From 6ba189d3f78c331153c4a6eb27163e27fc274123 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 6 May 2020 14:16:00 +0200 Subject: 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: e5b6b07a1b45 ("media: v4l2: Extend VIDIOC_ENUM_FMT to support MC-centric devices") Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../userspace-api/media/v4l/vidioc-enum-fmt.rst | 55 +++++++++++++++------- 1 file changed, 37 insertions(+), 18 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index 9694111772a2..a53dd3d7f7e2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -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 -`, 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 `, +the ``mbus_code`` field is handled differently: -If the driver advertises the ``V4L2_CAP_IO_MC`` :ref:`capability -`, applications may initialize the ``mbus_code`` field to -a valid :ref:`media bus format code `. 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 `, 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. -- cgit