redonkable/alistair23-linux
redonkable/alistair23-linux
1
0
Fork 0
Code Releases Activity

media: vidioc-enum-fmt.rst: make the ENUM_FMT text clearer

Browse source 
Rework the documentation to make it easier for the reader to understand
the differences in behavior of this ioctl between MC and non-MC drivers.

Note the addition of the 'video-node-centric' and 'MC-centric' terms to
help understand what the IO_MC capability really means.

Also mention in the beginning that mbus_code is one of the fields that
application should initialize, and add META_OUTPUT as one of the types that
this ioctl supports (that was never added here when the META_OUTPUT buffer
type was added).

Finally document that EINVAL will be returned if mbus_code is unsupported.

Fixes: e5b6b07a1b ("media: v4l2: Extend VIDIOC_ENUM_FMT to support MC-centric devices")
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Hans Verkuil 2020-05-06 14:16:00 +02:00 committed by Mauro Carvalho Chehab
parent c7ff09f6e2
commit 6ba189d3f7
1 changed files with 37 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
View file

@ -39,8 +39,8 @@ Arguments
Description
===========
To enumerate image formats applications initialize the ``type`` and
``index`` field of struct :c:type:`v4l2_fmtdesc` and call
To enumerate image formats applications initialize the ``type``, ``mbus_code``
and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
fill the rest of the structure or return an ``EINVAL`` error code. All
formats are enumerable by beginning at index zero and incrementing by
@ -48,21 +48,36 @@ one until ``EINVAL`` is returned. If applicable, drivers shall return
formats in preference order, where preferred formats are returned before
(that is, with lower ``index`` value) less-preferred formats.
If the driver doesn't advertise the ``V4L2_CAP_IO_MC`` :ref:`capability
<device-capabilities>`, applications shall initialize the ``mbus_code`` field
to zero and drivers shall ignore the value of the field. Drivers shall
enumerate all image formats. The enumerated formats may depend on the active
input or output of the device.
Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
the ``mbus_code`` field is handled differently:
If the driver advertises the ``V4L2_CAP_IO_MC`` :ref:`capability
<device-capabilities>`, applications may initialize the ``mbus_code`` field to
a valid :ref:`media bus format code <v4l2-mbus-pixelcode>`. If the
``mbus_code`` field is not zero, drivers shall restrict enumeration to only the
image formats that can produce (for video output devices) or be produced from
(for video capture devices) that media bus code. Regardless of the value of
the ``mbus_code`` field, the enumerated image formats shall not depend on the
active configuration of the video device or device pipeline. Enumeration shall
otherwise operate as previously described.
1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
Applications shall initialize the ``mbus_code`` field to zero and drivers
shall ignore the value of the field.
Drivers shall enumerate all image formats.
.. note::
After switching the input or output the list of enumerated image
formats may be different.
2) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver)
If the ``mbus_code`` field is zero, then all image formats
shall be enumerated.
If the ``mbus_code`` field is initialized to a valid (non-zero)
:ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers
shall restrict enumeration to only the image formats that can produce
(for video output devices) or be produced from (for video capture
devices) that media bus code. If the ``mbus_code`` is unsupported by
the driver, then ``EINVAL`` shall be returned.
Regardless of the value of the ``mbus_code`` field, the enumerated image
formats shall not depend on the active configuration of the video device
or device pipeline.
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@ -87,8 +102,9 @@ otherwise operate as previously described.
``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
``V4L2_BUF_TYPE_SDR_CAPTURE``,
``V4L2_BUF_TYPE_SDR_OUTPUT`` and
``V4L2_BUF_TYPE_META_CAPTURE``.
``V4L2_BUF_TYPE_SDR_OUTPUT``,
``V4L2_BUF_TYPE_META_CAPTURE`` and
``V4L2_BUF_TYPE_META_OUTPUT``.
See :c:type:`v4l2_buf_type`.
* - __u32
- ``flags``
@ -174,3 +190,6 @@ appropriately. The generic error codes are described at the
EINVAL
The struct :c:type:`v4l2_fmtdesc` ``type`` is not
supported or the ``index`` is out of bounds.
If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code``
is unsupported, then also return this error code.