| Message ID | 20210118015258.3993-13-ezequiel@collabora.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | V4L2 Async notifier API cleanup | expand |
Hi Ezequiel, On 1/17/21 10:52 PM, Ezequiel Garcia wrote: > 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. > > Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com> > Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > --- > .../driver-api/media/v4l2-subdev.rst | 38 ++++++++++++++++--- > include/media/v4l2-async.h | 11 ++++-- > 2 files changed, 41 insertions(+), 8 deletions(-) > > diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst > index bb5b1a7cdfd9..47a70538d758 100644 > --- a/Documentation/driver-api/media/v4l2-subdev.rst > +++ b/Documentation/driver-api/media/v4l2-subdev.rst > @@ -204,11 +204,39 @@ 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`. > +needs for its operation. Several functions are available, to add subdevice > +descriptors to a notifier, depending on the type of device: > +:c:func:`v4l2_async_notifier_add_fwnode_subdev`, > +:c:func:`v4l2_async_notifier_add_fwnode_remote_subdev` or > +:c:func:`v4l2_async_notifier_add_i2c_subdev`. > + > +These functions allocate a subdevice descriptor, which is of > +type struct :c:type:`v4l2_async_subdev`, and take a size argument > +which can be used to embed the descriptor in a driver-specific > +async subdevice 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 v4l2_async_subdev *asd; > + struct fwnode_handle *ep; > + > + ... > + > + asd = v4l2_async_notifier_add_fwnode_subdev( > + ¬ifier, ep, sizeof(*my_asd)); > + fwnode_handle_put(ep); > + > + if (IS_ERR(asd)) > + return PTR_ERR(asd); > + > + my_asd = container_of(asd, struct my_async_subdev, asd); > > The V4L2 core will then use these descriptors to match asynchronously > registered subdevices to them. If a match is detected the ``.bound()`` > diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h > index 2144502c95e0..7b45427aafb5 100644 > --- a/include/media/v4l2-async.h > +++ b/include/media/v4l2-async.h > @@ -120,7 +120,11 @@ struct v4l2_async_notifier { > * @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_i2c_subdev, > + * @v4l2_async_notifier_add_fwnode_subdev, > + * @v4l2_async_notifier_add_fwnode_remote_subdev or > + * @v4l2_async_notifier_parse_fwnode_sensor_common. Please see comment on 11/14. Maybe we could remove v4l2_async_notifier_parse_fwnode_sensor_common() from the kapi and remove it from this comment. Regards, Helen > */ > void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier); > > @@ -240,8 +244,9 @@ 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_async_notifier_add_i2c_subdev, > + * @v4l2_async_notifier_add_fwnode_subdev, > + * @v4l2_async_notifier_add_fwnode_remote_subdev or > * @v4l2_async_notifier_parse_fwnode_sensor_common. > * > * There is no harm from calling v4l2_async_notifier_cleanup in other >
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index bb5b1a7cdfd9..47a70538d758 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -204,11 +204,39 @@ 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`. +needs for its operation. Several functions are available, to add subdevice +descriptors to a notifier, depending on the type of device: +:c:func:`v4l2_async_notifier_add_fwnode_subdev`, +:c:func:`v4l2_async_notifier_add_fwnode_remote_subdev` or +:c:func:`v4l2_async_notifier_add_i2c_subdev`. + +These functions allocate a subdevice descriptor, which is of +type struct :c:type:`v4l2_async_subdev`, and take a size argument +which can be used to embed the descriptor in a driver-specific +async subdevice 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 v4l2_async_subdev *asd; + struct fwnode_handle *ep; + + ... + + asd = v4l2_async_notifier_add_fwnode_subdev( + ¬ifier, ep, sizeof(*my_asd)); + fwnode_handle_put(ep); + + if (IS_ERR(asd)) + return PTR_ERR(asd); + + my_asd = container_of(asd, struct my_async_subdev, asd); The V4L2 core will then use these descriptors to match asynchronously registered subdevices to them. If a match is detected the ``.bound()`` diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h index 2144502c95e0..7b45427aafb5 100644 --- a/include/media/v4l2-async.h +++ b/include/media/v4l2-async.h @@ -120,7 +120,11 @@ struct v4l2_async_notifier { * @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_i2c_subdev, + * @v4l2_async_notifier_add_fwnode_subdev, + * @v4l2_async_notifier_add_fwnode_remote_subdev or + * @v4l2_async_notifier_parse_fwnode_sensor_common. */ void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier); @@ -240,8 +244,9 @@ 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_async_notifier_add_i2c_subdev, + * @v4l2_async_notifier_add_fwnode_subdev, + * @v4l2_async_notifier_add_fwnode_remote_subdev or * @v4l2_async_notifier_parse_fwnode_sensor_common. * * There is no harm from calling v4l2_async_notifier_cleanup in other