From patchwork Mon Sep 21 20:21:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 11790865 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id F023059D for ; Mon, 21 Sep 2020 20:39:08 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E216921BE5 for ; Mon, 21 Sep 2020 20:39:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727531AbgIUUjE (ORCPT ); Mon, 21 Sep 2020 16:39:04 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:39198 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727483AbgIUUjD (ORCPT ); Mon, 21 Sep 2020 16:39:03 -0400 Received: from [78.134.51.148] (port=50434 helo=melee.fritz.box) by hostingweb31.netsons.net with esmtpa (Exim 4.93) (envelope-from ) id 1kKSJn-0009Ai-UR; Mon, 21 Sep 2020 22:21:48 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jacopo Mondi , Jacopo Mondi Subject: [PATCH v2 1/4] media: docs: v4l2-subdev: fix typo Date: Mon, 21 Sep 2020 22:21:31 +0200 Message-Id: <20200921202134.9792-1-luca@lucaceresoli.net> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - hostingweb31.netsons.net X-AntiAbuse: Original Domain - vger.kernel.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - lucaceresoli.net X-Get-Message-Sender-Via: hostingweb31.netsons.net: authenticated_id: luca+lucaceresoli.net/only user confirmed/virtual account not confirmed X-Authenticated-Sender: hostingweb31.netsons.net: luca@lucaceresoli.net X-Source: X-Source-Args: X-Source-Dir: Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Fix "will to" -> "will do". Reviewed-by: Jacopo Mondi Signed-off-by: Luca Ceresoli --- 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 ` is ``NULL``, ``-ENOIOCTLCMD`` if either :c:type:`sd `->core or :c:type:`sd `->core->g_std is ``NULL``, or the actual result of the :c:type:`sd `->ops->core->g_std ops. From patchwork Mon Sep 21 20:21:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 11790861 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 23D4D618 for ; Mon, 21 Sep 2020 20:38:57 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 15C5F21BE5 for ; Mon, 21 Sep 2020 20:38:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727302AbgIUUix (ORCPT ); Mon, 21 Sep 2020 16:38:53 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:34391 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727294AbgIUUiu (ORCPT ); Mon, 21 Sep 2020 16:38:50 -0400 Received: from [78.134.51.148] (port=50434 helo=melee.fritz.box) by hostingweb31.netsons.net with esmtpa (Exim 4.93) (envelope-from ) id 1kKSJq-0009Ai-1m; Mon, 21 Sep 2020 22:21:50 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jacopo Mondi Subject: [PATCH v2 2/4] media: docs: v4l2-subdev: fix typo Date: Mon, 21 Sep 2020 22:21:32 +0200 Message-Id: <20200921202134.9792-2-luca@lucaceresoli.net> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200921202134.9792-1-luca@lucaceresoli.net> References: <20200921202134.9792-1-luca@lucaceresoli.net> MIME-Version: 1.0 X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - hostingweb31.netsons.net X-AntiAbuse: Original Domain - vger.kernel.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - lucaceresoli.net X-Get-Message-Sender-Via: hostingweb31.netsons.net: authenticated_id: luca+lucaceresoli.net/only user confirmed/virtual account not confirmed X-Authenticated-Sender: hostingweb31.netsons.net: luca@lucaceresoli.net X-Source: X-Source-Args: X-Source-Dir: Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Fix "Helper functions exists" -> "Helper functions exist". Signed-off-by: Luca Ceresoli --- 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 From patchwork Mon Sep 21 20:21:33 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 11790863 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0FD0D59D for ; Mon, 21 Sep 2020 20:39:00 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id F077221D7A for ; Mon, 21 Sep 2020 20:38:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727348AbgIUUi4 (ORCPT ); Mon, 21 Sep 2020 16:38:56 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:41642 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727294AbgIUUi4 (ORCPT ); Mon, 21 Sep 2020 16:38:56 -0400 Received: from [78.134.51.148] (port=50434 helo=melee.fritz.box) by hostingweb31.netsons.net with esmtpa (Exim 4.93) (envelope-from ) id 1kKSJq-0009Ai-Fi; Mon, 21 Sep 2020 22:21:50 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jacopo Mondi Subject: [PATCH v2 3/4] media: docs: v4l2-subdev: move "Subdev registration" to a subsection Date: Mon, 21 Sep 2020 22:21:33 +0200 Message-Id: <20200921202134.9792-3-luca@lucaceresoli.net> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200921202134.9792-1-luca@lucaceresoli.net> References: <20200921202134.9792-1-luca@lucaceresoli.net> MIME-Version: 1.0 X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - hostingweb31.netsons.net X-AntiAbuse: Original Domain - vger.kernel.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - lucaceresoli.net X-Get-Message-Sender-Via: hostingweb31.netsons.net: authenticated_id: luca+lucaceresoli.net/only user confirmed/virtual account not confirmed X-Authenticated-Sender: hostingweb31.netsons.net: luca@lucaceresoli.net X-Source: X-Source-Args: X-Source-Dir: Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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 Signed-off-by: Luca Ceresoli --- 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 ` @@ -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 From patchwork Mon Sep 21 20:21:34 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 11790867 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7F714618 for ; Mon, 21 Sep 2020 20:39:09 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6CACE21D7A for ; Mon, 21 Sep 2020 20:39:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727435AbgIUUjC (ORCPT ); Mon, 21 Sep 2020 16:39:02 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:49684 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727388AbgIUUi6 (ORCPT ); Mon, 21 Sep 2020 16:38:58 -0400 Received: from [78.134.51.148] (port=50434 helo=melee.fritz.box) by hostingweb31.netsons.net with esmtpa (Exim 4.93) (envelope-from ) id 1kKSJq-0009Ai-RG; Mon, 21 Sep 2020 22:21:50 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jacopo Mondi Subject: [PATCH v2 4/4] media: docs: v4l2-subdev: move calling ops to a subsection Date: Mon, 21 Sep 2020 22:21:34 +0200 Message-Id: <20200921202134.9792-4-luca@lucaceresoli.net> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200921202134.9792-1-luca@lucaceresoli.net> References: <20200921202134.9792-1-luca@lucaceresoli.net> MIME-Version: 1.0 X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - hostingweb31.netsons.net X-AntiAbuse: Original Domain - vger.kernel.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - lucaceresoli.net X-Get-Message-Sender-Via: hostingweb31.netsons.net: authenticated_id: luca+lucaceresoli.net/only user confirmed/virtual account not confirmed X-Authenticated-Sender: hostingweb31.netsons.net: luca@lucaceresoli.net X-Source: X-Source-Args: X-Source-Dir: Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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 Signed-off-by: Luca Ceresoli --- 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 `->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 -----------------------------