Commit 3e90e5ad authored by Ezequiel Garcia's avatar Ezequiel Garcia Committed by Mauro Carvalho Chehab
Browse files

media: Clarify v4l2-async subdevice addition API 



Now that most users of v4l2_async_notifier_add_subdev have been converted,
let's fix the documentation so it's more clear how the v4l2-async API
should be used.

Document functions that drivers should use, and their purpose.

Signed-off-by: default avatarEzequiel Garcia <ezequiel@collabora.com>
Reviewed-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: default avatarHelen Koike <helen.koike@collabora.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent b01edcbd

Documentation/driver-api/media/v4l2-subdev.rst

+39 −9
Original line number Diff line number Diff line
@@ -197,15 +197,45 @@ unregister the notifier the driver has to call 
takes two arguments: a pointer to struct :c:type:`v4l2_device` and a

pointer to struct :c:type:`v4l2_async_notifier`.



Before registering the notifier, bridge drivers must do two things:

first, the notifier must be initialized using the

:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then

begin to form a list of subdevice descriptors that the bridge device

needs for its operation. Subdevice descriptors are added to the notifier

using the :c:func:`v4l2_async_notifier_add_subdev` call. This function

takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`,

and a pointer to the subdevice descripter, which is of type struct

:c:type:`v4l2_async_subdev`.

Before registering the notifier, bridge drivers must do two things: first, the

notifier must be initialized using the :c:func:`v4l2_async_notifier_init`.

Second, bridge drivers can then begin to form a list of subdevice descriptors

that the bridge device needs for its operation. Several functions are available

to add subdevice descriptors to a notifier, depending on the type of device and

the needs of the driver.



:c:func:`v4l2_async_notifier_add_fwnode_remote_subdev` and

:c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for

registering their async sub-devices with the notifier.



:c:func:`v4l2_async_register_subdev_sensor_common` is a helper function for

sensor drivers registering their own async sub-device, but it also registers a

notifier and further registers async sub-devices for lens and flash devices

found in firmware. The notifier for the sub-device is unregistered with the

async sub-device.



These functions allocate an async sub-device descriptor which is of type struct

:c:type:`v4l2_async_subdev` embedded in a driver-specific struct. The &struct

:c:type:`v4l2_async_subdev` shall be the first member of this struct:



.. code-block:: c



	struct my_async_subdev {

		struct v4l2_async_subdev asd;

		...

	};



	struct my_async_subdev *my_asd;

	struct fwnode_handle *ep;



	...



	my_asd = v4l2_async_notifier_add_fwnode_remote_subdev(&notifier, ep,

							      struct my_async_subdev);

	fwnode_handle_put(ep);



	if (IS_ERR(asd))

		return PTR_ERR(asd);



The V4L2 core will then use these descriptors to match asynchronously

registered subdevices to them. If a match is detected the ``.bound()``

include/media/v4l2-async.h

+11 −4
Original line number Diff line number Diff line
@@ -128,7 +128,12 @@ void v4l2_async_debug_init(struct dentry *debugfs_dir); 
 * @notifier: pointer to &struct v4l2_async_notifier

 *

 * This function initializes the notifier @asd_list. It must be called

 * before the first call to @v4l2_async_notifier_add_subdev.

 * before adding a subdevice to a notifier, using one of:

 * @v4l2_async_notifier_add_fwnode_remote_subdev,

 * @v4l2_async_notifier_add_fwnode_subdev,

 * @v4l2_async_notifier_add_i2c_subdev,

 * @__v4l2_async_notifier_add_subdev or

 * @v4l2_async_notifier_parse_fwnode_endpoints.

 */

void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier);
@@ -262,9 +267,11 @@ void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier); 
 * sub-devices allocated for the purposes of the notifier but not the notifier

 * itself. The user is responsible for calling this function to clean up the

 * notifier after calling

 * @v4l2_async_notifier_add_subdev,

 * @v4l2_async_notifier_parse_fwnode_endpoints or

 * @v4l2_fwnode_reference_parse_sensor_common.

 * @v4l2_async_notifier_add_fwnode_remote_subdev,

 * @v4l2_async_notifier_add_fwnode_subdev,

 * @v4l2_async_notifier_add_i2c_subdev,

 * @__v4l2_async_notifier_add_subdev or

 * @v4l2_async_notifier_parse_fwnode_endpoints.

 *

 * There is no harm from calling v4l2_async_notifier_cleanup in other

 * cases as long as its memory has been zeroed after it has been