Re: [PATCH 12/13] media: Clarify v4l2-async subdevice addition API

[Sakari Ailus <sakari.ailus@linux.intel.com>]

On Thu, Jan 14, 2021 at 10:39:33AM -0300, Ezequiel Garcia wrote:
> On Thu, 2021-01-14 at 04:21 +0200, Laurent Pinchart wrote:
> > Hi Ezequiel,
> > 
> > Thank you for the patch.
> > 
> > On Tue, Jan 12, 2021 at 10:23:38AM -0300, 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>
> > > ---
> > >  .../driver-api/media/v4l2-subdev.rst          | 38 ++++++++++++++++---
> > >  include/media/v4l2-async.h                    | 12 +++++-
> > >  2 files changed, 43 insertions(+), 7 deletions(-)
> > > 
> > > diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
> > > index bb5b1a7cdfd9..5ddf9de4fcf7 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:
> > 
> > You could reflow this to
> > 
> > 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_devname_subdev`,
> > > +:c:func:`v4l2_async_notifier_add_fwnode_subdev` or
> > > +:c:func:`v4l2_async_notifier_add_i2c_subdev`.
> > 
> > Should you also list v4l2_async_notifier_add_fwnode_remote_subdev() (and
> 
> Yes.
> 
> > possibly v4l2_async_notifier_parse_fwnode_endpoints()) here ?
> > 
> 
> Unsure. I'd rather not document this one, as it's deprecated
> and we want to remove it.

This document is here to guide people to use the right functions and that
isn't one of them. So it shouldn't be added here.

-- 
Regards,

Sakari Ailus