From patchwork Thu Apr 28 08:52:11 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dorota Czaplejewicz X-Patchwork-Id: 12830238 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 91D7FC433EF for ; Thu, 28 Apr 2022 08:52:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S244019AbiD1I4C (ORCPT ); Thu, 28 Apr 2022 04:56:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43346 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1344512AbiD1I4A (ORCPT ); Thu, 28 Apr 2022 04:56:00 -0400 Received: from comms.puri.sm (comms.puri.sm [159.203.221.185]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7BED723165; Thu, 28 Apr 2022 01:52:46 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by comms.puri.sm (Postfix) with ESMTP id 44DADDF75A; Thu, 28 Apr 2022 01:52:16 -0700 (PDT) Received: from comms.puri.sm ([127.0.0.1]) by localhost (comms.puri.sm [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 6X5VlkxIGCtY; Thu, 28 Apr 2022 01:52:15 -0700 (PDT) Date: Thu, 28 Apr 2022 10:52:11 +0200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=puri.sm; s=comms; t=1651135935; bh=ohE/IebwBN77RT1W4hsybc9tmsQEIEDdP++Soon6lDM=; h=Date:From:To:Subject:From; b=ssm+Caqw19pEA+VIsRGzYk2wLUCbQo5MRYZIHPy1rv6p6INwzTyr43rnTISXq3iOA bKTgUZrZEaw19MXRid5CqDKqK24IM/8iljdafA1wo68VKm3dkLIBbWsOkDqmTWGhuF uGGoeCtmN9t5gLN72dmBtmDBCIY90uC4HfnXYEB2sAtyeAB/uPAB3XanpIGJucXx6X 5Syo4nYGCu1Y06t1OBpMGNarkRiAEyjhbnQXHYBhtT4vUQHYpMwVYq+xOeixJOjAWT DrxJKseVSeOUBZnEl60XjfnKHjjMdVlfjHB7N8F8lL3DnLlOCjwFU0nhjUftDvDfh/ CFUKy3tVqnNPQ== From: Dorota Czaplejewicz To: Mauro Carvalho Chehab , linux-media@vger.kernel.org, linux-kernel@vger.kernel.org, kernel@puri.sm Subject: [PATCHv2 1/2] doc/media api: Try to make enum usage clearer Message-ID: <20220428105211.7106ce6a.dorota.czaplejewicz@puri.sm> Organization: Purism MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Added: mbus codes must not repeat Added: no holes in the enumeration Added: enumerations per what? Added: who fills in what in calls Changed: "zero" -> "0" Changed: "given" -> "specified" Signed-off-by: Dorota Czaplejewicz --- Hello, this is the second attempt at updating the media documentation. Differences from previous: "selected" is now "specified", "array" is now "enumeration", and "caller" is now "application". No differences: I haven't used the frame intervals calls and haven't gathered practical knowledge about where docs may be insufficient, so I didn't touch its documentation. Regards, Dorota .../v4l/vidioc-subdev-enum-mbus-code.rst | 39 +++++++++++++------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst index 417f1a19bcc4..87572de0fd26 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst @@ -31,15 +31,29 @@ Arguments Description =========== -To enumerate media bus formats available at a given sub-device pad -applications initialize the ``pad``, ``which`` and ``index`` fields of -struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this -structure. Drivers fill the rest of the structure or return an ``EINVAL`` -error code if either the ``pad`` or ``index`` are invalid. All media bus -formats are enumerable by beginning at index zero and incrementing by -one until ``EINVAL`` is returned. +This call is used by the application to access the enumeration of bus formats +for the selected pad. + +The enumerations are defined by the driver, and indexed using the ``index`` field +of struct :c:type:`v4l2_subdev_mbus_code_enum`. +Each value of ``pad`` corresponds to a separate enumeration. +Each enumeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of enumeration. + +Therefore, to enumerate media bus formats available at a given sub-device pad, +initialize the ``pad``, and ``which`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl +with a pointer to this structure. + +A successful call will return with the ``code`` field filled in +with a mbus format value. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either ``pad`` is invalid, +or that there are no more codes available at this pad. + +The driver must not return the same value of ``code`` for different indices +at the same pad. Available media bus formats may depend on the current 'try' formats at other pads of the sub-device, as well as on the current active links. @@ -57,14 +71,15 @@ information about the try formats. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the application. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the mbus code in the enumeration belonging to the given pad. + Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the driver. * - __u32 - ``which`` - Media bus format codes to be enumerated, from enum From patchwork Thu Apr 28 08:52:19 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dorota Czaplejewicz X-Patchwork-Id: 12830237 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E871BC433EF for ; Thu, 28 Apr 2022 08:52:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1344074AbiD1Izp (ORCPT ); Thu, 28 Apr 2022 04:55:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41454 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S244019AbiD1Izj (ORCPT ); Thu, 28 Apr 2022 04:55:39 -0400 Received: from comms.puri.sm (comms.puri.sm [159.203.221.185]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9A3E713D28; Thu, 28 Apr 2022 01:52:25 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by comms.puri.sm (Postfix) with ESMTP id B6F65DF75F; Thu, 28 Apr 2022 01:52:24 -0700 (PDT) Received: from comms.puri.sm ([127.0.0.1]) by localhost (comms.puri.sm [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id oin1w0UicEvp; Thu, 28 Apr 2022 01:52:24 -0700 (PDT) Date: Thu, 28 Apr 2022 10:52:19 +0200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=puri.sm; s=comms; t=1651135944; bh=7GvTiudrSeP0yh5rJkP4MPtvGvfvDnupAezm3TDBDt4=; h=Date:From:To:Subject:In-Reply-To:References:From; b=Gb9VNMTeIbJt88M70P2ChZEpLzARsNZPKnW5P1YEvAYAATR1enA3hQDZgB6LB4I3F tvlBKy3Ym2FewMFg7y0vtIPvuYwCrRvjbXAHNmsNzeLJBfjxJU6Udgc7ANH3lKbJQl sq/Ib7WMWWTmqIZVMV/brvdm4sPOkPN0ljnsZqGz9rGhLS6fTiybnNb7DoPp96i/jv NcL+f35HjDsjSfYTrz8hXBAt9d9kOnpyb8pgU65UGAz7n1X+6zyFrkpXlwlh0q9BpV mg9tH3Hz/ibhQpQiyRjaesmQrwhLdDS3hts0KWJJAW0vv3hlSM3qoggwkZ6ZPbyMNp 1C80QL0xwe4Ng== From: Dorota Czaplejewicz To: Mauro Carvalho Chehab , linux-media@vger.kernel.org, linux-kernel@vger.kernel.org, kernel@puri.sm Subject: [PATCHv2 2/2] media api: Try to make enum usage clearer Message-ID: <20220428105219.4b068b1f.dorota.czaplejewicz@puri.sm> In-Reply-To: <20220428083715.75997-1-dorota.czaplejewicz@puri.sm> References: <20220428083715.75997-1-dorota.czaplejewicz@puri.sm> Organization: Purism MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Fixed: typo "format" -> "frame size" in enum-frame-size Added: no holes in the enumeration Added: enumerations per what? Added: who fills in what in calls Changed: "zero" -> "0" Changed: "given" -> "specified" Signed-off-by: Dorota Czaplejewicz --- .../v4l/vidioc-subdev-enum-frame-size.rst | 44 ++++++++++++------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst index c25a9896df0e..2c6fd291dc44 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst @@ -31,18 +31,29 @@ Arguments Description =========== -This ioctl allows applications to enumerate all frame sizes supported by -a sub-device on the given pad for the given media bus format. Supported -formats can be retrieved with the +This ioctl allows applications to access the enumeration of frame sizes supported by +a sub-device on the specified pad for the specified media bus format. +Supported formats can be retrieved with the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl. -To enumerate frame sizes applications initialize the ``pad``, ``which`` -, ``code`` and ``index`` fields of the struct -:c:type:`v4l2_subdev_mbus_code_enum` and -call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the -structure. Drivers fill the minimum and maximum frame sizes or return an -EINVAL error code if one of the input parameters is invalid. +The enumerations are defined by the driver, and indexed using the ``index`` field +of the struct :c:type:`v4l2_subdev_mbus_code_enum`. +Each pair of ``pad`` and ``code`` correspond to a separate enumeration. +Each enumeeration starts with the ``index`` of 0, and +the lowest invalid index marks the end of the enumeration. + +Therefore, to enumerate frame sizes allowed on the specified pad +and using the specified mbus format, initialize the +``pad``, ``which``, and ``code`` fields to desired values, +and set ``index`` to 0. +Then call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the +structure. + +A successful call will return with minimum and maximum frame sizes filled in. +Repeat with increasing ``index`` until ``EINVAL`` is received. +``EINVAL`` means that either no more entries are available in the enumeration, +or that an input parameter was invalid. Sub-devices that only support discrete frame sizes (such as most sensors) will return one or more frame sizes with identical minimum and @@ -72,26 +83,27 @@ information about try formats. * - __u32 - ``index`` - - Number of the format in the enumeration, set by the application. + - Index of the frame size in the enumeration + belonging to the given pad and format. Filled in by the application. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the application. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the application. * - __u32 - ``min_width`` - - Minimum frame width, in pixels. + - Minimum frame width, in pixels. Filled in by the driver. * - __u32 - ``max_width`` - - Maximum frame width, in pixels. + - Maximum frame width, in pixels. Filled in by the driver. * - __u32 - ``min_height`` - - Minimum frame height, in pixels. + - Minimum frame height, in pixels. Filled in by the driver. * - __u32 - ``max_height`` - - Maximum frame height, in pixels. + - Maximum frame height, in pixels. Filled in by the driver. * - __u32 - ``which`` - Frame sizes to be enumerated, from enum