Commit 20936f77 authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

media: v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation 



Rework the documentation of v4l2_fwnode_endpoint_parse for better
readability, usefulness and correctness.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: default avatarNiklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Reviewed-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent c2505342

include/media/v4l2-fwnode.h

+40 −22
Original line number Diff line number Diff line
@@ -219,17 +219,26 @@ struct v4l2_fwnode_connector { 
 * @vep: pointer to the V4L2 fwnode data structure

 *

 * This function parses the V4L2 fwnode endpoint specific parameters from the

 * firmware. The caller is responsible for assigning @vep.bus_type to a valid

 * media bus type. The caller may also set the default configuration for the

 * endpoint --- a configuration that shall be in line with the DT binding

 * documentation. Should a device support multiple bus types, the caller may

 * call this function once the correct type is found --- with a default

 * configuration valid for that type.

 *

 * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS

 * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,

 * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is

 * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!

 * firmware. There are two ways to use this function, either by letting it

 * obtain the type of the bus (by setting the @vep.bus_type field to

 * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum

 * v4l2_mbus_type types.

 *

 * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"

 * property to determine the type when it is available. The caller is

 * responsible for validating the contents of @vep.bus_type field after the call

 * returns.

 *

 * As a deprecated functionality to support older DT bindings without "bus-type"

 * property for devices that support multiple types, if the "bus-type" property

 * does not exist, the function will attempt to guess the type based on the

 * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW

 * DRIVERS OR BINDINGS.

 *

 * It is also possible to set @vep.bus_type corresponding to an actual bus. In

 * this case the function will only attempt to parse properties related to this

 * bus, and it will return an error if the value of the "bus-type" property

 * corresponds to a different bus.

 *

 * The caller is required to initialise all fields of @vep, either with

 * explicitly values, or by zeroing them.
@@ -264,17 +273,26 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 
 * @vep: pointer to the V4L2 fwnode data structure

 *

 * This function parses the V4L2 fwnode endpoint specific parameters from the

 * firmware. The caller is responsible for assigning @vep.bus_type to a valid

 * media bus type. The caller may also set the default configuration for the

 * endpoint --- a configuration that shall be in line with the DT binding

 * documentation. Should a device support multiple bus types, the caller may

 * call this function once the correct type is found --- with a default

 * configuration valid for that type.

 *

 * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS

 * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,

 * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is

 * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!

 * firmware. There are two ways to use this function, either by letting it

 * obtain the type of the bus (by setting the @vep.bus_type field to

 * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum

 * v4l2_mbus_type types.

 *

 * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"

 * property to determine the type when it is available. The caller is

 * responsible for validating the contents of @vep.bus_type field after the call

 * returns.

 *

 * As a deprecated functionality to support older DT bindings without "bus-type"

 * property for devices that support multiple types, if the "bus-type" property

 * does not exist, the function will attempt to guess the type based on the

 * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW

 * DRIVERS OR BINDINGS.

 *

 * It is also possible to set @vep.bus_type corresponding to an actual bus. In

 * this case the function will only attempt to parse properties related to this

 * bus, and it will return an error if the value of the "bus-type" property

 * corresponds to a different bus.

 *

 * The caller is required to initialise all fields of @vep, either with

 * explicitly values, or by zeroing them.