Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Thu, 28 Apr 2022 10:52:11 +0200
From:   Dorota Czaplejewicz <dorota.czaplejewicz@puri.sm>
To:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        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
Content-Type: multipart/signed; boundary="Sig_/e.DoWQfsDpUUtXTZemZU8Pq";
 protocol="application/pgp-signature"; micalg=pgp-sha256
Precedence: bulk

--Sig_/e.DoWQfsDpUUtXTZemZU8Pq
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

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 <dorota.czaplejewicz@puri.sm>
---
Hello,

this is the second attempt at updating the media documentation.

Differences from previous: "selected" is now "specified", "array" is now "e=
numeration", and "caller" is now "application".

No differences: I haven't used the frame intervals calls and haven't gather=
ed practical knowledge about where docs may be insufficient, so I didn't to=
uch 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-co=
de.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
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
=20
-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 form=
ats
+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.
=20
 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.
=20
     * - __u32
       - ``pad``
-      - Pad number as reported by the media controller API.
+      - Pad number as reported by the media controller API. Filled in by t=
he 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 p=
ad.
+    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
--=20
2.35.1


--Sig_/e.DoWQfsDpUUtXTZemZU8Pq
Content-Type: application/pgp-signature
Content-Description: OpenPGP digital signature

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEExKRqtqfFqmh+lu1oADBpX4S8ZncFAmJqVbsACgkQADBpX4S8
ZncNnQ/7BWFK+LkIIBRQefdCUmp2vcmXBtC+DohmJgX6hHPbZtO0BGhssjuSS6Cy
b81Z7ujEyT9Lv2zOqEa+tHFR/zAjaqo5NxbiGhMdsFgDLEg7A5T+UZcRqNeruBNM
zKU2SGvFauukf2+wTwctBni0mLUAnpQA9cxzKEww+XNMGIftnjR1eX4APZylBX+D
ET5tR5iw8prcHzzuEQEM1cSNmzUhR49XcvJQXVSS+6kjjFViUeEaImxlfPbVvmvY
nf3JwcvRpJkNrJyVHFkVaul/ezzG4Pq0l6A/swlmUXErgHrBoado1bhtDoZpy7Ez
CuFRUioNk5yI7QrIX5tq+7bWMaVVxd9gbPqN1lvZU1MJ2V2PyqxbpmC+umXSTg1v
cuXLDSkHqO6p9Gdum2bsPkEhOIpgzzirYaEyDpxLhxMrHXuatt+2v2GxkeK4xuw+
Ghc6JczAYDcFYLjJpiZqMPr7oXBSGdIU6D8zlGX2jOfHTRVotzKEHT2tiCh17Hcq
RA22RlXEjWAg92YWfz/Qv+r/5VW9EvG3lQ5Tr17m0RIaXo0N5ygK5CKvBxFvpDuT
3fDs4J0wKnCjQ+00B4yzh2xF45JcHdOQ+T4IGgM0Mew61r8UCnJAlKzBWJsYLuap
0CY+n4obCRZJTHm6GJr/0Qj04nDuWhBgPWLmFfMu8iT1ZZp3k7g=
=AivM
-----END PGP SIGNATURE-----

--Sig_/e.DoWQfsDpUUtXTZemZU8Pq--