iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

media: v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation

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

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Sakari Ailus 2020-09-30 16:28:49 +02:00 committed by Mauro Carvalho Chehab
parent c2505342ee
commit 20936f7734
1 changed files with 38 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
include/media/v4l2-fwnode.h
View File

@ -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.
* 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.
*
* 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!
* 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.
* 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.
*
* 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!
* 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.