hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

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 Description
=========== ===========
To enumerate image formats applications initialize the ``type`` and To enumerate image formats applications initialize the ``type``, ``mbus_code``
``index`` field of struct :c:type:`v4l2_fmtdesc` and call and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call
the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers 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 fill the rest of the structure or return an ``EINVAL`` error code. All
formats are enumerable by beginning at index zero and incrementing by 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 formats in preference order, where preferred formats are returned before
(that is, with lower ``index`` value) less-preferred formats. (that is, with lower ``index`` value) less-preferred formats.
If the driver doesn't advertise the ``V4L2_CAP_IO_MC`` :ref:`capability Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
<device-capabilities>`, applications shall initialize the ``mbus_code`` field the ``mbus_code`` field is handled differently:
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.
If the driver advertises the ``V4L2_CAP_IO_MC`` :ref:`capability 1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver)
<device-capabilities>`, applications may initialize the ``mbus_code`` field to
a valid :ref:`media bus format code <v4l2-mbus-pixelcode>`. If the Applications shall initialize the ``mbus_code`` field to zero and drivers
``mbus_code`` field is not zero, drivers shall restrict enumeration to only the shall ignore the value of the field.
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 Drivers shall enumerate all image formats.
the ``mbus_code`` field, the enumerated image formats shall not depend on the
active configuration of the video device or device pipeline. Enumeration shall .. note::
otherwise operate as previously described.
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}| .. 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_OUTPUT_MPLANE``,
``V4L2_BUF_TYPE_VIDEO_OVERLAY``, ``V4L2_BUF_TYPE_VIDEO_OVERLAY``,
``V4L2_BUF_TYPE_SDR_CAPTURE``, ``V4L2_BUF_TYPE_SDR_CAPTURE``,
``V4L2_BUF_TYPE_SDR_OUTPUT`` and ``V4L2_BUF_TYPE_SDR_OUTPUT``,
``V4L2_BUF_TYPE_META_CAPTURE``. ``V4L2_BUF_TYPE_META_CAPTURE`` and
``V4L2_BUF_TYPE_META_OUTPUT``.
See :c:type:`v4l2_buf_type`. See :c:type:`v4l2_buf_type`.
* - __u32 * - __u32
- ``flags`` - ``flags``
@ -174,3 +190,6 @@ appropriately. The generic error codes are described at the
EINVAL EINVAL
The struct :c:type:`v4l2_fmtdesc` ``type`` is not The struct :c:type:`v4l2_fmtdesc` ``type`` is not
supported or the ``index`` is out of bounds. 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.