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) .. _planar-apis:
^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) Single- and multi-planar APIs
^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) Some devices require data for each input or output video frame to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) placed in discontiguous memory buffers. In such cases, one video frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) has to be addressed using more than one memory address, i.e. one pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) per "plane". A plane is a sub-buffer of the current frame. For examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) of such formats see :ref:`pixfmt`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Initially, V4L2 API did not support multi-planar buffers and a set of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) extensions has been introduced to handle them. Those extensions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) constitute what is being referred to as the "multi-planar API".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Some of the V4L2 API calls and structures are interpreted differently,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) depending on whether single- or multi-planar API is being used. An
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) application can choose whether to use one or the other by passing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) corresponding buffer type to its ioctl calls. Multi-planar versions of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) buffer types are suffixed with an ``_MPLANE`` string. For a list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) available multi-planar buffer types see enum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) :c:type:`v4l2_buf_type`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Multi-planar formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Multi-planar API introduces new multi-planar formats. Those formats use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) a separate set of FourCC codes. It is important to distinguish between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) the multi-planar API and a multi-planar format. Multi-planar API calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) can handle all single-planar formats as well (as long as they are passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) in multi-planar API structures), while the single-planar API cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) handle multi-planar formats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Calls that distinguish between single and multi-planar APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ===========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)     Two additional multi-planar capabilities are added. They can be set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)     together with non-multi-planar ones for devices that handle both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)     single- and multi-planar formats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)     New structures for describing multi-planar formats are added: struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)     :c:type:`v4l2_pix_format_mplane` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)     struct :c:type:`v4l2_plane_pix_format`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)     Drivers may define new multi-planar formats, which have distinct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)     FourCC codes from the existing single-planar ones.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)     A new struct :c:type:`v4l2_plane` structure for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)     describing planes is added. Arrays of this structure are passed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)     the new ``m.planes`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)     :c:type:`v4l2_buffer`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)     Will allocate multi-planar buffers as requested.