Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) .. _metadata:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ******************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) Metadata Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) ******************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) Metadata refers to any non-image data that supplements video frames with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) additional information. This may include statistics computed over the image,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) frame capture parameters supplied by the image source or device specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) parameters for specifying how the device processes images. This interface is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) intended for transfer of metadata between the userspace and the hardware and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) control of that operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) The metadata interface is implemented on video device nodes. The device can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) dedicated to metadata or can support both video and metadata as specified in its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) reported capabilities.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) Querying Capabilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Device nodes supporting the metadata capture interface set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ioctl. That flag means the device can capture metadata to memory. Similarly,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) device nodes supporting metadata output interface set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) ``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) :c:type:`v4l2_capability` structure. That flag means the device can read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) metadata from memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) At least one of the read/write or streaming I/O methods must be supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Data Format Negotiation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The metadata device uses the :ref:`format` ioctls to select the capture format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) The metadata buffer content format is bound to that selected format. In addition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) supported as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) To use the :ref:`format` ioctls applications set the ``type`` field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) :c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) ``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) member of the ``fmt`` union as needed per the desired operation. Both drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) and applications must set the remainder of the :c:type:`v4l2_format` structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) to 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) .. c:type:: v4l2_meta_format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) .. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) .. flat-table:: struct v4l2_meta_format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)     :header-rows:  0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)     :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)     :widths:       1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)       - ``dataformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)       - The data format, set by the application. This is a little endian
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)         :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)         in :ref:`meta-formats`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)     * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)       - ``buffersize``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)       - Maximum buffer size in bytes required for data. The value is set by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)         driver.