[PATCH v2 1/4] media: docs: v4l2-subdev: fix typo

[PATCH v2 1/4] media: docs: v4l2-subdev: fix typo

[Luca Ceresoli]

Fix "will to" -> "will do".

Reviewed-by: Jacopo Mondi <jacopo+renesas@jmondi.org>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

---

Changes in v2: none
---
 Documentation/driver-api/media/v4l2-subdev.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index bc7e1fc40a9d..9a7dddd97f5a 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -191,7 +191,7 @@ but it is better and easier to use this macro:
 
 	err = v4l2_subdev_call(sd, core, g_std, &norm);
 
-The macro will to the right ``NULL`` pointer checks and returns ``-ENODEV``
+The macro will do the right ``NULL`` pointer checks and returns ``-ENODEV``
 if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
 :c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the
 :c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
-- 
2.28.0

[PATCH v2 2/4] media: docs: v4l2-subdev: fix typo

[Luca Ceresoli]

Fix "Helper functions exists" -> "Helper functions exist".

Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

---

This patch is new in v2
---
 Documentation/driver-api/media/v4l2-subdev.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 9a7dddd97f5a..9ea16a8c3bde 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -34,7 +34,7 @@ provides host private data for that purpose that can be accessed with
 From the bridge driver perspective, you load the sub-device module and somehow
 obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
 ``i2c_get_clientdata()``. For other buses something similar needs to be done.
-Helper functions exists for sub-devices on an I2C bus that do most of this
+Helper functions exist for sub-devices on an I2C bus that do most of this
 tricky work for you.
 
 Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers
-- 
2.28.0

[PATCH v2 3/4] media: docs: v4l2-subdev: move "Subdev registration" to a subsection

[Luca Ceresoli]

The subdev registration topic is pretty lengthy, and takes more than
half of the "V4L2 sub-devices" section. Help readers in finding their
way through the document by dedicating a subsection to
"Subdev registration".

Each of the two registration methods takes many paragraphs, but since
adding a subsubsection would be overkill, just emphasize them in bold.

Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

---

Changes in v2: none
---
 Documentation/driver-api/media/v4l2-subdev.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 9ea16a8c3bde..3adcd881cae5 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -138,6 +138,9 @@ ensures that width, height and the media bus pixel code are equal on both source
 and sink of the link. Subdev drivers are also free to use this function to
 perform the checks mentioned above in addition to their own checks.
 
+Subdev registration
+~~~~~~~~~~~~~~~~~~~
+
 There are currently two ways to register subdevices with the V4L2 core. The
 first (traditional) possibility is to have subdevices registered by bridge
 drivers. This can be done when the bridge driver has the complete information
@@ -157,7 +160,7 @@ below.
 Using one or the other registration method only affects the probing process, the
 run-time bridge-subdevice interaction is in both cases the same.
 
-In the synchronous case a device (bridge) driver needs to register the
+In the **synchronous** case a device (bridge) driver needs to register the
 :c:type:`v4l2_subdev` with the v4l2_device:
 
 	:c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
@@ -238,9 +241,9 @@ contain several subdevs that use an I2C bus, but also a subdev that is
 controlled through GPIO pins. This distinction is only relevant when setting
 up the device, but once the subdev is registered it is completely transparent.
 
-In the asynchronous case subdevice probing can be invoked independently of the
-bridge driver availability. The subdevice driver then has to verify whether all
-the requirements for a successful probing are satisfied. This can include a
+In the **asynchronous** case subdevice probing can be invoked independently of
+the bridge driver availability. The subdevice driver then has to verify whether
+all the requirements for a successful probing are satisfied. This can include a
 check for a master clock availability. If any of the conditions aren't satisfied
 the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
 attempts. Once all conditions are met the subdevice shall be registered using
-- 
2.28.0

[PATCH v2 4/4] media: docs: v4l2-subdev: move calling ops to a subsection

[Luca Ceresoli]

Documentation on how to call the subdev ops is currently in the middle of
synchronous and asynchronous registration. Move it to a dedicated
subsection after the registration methods.

Also move the final paragraph "The advantage of using v4l2_subdev..." to
the beginning of the new section as it has an introductory content.

Suggested-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>

---

Changes in v2:
 - replaces the simpler patch 3/3 upon suggestion by Jacopo
---
 .../driver-api/media/v4l2-subdev.rst          | 88 ++++++++++---------
 1 file changed, 46 insertions(+), 42 deletions(-)

diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 3adcd881cae5..21ee54bbec77 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -182,7 +182,51 @@ You can unregister a sub-device using:
 Afterwards the subdev module can be unloaded and
 :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
 
-You can call an ops function either directly:
+In the **asynchronous** case subdevice probing can be invoked independently of
+the bridge driver availability. The subdevice driver then has to verify whether
+all the requirements for a successful probing are satisfied. This can include a
+check for a master clock availability. If any of the conditions aren't satisfied
+the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
+attempts. Once all conditions are met the subdevice shall be registered using
+the :c:func:`v4l2_async_register_subdev` function. Unregistration is
+performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
+registered this way are stored in a global list of subdevices, ready to be
+picked up by bridge drivers.
+
+Bridge drivers in turn have to register a notifier object. This is
+performed using the :c:func:`v4l2_async_notifier_register` call. To
+unregister the notifier the driver has to call
+:c:func:`v4l2_async_notifier_unregister`. The former of the two functions
+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`.
+
+The V4L2 core will then use these descriptors to match asynchronously
+registered subdevices to them. If a match is detected the ``.bound()``
+notifier callback is called. After all subdevices have been located the
+.complete() callback is called. When a subdevice is removed from the
+system the .unbind() method is called. All three callbacks are optional.
+
+Calling subdev operations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
+does not contain any knowledge about the underlying hardware. So a driver might
+contain several subdevs that use an I2C bus, but also a subdev that is
+controlled through GPIO pins. This distinction is only relevant when setting
+up the device, but once the subdev is registered it is completely transparent.
+
+Once te subdev has been registered you can call an ops function either
+directly:
 
 .. code-block:: c
 
@@ -233,47 +277,7 @@ that needs it.
 If the sub-device needs to notify its v4l2_device parent of an event, then
 it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks
 whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
-Otherwise the result of the ``notify()`` call is returned.
-
-The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
-does not contain any knowledge about the underlying hardware. So a driver might
-contain several subdevs that use an I2C bus, but also a subdev that is
-controlled through GPIO pins. This distinction is only relevant when setting
-up the device, but once the subdev is registered it is completely transparent.
-
-In the **asynchronous** case subdevice probing can be invoked independently of
-the bridge driver availability. The subdevice driver then has to verify whether
-all the requirements for a successful probing are satisfied. This can include a
-check for a master clock availability. If any of the conditions aren't satisfied
-the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
-attempts. Once all conditions are met the subdevice shall be registered using
-the :c:func:`v4l2_async_register_subdev` function. Unregistration is
-performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
-registered this way are stored in a global list of subdevices, ready to be
-picked up by bridge drivers.
-
-Bridge drivers in turn have to register a notifier object. This is
-performed using the :c:func:`v4l2_async_notifier_register` call. To
-unregister the notifier the driver has to call
-:c:func:`v4l2_async_notifier_unregister`. The former of the two functions
-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`.
-
-The V4L2 core will then use these descriptors to match asynchronously
-registered subdevices to them. If a match is detected the ``.bound()``
-notifier callback is called. After all subdevices have been located the
-.complete() callback is called. When a subdevice is removed from the
-system the .unbind() method is called. All three callbacks are optional.
+Otherwise the result of the ``notify()`` call is return
 
 V4L2 sub-device userspace API
 -----------------------------
-- 
2.28.0

Re: [PATCH v2 4/4] media: docs: v4l2-subdev: move calling ops to a subsection

[Hans Verkuil]

On 21/09/2020 22:21, Luca Ceresoli wrote:
> Documentation on how to call the subdev ops is currently in the middle of
> synchronous and asynchronous registration. Move it to a dedicated
> subsection after the registration methods.
> 
> Also move the final paragraph "The advantage of using v4l2_subdev..." to
> the beginning of the new section as it has an introductory content.
> 
> Suggested-by: Jacopo Mondi <jacopo@jmondi.org>
> Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
> 
> ---
> 
> Changes in v2:
>  - replaces the simpler patch 3/3 upon suggestion by Jacopo
> ---
>  .../driver-api/media/v4l2-subdev.rst          | 88 ++++++++++---------
>  1 file changed, 46 insertions(+), 42 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
> index 3adcd881cae5..21ee54bbec77 100644
> --- a/Documentation/driver-api/media/v4l2-subdev.rst
> +++ b/Documentation/driver-api/media/v4l2-subdev.rst
> @@ -182,7 +182,51 @@ You can unregister a sub-device using:
>  Afterwards the subdev module can be unloaded and
>  :c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
>  
> -You can call an ops function either directly:
> +In the **asynchronous** case subdevice probing can be invoked independently of
> +the bridge driver availability. The subdevice driver then has to verify whether
> +all the requirements for a successful probing are satisfied. This can include a
> +check for a master clock availability. If any of the conditions aren't satisfied
> +the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
> +attempts. Once all conditions are met the subdevice shall be registered using
> +the :c:func:`v4l2_async_register_subdev` function. Unregistration is
> +performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
> +registered this way are stored in a global list of subdevices, ready to be
> +picked up by bridge drivers.
> +
> +Bridge drivers in turn have to register a notifier object. This is
> +performed using the :c:func:`v4l2_async_notifier_register` call. To
> +unregister the notifier the driver has to call
> +:c:func:`v4l2_async_notifier_unregister`. The former of the two functions
> +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`.
> +
> +The V4L2 core will then use these descriptors to match asynchronously
> +registered subdevices to them. If a match is detected the ``.bound()``
> +notifier callback is called. After all subdevices have been located the
> +.complete() callback is called. When a subdevice is removed from the
> +system the .unbind() method is called. All three callbacks are optional.
> +
> +Calling subdev operations
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
> +does not contain any knowledge about the underlying hardware. So a driver might
> +contain several subdevs that use an I2C bus, but also a subdev that is
> +controlled through GPIO pins. This distinction is only relevant when setting
> +up the device, but once the subdev is registered it is completely transparent.
> +
> +Once te subdev has been registered you can call an ops function either
> +directly:
>  
>  .. code-block:: c
>  
> @@ -233,47 +277,7 @@ that needs it.
>  If the sub-device needs to notify its v4l2_device parent of an event, then
>  it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks
>  whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
> -Otherwise the result of the ``notify()`` call is returned.
> -
> -The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
> -does not contain any knowledge about the underlying hardware. So a driver might
> -contain several subdevs that use an I2C bus, but also a subdev that is
> -controlled through GPIO pins. This distinction is only relevant when setting
> -up the device, but once the subdev is registered it is completely transparent.
> -
> -In the **asynchronous** case subdevice probing can be invoked independently of
> -the bridge driver availability. The subdevice driver then has to verify whether
> -all the requirements for a successful probing are satisfied. This can include a
> -check for a master clock availability. If any of the conditions aren't satisfied
> -the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
> -attempts. Once all conditions are met the subdevice shall be registered using
> -the :c:func:`v4l2_async_register_subdev` function. Unregistration is
> -performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
> -registered this way are stored in a global list of subdevices, ready to be
> -picked up by bridge drivers.
> -
> -Bridge drivers in turn have to register a notifier object. This is
> -performed using the :c:func:`v4l2_async_notifier_register` call. To
> -unregister the notifier the driver has to call
> -:c:func:`v4l2_async_notifier_unregister`. The former of the two functions
> -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`.
> -
> -The V4L2 core will then use these descriptors to match asynchronously
> -registered subdevices to them. If a match is detected the ``.bound()``
> -notifier callback is called. After all subdevices have been located the
> -.complete() callback is called. When a subdevice is removed from the
> -system the .unbind() method is called. All three callbacks are optional.
> +Otherwise the result of the ``notify()`` call is return

It looks like the last bit of this sentences was accidentally deleted.
"return" -> "returned."

I'll fix this up myself, no need for a new version of this patch.

Regards,

	Hans

>  
>  V4L2 sub-device userspace API
>  -----------------------------
>