Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 2e6e3932 authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

media: v4l: fwnode: Update V4L2 fwnode endpoint parsing documentation 



The semantics of v4l2_fwnode_endpoint_parse() and
v4l2_fwnode_endpoint_alloc_parse() have changed slightly: they now take
the bus type from the user as well as a default configuration for the bus
that shall reflect the DT binding defaults. Document this.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Tested-by: default avatarSteve Longerbeam <steve_longerbeam@mentor.com>
Tested-by: default avatarJacopo Mondi <jacopo+renesas@jmondi.org>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent edc6d56c

include/media/v4l2-fwnode.h

+37 −19
Original line number Diff line number Diff line
@@ -131,21 +131,30 @@ struct v4l2_fwnode_link { 
 * @fwnode: pointer to the endpoint's fwnode handle

 * @vep: pointer to the V4L2 fwnode data structure

 *

 * All properties are optional. If none are found, we don't set any flags. This

 * means the port has a static configuration and no properties have to be

 * specified explicitly. If any properties that identify the bus as parallel

 * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if

 * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we

 * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a

 * reference to @fwnode.

 *

 * The caller must set the bus_type field of @vep to zero.

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

 *

 * As a compatibility means guessing the bus type is also supported by setting

 * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default

 * configuration in this case as the defaults are specific to a given bus type.

 * This functionality is deprecated and should not be used in new drivers and it

 * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses.

 *

 * The function does not change the V4L2 fwnode endpoint state if it fails.

 *

 * NOTE: This function does not parse properties the size of which is variable

 * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in

 * new drivers instead.

 *

 * Return: 0 on success or a negative error code on failure.

 * Return: %0 on success or a negative error code on failure:

 *	   %-ENOMEM on memory allocation failure

 *	   %-EINVAL on parsing failure

 *	   %-ENXIO on mismatching bus types

 */

int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,

			       struct v4l2_fwnode_endpoint *vep);
@@ -165,15 +174,21 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 
 * @fwnode: pointer to the endpoint's fwnode handle

 * @vep: pointer to the V4L2 fwnode data structure

 *

 * All properties are optional. If none are found, we don't set any flags. This

 * means the port has a static configuration and no properties have to be

 * specified explicitly. If any properties that identify the bus as parallel

 * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if

 * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we

 * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a

 * reference to @fwnode.

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

 *

 * As a compatibility means guessing the bus type is also supported by setting

 * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default

 * configuration in this case as the defaults are specific to a given bus type.

 * This functionality is deprecated and should not be used in new drivers and it

 * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses.

 *

 * The caller must set the bus_type field of @vep to zero.

 * The function does not change the V4L2 fwnode endpoint state if it fails.

 *

 * v4l2_fwnode_endpoint_alloc_parse() has two important differences to

 * v4l2_fwnode_endpoint_parse():
@@ -183,7 +198,10 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 
 * 2. The memory it has allocated to store the variable size data must be freed

 *    using v4l2_fwnode_endpoint_free() when no longer needed.

 *

 * Return: 0 on success or a negative error code on failure.

 * Return: %0 on success or a negative error code on failure:

 *	   %-ENOMEM on memory allocation failure

 *	   %-EINVAL on parsing failure

 *	   %-ENXIO on mismatching bus types

 */

int v4l2_fwnode_endpoint_alloc_parse(

	struct fwnode_handle *fwnode, struct v4l2_fwnode_endpoint *vep);