From patchwork Fri Apr 22 09:30:54 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dorota Czaplejewicz X-Patchwork-Id: 12823156 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 B4436C433F5 for ; Fri, 22 Apr 2022 09:31:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1352701AbiDVJeo (ORCPT ); Fri, 22 Apr 2022 05:34:44 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50534 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1445941AbiDVJeg (ORCPT ); Fri, 22 Apr 2022 05:34:36 -0400 Received: from comms.puri.sm (comms.puri.sm [159.203.221.185]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 749B453728; Fri, 22 Apr 2022 02:31:42 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by comms.puri.sm (Postfix) with ESMTP id 00769E041E; Fri, 22 Apr 2022 02:31:12 -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 OBw0JyK1CiTz; Fri, 22 Apr 2022 02:31:10 -0700 (PDT) Date: Fri, 22 Apr 2022 11:30:54 +0200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=puri.sm; s=comms; t=1650619870; bh=Onm9kRIqSZOU/4DiXxTyHXXHiBJ5pmGSDgQdiFJ83uU=; h=Date:From:To:Subject:From; b=reNQs44XviBWtVS9QHoMQnWNAV2ZctppQb/KImRQ8CZXVIzDtE9zliPTSARCCxgjD a1YhnR1WvUFFxVUliNRGOYJU47MlK/vgODfEDRBMsTTVzpYnaFoerBUeCliMRC3Gpc s5suBV8oB/ScwIps7wyzaFu65x9xOhjw4xlq9tJvT+ISZcwViO5lFgLZ5SdCxdVRML i5fVFCvLsDocuxcwoOG1eMROMCblMI/DQe8CSCNjJ/mkKLZeH5L52LXAVCzmIfvBXx 11CYRe2VRMz7UluAk1c/ZHps8BViBjLm3sc8RRdXwdOPNoBe1hW+wx+sJSzIckr/AY su5eiee9amL4w== From: Dorota Czaplejewicz To: Mauro Carvalho Chehab , linux-media@vger.kernel.org, linux-kernel@vger.kernel.org, kernel@puri.sm Subject: [PATCH] Documentation/media: Try to make enum usage clearer Message-ID: <20220422092542.1333177-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: mbus codes must not repeat Added: no holes in the array Added: arrays per what? Added: who fills in what (questionable naming: caller/driver. caller/callee could be confusing for beginners, they look similar) Changed: "zero" -> "0" Changed: "given" -> "selected". "given to me by the driver?" dunno feels like "selected" or "chosen" are the words to indicate agency to the consumer --- Hello, I encountered some difficulties trying to implement a media-api driver, and I traced the problems to not understanding the documentation. Here I try to make the API usage clearer, after consulting with libcamera authors. Still unclear how it works so I didn't touch it: "which". What is a "try format" vs "active format"? Cheers, Dorota Czaplejewicz .../v4l/vidioc-subdev-enum-frame-size.rst | 44 ++++++++++++------- .../v4l/vidioc-subdev-enum-mbus-code.rst | 39 +++++++++++----- 2 files changed, 55 insertions(+), 28 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..c7afeffb6269 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 array of frame sizes supported by +a sub-device on the selected pad for the selected 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 arrays 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 array. +Each array starts with the ``index`` of 0, and +the first invalid index marks the end of array. + +Therefore, to enumerate frame sizes allowed on the selected pad +and using the selected 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 array, +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 caller. * - __u32 - ``pad`` - - Pad number as reported by the media controller API. + - Pad number as reported by the media controller API. Filled in by the caller. * - __u32 - ``code`` - The media bus format code, as defined in - :ref:`v4l2-mbus-format`. + :ref:`v4l2-mbus-format`. Filled in by the caller. * - __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 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..22d046dd09c2 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 array of bus formats +for the selected pad. + +The arrays 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 array. +Each array starts with the ``index`` of 0, and +the first invalid index marks the end of array. + +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 caller. * - __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 caller. * - __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