Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_SUBDEV_ENUM_MBUS_CODE:
   5
   6 **********************************
   7 ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
   8 **********************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_SUBDEV_ENUM_MBUS_CODE
  19
  20 ``int ioctl(int fd, VIDIOC_SUBDEV_ENUM_MBUS_CODE, struct v4l2_subdev_mbus_code_enum * argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_subdev_mbus_code_enum`.
  30
  31 Description
  32 ===========
  33
  34 This call is used by the application to access the enumeration
  35 of media bus formats for the selected pad.
  36
  37 The enumerations are defined by the driver, and indexed using the ``index`` field
  38 of struct :c:type:`v4l2_subdev_mbus_code_enum`.
  39 Each enumeration starts with the ``index`` of 0, and
  40 the lowest invalid index marks the end of enumeration.
  41
  42 Therefore, to enumerate media bus formats available at a given sub-device pad,
  43 initialize the ``pad``, and ``which`` fields to desired values,
  44 and set ``index`` to 0.
  45 Then call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl
  46 with a pointer to this structure.
  47
  48 A successful call will return with the ``code`` field filled in
  49 with a mbus code value.
  50 Repeat with increasing ``index`` until ``EINVAL`` is received.
  51 ``EINVAL`` means that either ``pad`` is invalid,
  52 or that there are no more codes available at this pad.
  53
  54 The driver must not return the same value of ``code`` for different indices
  55 at the same pad.
  56
  57 Available media bus formats may depend on the current 'try' formats at
  58 other pads of the sub-device, as well as on the current active links.
  59 See :ref:`VIDIOC_SUBDEV_G_FMT` for more
  60 information about the try formats.
  61
  62 .. c:type:: v4l2_subdev_mbus_code_enum
  63
  64 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
  65
  66 .. flat-table:: struct v4l2_subdev_mbus_code_enum
  67     :header-rows:  0
  68     :stub-columns: 0
  69     :widths:       1 1 2
  70
  71     * - __u32
  72       - ``pad``
  73       - Pad number as reported by the media controller API. Filled in by the
  74         application.
  75     * - __u32
  76       - ``index``
  77       - Index of the mbus code in the enumeration belonging to the given pad.
  78         Filled in by the application.
  79     * - __u32
  80       - ``code``
  81       - The media bus format code, as defined in
  82         :ref:`v4l2-mbus-format`. Filled in by the driver.
  83     * - __u32
  84       - ``which``
  85       - Media bus format codes to be enumerated, from enum
  86         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  87     * - __u32
  88       - ``flags``
  89       - See :ref:`v4l2-subdev-mbus-code-flags`
  90     * - __u32
  91       - ``stream``
  92       - Stream identifier.
  93     * - __u32
  94       - ``reserved``\ [6]
  95       - Reserved for future extensions. Applications and drivers must set
  96         the array to zero.
  97
  98
  99
 100 .. raw:: latex
 101
 102    \footnotesize
 103
 104 .. tabularcolumns:: |p{8.8cm}|p{2.2cm}|p{6.3cm}|
 105
 106 .. _v4l2-subdev-mbus-code-flags:
 107
 108 .. flat-table:: Subdev Media Bus Code Enumerate Flags
 109     :header-rows:  0
 110     :stub-columns: 0
 111     :widths:       1 1 2
 112
 113     * - V4L2_SUBDEV_MBUS_CODE_CSC_COLORSPACE
 114       - 0x00000001
 115       - The driver allows the application to try to change the default colorspace
 116         encoding. The application can ask to configure the colorspace of the
 117         subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>`
 118         ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set.
 119         See :ref:`v4l2-mbus-format` on how to do this.
 120     * - V4L2_SUBDEV_MBUS_CODE_CSC_XFER_FUNC
 121       - 0x00000002
 122       - The driver allows the application to try to change the default transform function.
 123         The application can ask to configure the transform function of
 124         the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>`
 125         ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set.
 126         See :ref:`v4l2-mbus-format` on how to do this.
 127     * - V4L2_SUBDEV_MBUS_CODE_CSC_YCBCR_ENC
 128       - 0x00000004
 129       - The driver allows the application to try to change the default Y'CbCr
 130         encoding. The application can ask to configure the Y'CbCr encoding of the
 131         subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>`
 132         ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set.
 133         See :ref:`v4l2-mbus-format` on how to do this.
 134     * - V4L2_SUBDEV_MBUS_CODE_CSC_HSV_ENC
 135       - 0x00000004
 136       - The driver allows the application to try to change the default HSV
 137         encoding. The application can ask to configure the HSV encoding of the
 138         subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>`
 139         ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set.
 140         See :ref:`v4l2-mbus-format` on how to do this.
 141     * - V4L2_SUBDEV_MBUS_CODE_CSC_QUANTIZATION
 142       - 0x00000008
 143       - The driver allows the application to try to change the default
 144         quantization. The application can ask to configure the quantization of
 145         the subdevice when calling the :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>`
 146         ioctl with :ref:`V4L2_MBUS_FRAMEFMT_SET_CSC <mbus-framefmt-set-csc>` set.
 147         See :ref:`v4l2-mbus-format` on how to do this.
 148
 149 .. raw:: latex
 150
 151    \normalsize
 152
 153 Return Value
 154 ============
 155
 156 On success 0 is returned, on error -1 and the ``errno`` variable is set
 157 appropriately. The generic error codes are described at the
 158 :ref:`Generic Error Codes <gen-errors>` chapter.
 159
 160 EINVAL
 161     The struct
 162     :c:type:`v4l2_subdev_mbus_code_enum`
 163     ``pad`` references a non-existing pad, or the ``index`` field is out
 164     of bounds.