From patchwork Thu Jun 13 14:18:18 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992075 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id E668814C0 for ; Thu, 13 Jun 2019 15:04:20 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D55CD20572 for ; Thu, 13 Jun 2019 15:04:20 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C9E7D2239C; Thu, 13 Jun 2019 15:04:20 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 68561212DB for ; Thu, 13 Jun 2019 15:04:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732920AbfFMPET (ORCPT ); Thu, 13 Jun 2019 11:04:19 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:39959 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732469AbfFMOSo (ORCPT ); Thu, 13 Jun 2019 10:18:44 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYq-0005He-UU; Thu, 13 Jun 2019 16:18:40 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 1/9] media: docs: v4l2-controls: fix sentence rendered in a nonsense way Date: Thu, 13 Jun 2019 16:18:18 +0200 Message-Id: <20190613141826.26775-1-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This sentence renders as: > Since such compound controls need to expose more information about > themselves than is possible with ioctls VIDIOC_QUERYCTRL, > VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU the VIDIOC_QUERY_EXT_CTRL ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^ > ioctl was added. This does not make sense. Fix by providing an explicit link text. This results in: > Since such compound controls need to expose more information about > themselves than is possible with VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU > the VIDIOC_QUERY_EXT_CTRL ioctl was added. Signed-off-by: Luca Ceresoli --- Documentation/media/uapi/v4l/extended-controls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 24274b398e63..0968aa9cd167 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -86,7 +86,7 @@ with compound types should only be used programmatically. Since such compound controls need to expose more information about themselves than is possible with -:ref:`VIDIOC_QUERYCTRL` the +:ref:`VIDIOC_QUERYCTRL and VIDIOC_QUERYMENU ` the :ref:`VIDIOC_QUERY_EXT_CTRL ` ioctl was added. In particular, this ioctl gives the dimensions of the N-dimensional array if this control consists of more than one element. From patchwork Thu Jun 13 14:18:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992089 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id AD70D14C0 for ; Thu, 13 Jun 2019 15:04:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9B0B320499 for ; Thu, 13 Jun 2019 15:04:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 8F694205A9; Thu, 13 Jun 2019 15:04:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 360DA20499 for ; Thu, 13 Jun 2019 15:04:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732555AbfFMPEs (ORCPT ); Thu, 13 Jun 2019 11:04:48 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:60065 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732468AbfFMOSo (ORCPT ); Thu, 13 Jun 2019 10:18:44 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYr-0005He-4g; Thu, 13 Jun 2019 16:18:41 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 2/9] media: docs: v4l2-controls: remove repeated ioctl names Date: Thu, 13 Jun 2019 16:18:19 +0200 Message-Id: <20190613141826.26775-2-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Mentioning :ref:`VIDIOC_QUERYCTRL` renders all the three related ioctls. Explicitly adding VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU will make them render twice, so remove them Signed-off-by: Luca Ceresoli --- Documentation/media/uapi/v4l/extended-controls.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 0968aa9cd167..802a405aa535 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -96,9 +96,7 @@ if this control consists of more than one element. #. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use - the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL - `) and :ref:`VIDIOC_QUERYMENU ` - ioctls to check this. + :ref:`VIDIOC_QUERYCTRL` to check this. #. It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` From patchwork Thu Jun 13 14:18:20 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992081 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5037414BB for ; Thu, 13 Jun 2019 15:04:44 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3E75421C9A for ; Thu, 13 Jun 2019 15:04:44 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 263932228E; Thu, 13 Jun 2019 15:04:44 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C7C29219AC for ; Thu, 13 Jun 2019 15:04:43 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732865AbfFMPET (ORCPT ); Thu, 13 Jun 2019 11:04:19 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:43368 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732467AbfFMOSo (ORCPT ); Thu, 13 Jun 2019 10:18:44 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYr-0005He-D0; Thu, 13 Jun 2019 16:18:41 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 3/9] media: docs: v4l2-controls: fix indentation Date: Thu, 13 Jun 2019 16:18:20 +0200 Message-Id: <20190613141826.26775-3-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Fix indentation in example C code. Signed-off-by: Luca Ceresoli --- Documentation/media/uapi/v4l/extended-controls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 802a405aa535..3db283eedcaa 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -142,7 +142,7 @@ control class is found: while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; - /* ... */ + /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; } From patchwork Thu Jun 13 14:18:21 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992079 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 82C1D14BB for ; Thu, 13 Jun 2019 15:04:42 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 71D3620499 for ; Thu, 13 Jun 2019 15:04:42 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 65E0721EEB; Thu, 13 Jun 2019 15:04:42 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0D9A821C9A for ; Thu, 13 Jun 2019 15:04:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732939AbfFMPEU (ORCPT ); Thu, 13 Jun 2019 11:04:20 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:53083 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732470AbfFMOSo (ORCPT ); Thu, 13 Jun 2019 10:18:44 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYr-0005He-L4; Thu, 13 Jun 2019 16:18:41 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 4/9] media: docs: v4l2-controls: add links to structs Date: Thu, 13 Jun 2019 16:18:21 +0200 Message-Id: <20190613141826.26775-4-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This section lacks links to struct definitions. Add one where each struct is introduced. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 64ab99abf0b6..0c3f486727ed 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -26,8 +26,9 @@ The control framework was created in order to implement all the rules of the V4L2 specification with respect to controls in a central place. And to make life as easy as possible for the driver developer. -Note that the control framework relies on the presence of a struct v4l2_device -for V4L2 drivers and struct v4l2_subdev for sub-device drivers. +Note that the control framework relies on the presence of a struct +:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +sub-device drivers. Objects in the framework @@ -35,12 +36,13 @@ Objects in the framework There are two main objects: -The v4l2_ctrl object describes the control properties and keeps track of the -control's value (both the current value and the proposed new value). +The :c:type:`v4l2_ctrl` object describes the control properties and keeps +track of the control's value (both the current value and the proposed new +value). -v4l2_ctrl_handler is the object that keeps track of controls. It maintains a -list of v4l2_ctrl objects that it owns and another list of references to -controls, possibly to controls owned by other handlers. +:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It +maintains a list of v4l2_ctrl objects that it owns and another list of +references to controls, possibly to controls owned by other handlers. Basic usage for V4L2 and sub-device drivers @@ -242,7 +244,7 @@ initializes the hardware to the default control values. It is recommended that you do this as this ensures that both the internal data structures and the hardware are in sync. -4) Finally: implement the v4l2_ctrl_ops +4) Finally: implement the :c:type:`v4l2_ctrl_ops` .. code-block:: none From patchwork Thu Jun 13 14:18:22 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992093 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 567471515 for ; Thu, 13 Jun 2019 15:05:15 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 44DBA201A4 for ; Thu, 13 Jun 2019 15:05:15 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 3978B204FE; Thu, 13 Jun 2019 15:05:15 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2ED6C204C4 for ; Thu, 13 Jun 2019 15:05:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732926AbfFMPEz (ORCPT ); Thu, 13 Jun 2019 11:04:55 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:43572 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732471AbfFMOSn (ORCPT ); Thu, 13 Jun 2019 10:18:43 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYr-0005He-Rc; Thu, 13 Jun 2019 16:18:41 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 5/9] media: docs: v4l2-controls: rearrange control initialization sequence Date: Thu, 13 Jun 2019 16:18:22 +0200 Message-Id: <20190613141826.26775-5-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The code snippet showing how to add controls to the driver’s top-level struct is present twice, but only the second time it is split in the V4L2 and subdev cases. Consolidate everything at the beginning. Also remove the "Where foo->bar is of type struct baz" sentences, this obvious from the code. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 40 +++++++++------------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 0c3f486727ed..5281c9b1fd66 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -52,15 +52,29 @@ Basic usage for V4L2 and sub-device drivers 1.1) Add the handler to your driver's top-level struct: +For V4L2 drivers: + .. code-block:: none struct foo_dev { + ... + struct v4l2_device v4l2_dev; ... struct v4l2_ctrl_handler ctrl_handler; ... }; - struct foo_dev *foo; +For sub-device drivers: + +.. code-block:: none + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; 1.2) Initialize the handler: @@ -74,43 +88,23 @@ information. It is a hint only. 1.3) Hook the control handler into the driver: -1.3.1) For V4L2 drivers do this: +For V4L2 drivers: .. code-block:: none - struct foo_dev { - ... - struct v4l2_device v4l2_dev; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; - foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; -Where foo->v4l2_dev is of type struct v4l2_device. - Finally, remove all control functions from your v4l2_ioctl_ops (if any): vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. Those are now no longer needed. -1.3.2) For sub-device drivers do this: +For sub-device drivers: .. code-block:: none - struct foo_dev { - ... - struct v4l2_subdev sd; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; - foo->sd.ctrl_handler = &foo->ctrl_handler; -Where foo->sd is of type struct v4l2_subdev. - 1.4) Clean up the handler at the end: .. code-block:: none From patchwork Thu Jun 13 14:18:23 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992087 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 03D5E14BB for ; Thu, 13 Jun 2019 15:04:48 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E5F172228E for ; Thu, 13 Jun 2019 15:04:47 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id DA8DB2239C; Thu, 13 Jun 2019 15:04:47 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5AB9522638 for ; Thu, 13 Jun 2019 15:04:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732594AbfFMPET (ORCPT ); Thu, 13 Jun 2019 11:04:19 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:52035 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732472AbfFMOSq (ORCPT ); Thu, 13 Jun 2019 10:18:46 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYs-0005He-3L; Thu, 13 Jun 2019 16:18:42 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 6/9] media: docs: v4l2-controls: add links to functions Date: Thu, 13 Jun 2019 16:18:23 +0200 Message-Id: <20190613141826.26775-6-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This section lacks links to functions. Add one to simplify reading. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 67 +++++++++++----------- 1 file changed, 35 insertions(+), 32 deletions(-) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 5281c9b1fd66..41c0fd4009e9 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -114,7 +114,7 @@ For sub-device drivers: 2) Add controls: -You add non-menu controls by calling v4l2_ctrl_new_std: +You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: .. code-block:: none @@ -122,7 +122,8 @@ You add non-menu controls by calling v4l2_ctrl_new_std: const struct v4l2_ctrl_ops *ops, u32 id, s32 min, s32 max, u32 step, s32 def); -Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: +Menu and integer menu controls are added by calling +:c:func:`v4l2_ctrl_new_std_menu`: .. code-block:: none @@ -131,7 +132,7 @@ Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: u32 id, s32 max, s32 skip_mask, s32 def); Menu controls with a driver specific menu are added by calling -v4l2_ctrl_new_std_menu_items: +:c:func:`v4l2_ctrl_new_std_menu_items`: .. code-block:: none @@ -141,7 +142,7 @@ v4l2_ctrl_new_std_menu_items: s32 skip_mask, s32 def, const char * const *qmenu); Integer menu controls with a driver specific menu can be added by calling -v4l2_ctrl_new_int_menu: +:c:func:`v4l2_ctrl_new_int_menu`: .. code-block:: none @@ -149,7 +150,8 @@ v4l2_ctrl_new_int_menu: const struct v4l2_ctrl_ops *ops, u32 id, s32 max, s32 def, const s64 *qmenu_int); -These functions are typically called right after the v4l2_ctrl_handler_init: +These functions are typically called right after the +:c:func:`v4l2_ctrl_handler_init`: .. code-block:: none @@ -188,33 +190,34 @@ These functions are typically called right after the v4l2_ctrl_handler_init: return err; } -The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new -control, but if you do not need to access the pointer outside the control ops, -then there is no need to store it. - -The v4l2_ctrl_new_std function will fill in most fields based on the control -ID except for the min, max, step and default values. These are passed in the -last four arguments. These values are driver specific while control attributes -like type, name, flags are all global. The control's current value will be set -to the default value. - -The v4l2_ctrl_new_std_menu function is very similar but it is used for menu -controls. There is no min argument since that is always 0 for menu controls, -and instead of a step there is a skip_mask argument: if bit X is 1, then menu -item X is skipped. - -The v4l2_ctrl_new_int_menu function creates a new standard integer menu -control with driver-specific items in the menu. It differs from -v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes -as the last argument an array of signed 64-bit integers that form an exact -menu item list. - -The v4l2_ctrl_new_std_menu_items function is very similar to -v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver -specific menu for an otherwise standard menu control. A good example for this -control is the test pattern control for capture/display/sensors devices that -have the capability to generate test patterns. These test patterns are hardware -specific, so the contents of the menu will vary from device to device. +The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to +the new control, but if you do not need to access the pointer outside the +control ops, then there is no need to store it. + +The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on +the control ID except for the min, max, step and default values. These are +passed in the last four arguments. These values are driver specific while +control attributes like type, name, flags are all global. The control's +current value will be set to the default value. + +The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is +used for menu controls. There is no min argument since that is always 0 for +menu controls, and instead of a step there is a skip_mask argument: if bit +X is 1, then menu item X is skipped. + +The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard +integer menu control with driver-specific items in the menu. It differs +from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and +takes as the last argument an array of signed 64-bit integers that form an +exact menu item list. + +The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to +v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the +driver specific menu for an otherwise standard menu control. A good example +for this control is the test pattern control for capture/display/sensors +devices that have the capability to generate test patterns. These test +patterns are hardware specific, so the contents of the menu will vary from +device to device. Note that if something fails, the function will return NULL or an error and set ctrl_handler->error to the error code. If ctrl_handler->error was already From patchwork Thu Jun 13 14:18:24 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992073 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B0D4414BB for ; Thu, 13 Jun 2019 15:04:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9D1322223E for ; Thu, 13 Jun 2019 15:04:17 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 90B4C20572; Thu, 13 Jun 2019 15:04:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B9E682239C for ; Thu, 13 Jun 2019 15:04:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732832AbfFMPEE (ORCPT ); Thu, 13 Jun 2019 11:04:04 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:39624 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732473AbfFMOSr (ORCPT ); Thu, 13 Jun 2019 10:18:47 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYs-0005He-EY; Thu, 13 Jun 2019 16:18:42 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 7/9] media: docs: v4l2-controls: convert code blocks to C Date: Thu, 13 Jun 2019 16:18:24 +0200 Message-Id: <20190613141826.26775-7-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP All these code blocks contain C code, enable C formatting for a nicer reading. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 74 +++++++++++----------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 41c0fd4009e9..45541e05a0e7 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -54,7 +54,7 @@ Basic usage for V4L2 and sub-device drivers For V4L2 drivers: -.. code-block:: none +.. code-block:: c struct foo_dev { ... @@ -66,7 +66,7 @@ For V4L2 drivers: For sub-device drivers: -.. code-block:: none +.. code-block:: c struct foo_dev { ... @@ -78,7 +78,7 @@ For sub-device drivers: 1.2) Initialize the handler: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); @@ -90,7 +90,7 @@ information. It is a hint only. For V4L2 drivers: -.. code-block:: none +.. code-block:: c foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; @@ -101,13 +101,13 @@ Those are now no longer needed. For sub-device drivers: -.. code-block:: none +.. code-block:: c foo->sd.ctrl_handler = &foo->ctrl_handler; 1.4) Clean up the handler at the end: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_free(&foo->ctrl_handler); @@ -116,7 +116,7 @@ For sub-device drivers: You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -125,7 +125,7 @@ You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: Menu and integer menu controls are added by calling :c:func:`v4l2_ctrl_new_std_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -134,7 +134,7 @@ Menu and integer menu controls are added by calling Menu controls with a driver specific menu are added by calling :c:func:`v4l2_ctrl_new_std_menu_items`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items( struct v4l2_ctrl_handler *hdl, @@ -144,7 +144,7 @@ Menu controls with a driver specific menu are added by calling Integer menu controls with a driver specific menu can be added by calling :c:func:`v4l2_ctrl_new_int_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -153,7 +153,7 @@ Integer menu controls with a driver specific menu can be added by calling These functions are typically called right after the :c:func:`v4l2_ctrl_handler_init`: -.. code-block:: none +.. code-block:: c static const s64 exp_bias_qmenu[] = { -2, -1, 0, 1, 2 @@ -232,7 +232,7 @@ a bit faster that way. 3) Optionally force initial control setup: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_setup(&foo->ctrl_handler); @@ -243,7 +243,7 @@ the hardware are in sync. 4) Finally: implement the :c:type:`v4l2_ctrl_ops` -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_ops foo_ctrl_ops = { .s_ctrl = foo_s_ctrl, @@ -251,7 +251,7 @@ the hardware are in sync. Usually all you need is s_ctrl: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -304,7 +304,7 @@ Accessing Control Values The following union is used inside the control framework to access control values: -.. code-block:: none +.. code-block:: c union v4l2_ctrl_ptr { s32 *p_s32; @@ -316,7 +316,7 @@ values: The v4l2_ctrl struct contains these fields that can be used to access both current and new values: -.. code-block:: none +.. code-block:: c s32 val; struct { @@ -329,7 +329,7 @@ current and new values: If the control has a simple s32 type type, then: -.. code-block:: none +.. code-block:: c &ctrl->val == ctrl->p_new.p_s32 &ctrl->cur.val == ctrl->p_cur.p_s32 @@ -353,7 +353,7 @@ exception is for controls that return a volatile register such as a signal strength read-out that changes continuously. In that case you will need to implement g_volatile_ctrl like this: -.. code-block:: none +.. code-block:: c static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) { @@ -371,7 +371,7 @@ changes. To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: -.. code-block:: none +.. code-block:: c ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); if (ctrl) @@ -392,7 +392,7 @@ not to introduce deadlocks. Outside of the control ops you have to go through to helper functions to get or set a single control value safely in your driver: -.. code-block:: none +.. code-block:: c s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); @@ -403,7 +403,7 @@ will result in a deadlock since these helpers lock the handler as well. You can also take the handler lock yourself: -.. code-block:: none +.. code-block:: c mutex_lock(&state->ctrl_handler.lock); pr_info("String value is '%s'\n", ctrl1->p_cur.p_char); @@ -416,7 +416,7 @@ Menu Controls The v4l2_ctrl struct contains this union: -.. code-block:: none +.. code-block:: c union { u32 step; @@ -444,7 +444,7 @@ Custom Controls Driver specific controls can be created using v4l2_ctrl_new_custom(): -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_filter = { .ops = &ctrl_custom_ops, @@ -498,7 +498,7 @@ By default all controls are independent from the others. But in more complex scenarios you can get dependencies from one control to another. In that case you need to 'cluster' them: -.. code-block:: none +.. code-block:: c struct foo { struct v4l2_ctrl_handler ctrl_handler; @@ -522,7 +522,7 @@ composite control. Similar to how a 'struct' works in C. So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set all two controls belonging to the audio_cluster: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -544,7 +544,7 @@ all two controls belonging to the audio_cluster: In the example above the following are equivalent for the VOLUME case: -.. code-block:: none +.. code-block:: c ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] @@ -552,7 +552,7 @@ In the example above the following are equivalent for the VOLUME case: In practice using cluster arrays like this becomes very tiresome. So instead the following equivalent method is used: -.. code-block:: none +.. code-block:: c struct { /* audio cluster */ @@ -564,7 +564,7 @@ The anonymous struct is used to clearly 'cluster' these two control pointers, but it serves no other purpose. The effect is the same as creating an array with two control pointers. So you can just do: -.. code-block:: none +.. code-block:: c state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...); state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...); @@ -620,7 +620,7 @@ changing that control affects the control flags of the manual controls. In order to simplify this a special variation of v4l2_ctrl_cluster was introduced: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, u8 manual_val, bool set_volatile); @@ -675,7 +675,7 @@ of another handler (e.g. for a video device node), then you should first add the controls to the first handler, add the other controls to the second handler and finally add the first handler to the second. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -689,7 +689,7 @@ all controls. Or you can add specific controls to a handler: -.. code-block:: none +.. code-block:: c volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); @@ -698,7 +698,7 @@ Or you can add specific controls to a handler: What you should not do is make two identical controls for two handlers. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -719,7 +719,7 @@ not own. For example, if you have to find a volume control from a subdev. You can do that by calling v4l2_ctrl_find: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *volume; @@ -728,7 +728,7 @@ You can do that by calling v4l2_ctrl_find: Since v4l2_ctrl_find will lock the handler you have to be careful where you use it. For example, this is not a good idea: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl_handler ctrl_handler; @@ -737,7 +737,7 @@ use it. For example, this is not a good idea: ...and in video_ops.s_ctrl: -.. code-block:: none +.. code-block:: c case V4L2_CID_BRIGHTNESS: contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); @@ -759,7 +759,7 @@ not when it is used in consumer-level hardware. In that case you want to keep those low-level controls local to the subdev. You can do this by simply setting the 'is_private' flag of the control to 1: -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_private = { .ops = &ctrl_custom_ops, @@ -796,7 +796,7 @@ Sometimes the platform or bridge driver needs to be notified when a control from a sub-device driver changes. You can set a notify callback by calling this function: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv); From patchwork Thu Jun 13 14:18:25 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992085 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 90A4B14C0 for ; Thu, 13 Jun 2019 15:04:46 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7CF2720499 for ; Thu, 13 Jun 2019 15:04:46 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 717C82228E; Thu, 13 Jun 2019 15:04:46 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2197D212DB for ; Thu, 13 Jun 2019 15:04:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732739AbfFMPET (ORCPT ); Thu, 13 Jun 2019 11:04:19 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:45408 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732474AbfFMOSp (ORCPT ); Thu, 13 Jun 2019 10:18:45 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYs-0005He-LX; Thu, 13 Jun 2019 16:18:42 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 8/9] media: docs: v4l2-controls: document file to include Date: Thu, 13 Jun 2019 16:18:25 +0200 Message-Id: <20190613141826.26775-8-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The tutorial in this section is almost complete, add the one missing bit. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 45541e05a0e7..407617b1d0ce 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -50,6 +50,10 @@ Basic usage for V4L2 and sub-device drivers 1) Prepare the driver: +.. code-block:: c + + #include + 1.1) Add the handler to your driver's top-level struct: For V4L2 drivers: From patchwork Thu Jun 13 14:18:26 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 10992069 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id E093314BB for ; Thu, 13 Jun 2019 15:04:06 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CD84B21C9A for ; Thu, 13 Jun 2019 15:04:06 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C152A223A1; Thu, 13 Jun 2019 15:04:06 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2B5C321C9A for ; Thu, 13 Jun 2019 15:04:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1732849AbfFMPEF (ORCPT ); Thu, 13 Jun 2019 11:04:05 -0400 Received: from hostingweb31-40.netsons.net ([89.40.174.40]:45540 "EHLO hostingweb31-40.netsons.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1732475AbfFMOSq (ORCPT ); Thu, 13 Jun 2019 10:18:46 -0400 Received: from [109.168.11.45] (port=39754 helo=pc-ceresoli.dev.aim) by hostingweb31.netsons.net with esmtpa (Exim 4.92) (envelope-from ) id 1hbQYs-0005He-T4; Thu, 13 Jun 2019 16:18:42 +0200 From: Luca Ceresoli To: linux-media@vger.kernel.org Cc: Luca Ceresoli , Mauro Carvalho Chehab , Hans Verkuil , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 9/9] media: docs: v4l2-controls: remove outdated paragraph Date: Thu, 13 Jun 2019 16:18:26 +0200 Message-Id: <20190613141826.26775-9-luca@lucaceresoli.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190613141826.26775-1-luca@lucaceresoli.net> References: <20190613141826.26775-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: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This paragraph was added by commit a42b57f5aacf ("V4L/DVB: Documentation: add v4l2-controls.txt documenting the new controls API") back in 2010, when the controls API has been improved. Nowadays it is a bit anachronistic, so remove it. The same information is stated in up-to-date wording a few paragraphs later anyway: > You’re done! And this is sufficient for most of the drivers we have. No > need to do any validation of control values, or implement QUERYCTRL, > QUERY_EXT_CTRL and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS > are automatically supported. Signed-off-by: Luca Ceresoli --- Documentation/media/kapi/v4l2-controls.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 407617b1d0ce..ebe2a55908be 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -98,11 +98,6 @@ For V4L2 drivers: foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; -Finally, remove all control functions from your v4l2_ioctl_ops (if any): -vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, -vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. -Those are now no longer needed. - For sub-device drivers: .. code-block:: c