summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst')
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst39
1 files 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 248f6f9ee7c5..4ad7dec27e25 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,28 @@ 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 media 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 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 code 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 +70,16 @@ 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