summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2021-11-01 18:45:08 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2021-11-01 18:45:08 -0700
commit73d21a3579818aa0e39de207474a39ca35c7d8cb (patch)
treeae723d1026a6f39aa22bbcb3e82d3966ac7f5dcc /Documentation/userspace-api
parent6f2b76a4a384e05ac8d3349831f29dff5de1e1e2 (diff)
parent57c3b9f55ba875a6f6295fa59f0bdc0a01c544f8 (diff)
Merge tag 'media/v5.16-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab: - New driver for SK Hynix Hi-846 8M pixel camera - New driver for the ov13b10 camera - New driver for Renesas R-Car ISP - mtk-vcodec gained support for version 2 of decoder firmware ABI - The legacy sir_ir driver got removed - videobuf2: the vb2_mem_ops kAPI had some improvements - lots of cleanups, fixes and new features at device drivers * tag 'media/v5.16-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (328 commits) media: venus: core: Add sdm660 DT compatible and resource struct media: dt-bindings: media: venus: Add sdm660 dt schema media: venus: vdec: decoded picture buffer handling during reconfig sequence media: venus: Handle fatal errors during encoding and decoding media: venus: helpers: Add helper to mark fatal vb2 error media: venus: hfi: Check for sys error on session hfi functions media: venus: Make sys_error flag an atomic bitops media: venus: venc: Use pmruntime autosuspend media: allegro: write vui parameters for HEVC media: allegro: nal-hevc: implement generator for vui media: allegro: write correct colorspace into SPS media: allegro: extract nal value lookup functions to header media: allegro: correctly scale the bit rate in SPS media: allegro: remove external QP table media: allegro: fix row and column in response message media: allegro: add control to disable encoder buffer media: allegro: add encoder buffer support media: allegro: add pm_runtime support media: allegro: lookup VCU settings media: allegro: fix module removal if initialization failed ...
Diffstat (limited to 'Documentation/userspace-api')
-rw-r--r--Documentation/userspace-api/media/drivers/cx2341x-uapi.rst8
-rw-r--r--Documentation/userspace-api/media/v4l/buffer.rst40
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst57
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst20
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-reserved.rst29
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst50
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst7
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst3
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst3
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst6
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst16
-rw-r--r--Documentation/userspace-api/media/videodev2.h.rst.exceptions2
12 files changed, 190 insertions, 51 deletions
diff --git a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst
index 8a7977af79d5..debde65fb8cd 100644
--- a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst
+++ b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst
@@ -7,9 +7,7 @@ Non-compressed file format
--------------------------
The cx23416 can produce (and the cx23415 can also read) raw YUV output. The
-format of a YUV frame is specific to this chip and is called HM12. 'HM' stands
-for 'Hauppauge Macroblock', which is a misnomer as 'Conexant Macroblock' would
-be more accurate.
+format of a YUV frame is 16x16 linear tiled NV12 (V4L2_PIX_FMT_NV12_16L16).
The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per
four pixels.
@@ -34,8 +32,8 @@ second line of 8 UV pairs of the top-left block, etc. After transmitting
this block the first line of the block on the right to the first block is
transmitted, etc.
-The code below is given as an example on how to convert HM12 to separate
-Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels.
+The code below is given as an example on how to convert V4L2_PIX_FMT_NV12_16L16
+to separate Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels.
The width of a frame is always 720 pixels, regardless of the actual specified
width.
diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst
index e991ba73d873..4638ec64db00 100644
--- a/Documentation/userspace-api/media/v4l/buffer.rst
+++ b/Documentation/userspace-api/media/v4l/buffer.rst
@@ -676,8 +676,6 @@ Buffer Flags
\normalsize
-.. _memory-flags:
-
enum v4l2_memory
================
@@ -701,6 +699,44 @@ enum v4l2_memory
- 4
- The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
+.. _memory-flags:
+
+Memory Consistency Flags
+------------------------
+
+.. raw:: latex
+
+ \small
+
+.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}|
+
+.. cssclass:: longtable
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+ * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`:
+
+ - ``V4L2_MEMORY_FLAG_NON_COHERENT``
+ - 0x00000001
+ - A buffer is allocated either in coherent (it will be automatically
+ coherent between the CPU and the bus) or non-coherent memory. The
+ latter can provide performance gains, for instance the CPU cache
+ sync/flush operations can be avoided if the buffer is accessed by the
+ corresponding device only and the CPU does not read/write to/from that
+ buffer. However, this requires extra care from the driver -- it must
+ guarantee memory consistency by issuing a cache flush/sync when
+ consistency is needed. If this flag is set V4L2 will attempt to
+ allocate the buffer in non-coherent memory. The flag takes effect
+ only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the
+ queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS
+ <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
+
+.. raw:: latex
+
+ \normalsize
Timecodes
=========
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
index 976d34445a24..e141f0e4eec9 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
@@ -3088,6 +3088,63 @@ enum v4l2_mpeg_video_hevc_size_of_length_field -
\normalsize
+``V4L2_CID_MPEG_VIDEO_HEVC_SCALING_MATRIX (struct)``
+ Specifies the HEVC scaling matrix parameters used for the scaling process
+ for transform coefficients.
+ These matrix and parameters are defined according to :ref:`hevc`.
+ They are described in section 7.4.5 "Scaling list data semantics" of
+ the specification.
+
+.. c:type:: v4l2_ctrl_hevc_scaling_matrix
+
+.. raw:: latex
+
+ \scriptsize
+
+.. tabularcolumns:: |p{5.4cm}|p{6.8cm}|p{5.1cm}|
+
+.. cssclass:: longtable
+
+.. flat-table:: struct v4l2_ctrl_hevc_scaling_matrix
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u8
+ - ``scaling_list_4x4[6][16]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+ * - __u8
+ - ``scaling_list_8x8[6][64]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+ * - __u8
+ - ``scaling_list_16x16[6][64]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+ * - __u8
+ - ``scaling_list_32x32[2][64]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+ * - __u8
+ - ``scaling_list_dc_coef_16x16[6]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+ * - __u8
+ - ``scaling_list_dc_coef_32x32[2]``
+ - Scaling list is used for the scaling process for transform
+ coefficients. The values on each scaling list are expected
+ in raster scan order.
+
+.. raw:: latex
+
+ \normalsize
+
.. c:type:: v4l2_hevc_dpb_entry
.. raw:: latex
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
index de43f5c8486d..71f23f131f97 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -72,3 +72,23 @@ Image Source Control IDs
* - __u32
- ``height``
- Height of the area.
+
+``V4L2_CID_NOTIFY_GAINS (integer array)``
+ The sensor is notified what gains will be applied to the different
+ colour channels by subsequent processing (such as by an ISP). The
+ sensor is merely informed of these values in case it performs
+ processing that requires them, but it does not apply them itself to
+ the output pixels.
+
+ Currently it is defined only for Bayer sensors, and is an array
+ control taking 4 gain values, being the gains for each of the
+ Bayer channels. The gains are always in the order B, Gb, Gr and R,
+ irrespective of the exact Bayer order of the sensor itself.
+
+ The use of an array allows this control to be extended to sensors
+ with, for example, non-Bayer CFAs (colour filter arrays).
+
+ The units for the gain values are linear, with the default value
+ representing a gain of exactly 1.0. For example, if this default value
+ is reported as being (say) 128, then a value of 192 would represent
+ a gain of exactly 1.5.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst
index 0b879c0da713..2f2133b4cd9c 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-reserved.rst
@@ -48,14 +48,6 @@ please make a proposal on the linux-media mailing list.
- ``V4L2_PIX_FMT_HI240``
- 'HI24'
- 8 bit RGB format used by the BTTV driver.
- * .. _V4L2-PIX-FMT-HM12:
-
- - ``V4L2_PIX_FMT_HM12``
- - 'HM12'
- - YUV 4:2:0 format used by the IVTV driver.
-
- The format is documented in the kernel sources in the file
- ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst``
* .. _V4L2-PIX-FMT-CPIA1:
- ``V4L2_PIX_FMT_CPIA1``
@@ -246,20 +238,13 @@ please make a proposal on the linux-media mailing list.
It is an opaque intermediate format and the MDP hardware must be
used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``,
``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``.
- * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12:
-
- - ``V4L2_PIX_FMT_SUNXI_TILED_NV12``
- - 'ST12'
- - Two-planar NV12-based format used by the video engine found on Allwinner
- (codenamed sunxi) platforms, with 32x32 tiles for the luminance plane
- and 32x64 tiles for the chrominance plane. The data in each tile is
- stored in linear order, within the tile bounds. Each tile follows the
- previous one linearly in memory (from left to right, top to bottom).
-
- The associated buffer dimensions are aligned to match an integer number
- of tiles, resulting in 32-aligned resolutions for the luminance plane
- and 16-aligned resolutions for the chrominance plane (with 2x2
- subsampling).
+ * .. _V4L2-PIX-FMT-MM21:
+
+ - ``V4L2_PIX_FMT_MM21``
+ - 'MM21'
+ - Non-compressed, tiled two-planar format used by Mediatek MT8183.
+ This is an opaque intermediate format and the MDP3 hardware can be
+ used to convert it to other formats.
.. raw:: latex
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
index 090c091affd2..3a09d93d405b 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
@@ -99,7 +99,7 @@ All components are stored with the same number of bits per component.
- 4:2:0
- Cb, Cr
- No
- - 64x32 macroblocks
+ - 64x32 tiles
Horizontal Z order
* - V4L2_PIX_FMT_NV12MT_16X16
@@ -108,7 +108,7 @@ All components are stored with the same number of bits per component.
- 4:2:2
- Cb, Cr
- No
- - 16x16 macroblocks
+ - 16x16 tiles
* - V4L2_PIX_FMT_NV16
- 'NV16'
- 8
@@ -254,27 +254,47 @@ of the luma plane.
.. _V4L2-PIX-FMT-NV12MT:
.. _V4L2-PIX-FMT-NV12MT-16X16:
+.. _V4L2-PIX-FMT-NV12-4L4:
+.. _V4L2-PIX-FMT-NV12-16L16:
+.. _V4L2-PIX-FMT-NV12-32L32:
-NV12MT and MV12MT_16X16
------------------------
+Tiled NV12
+----------
Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is
subsampled by 2 in each direction. Chroma lines contain half the number of
pixels and the same number of bytes as luma lines, and the chroma plane
-contains half the number of lines of the luma plane.
+contains half the number of lines of the luma plane. Each tile follows the
+previous one linearly in memory (from left to right, top to bottom).
+
+``V4L2_PIX_FMT_NV12MT_16X16`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
+pixels in 2D 16x16 tiles, and stores tiles linearly in memory.
+The line stride and image height must be aligned to a multiple of 16.
+The layouts of the luma and chroma planes are identical.
+
+``V4L2_PIX_FMT_NV12MT`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
+pixels in 2D 64x32 tiles, and stores 2x2 groups of tiles in
+Z-order in memory, alternating Z and mirrored Z shapes horizontally.
+The line stride must be a multiple of 128 pixels to ensure an
+integer number of Z shapes. The image height must be a multiple of 32 pixels.
+If the vertical resolution is an odd number of tiles, the last row of
+tiles is stored in linear order. The layouts of the luma and chroma
+planes are identical.
+
+``V4L2_PIX_FMT_NV12_4L4`` stores pixel in 4x4 tiles, and stores
+tiles linearly in memory. The line stride and image height must be
+aligned to a multiple of 4. The layouts of the luma and chroma planes are
+identical.
-``V4L2_PIX_FMT_NV12MT_16X16`` stores pixel in 2D 16x16 macroblocks, and stores
-macroblocks linearly in memory. The line stride and image height must be
+``V4L2_PIX_FMT_NV12_16L16`` stores pixel in 16x16 tiles, and stores
+tiles linearly in memory. The line stride and image height must be
aligned to a multiple of 16. The layouts of the luma and chroma planes are
identical.
-``V4L2_PIX_FMT_NV12MT`` stores pixels in 2D 64x32 macroblocks, and stores 2x2
-groups of macroblocks in Z-order in memory, alternating Z and mirrored Z shapes
-horizontally. The line stride must be a multiple of 128 pixels to ensure an
-integer number of Z shapes. The image height must be a multiple of 32 pixels.
-If the vertical resolution is an odd number of macroblocks, the last row of
-macroblocks is stored in linear order. The layouts of the luma and chroma
-planes are identical.
+``V4L2_PIX_FMT_NV12_32L32`` stores pixel in 32x32 tiles, and stores
+tiles linearly in memory. The line stride and image height must be
+aligned to a multiple of 32. The layouts of the luma and chroma planes are
+identical.
.. _nv12mt:
@@ -290,7 +310,7 @@ planes are identical.
:alt: nv12mt_example.svg
:align: center
- Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
+ Example V4L2_PIX_FMT_NV12MT memory layout of tiles
.. _V4L2-PIX-FMT-NV16:
diff --git a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
index f98f18c9e91c..a048a9f6b7b6 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst
@@ -113,7 +113,12 @@ than the number requested.
``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type.
* - __u32
- - ``reserved``\ [7]
+ - ``flags``
+ - Specifies additional buffer management attributes.
+ See :ref:`memory-flags`.
+
+ * - __u32
+ - ``reserved``\ [6]
- A place holder for future extensions. Drivers and applications
must set the array to zero.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
index 80e8c63d530f..fd09677f64f8 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst
@@ -95,3 +95,6 @@ EBUSY
EACCES
Attempt to set a read-only control or to get a write-only control.
+
+ Or if there is an attempt to set an inactive control and the driver is
+ not capable of caching the new value until the control is active again.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
index 2d6bc8d94380..fdde0ae6d521 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst
@@ -470,3 +470,6 @@ EACCES
Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the
device does not support requests.
+
+ Or if there is an attempt to set an inactive control and the driver is
+ not capable of caching the new value until the control is active again.
diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
index f9ecf6276129..2f491c17dd5d 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
@@ -495,6 +495,12 @@ See also the examples in :ref:`control`.
- n/a
- A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC
slice parameters for stateless video decoders.
+ * - ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``
+ - n/a
+ - n/a
+ - n/a
+ - A struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`, containing HEVC
+ scaling matrix for stateless video decoders.
* - ``V4L2_CTRL_TYPE_VP8_FRAME``
- n/a
- n/a
diff --git a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
index 50ea72043bb0..099fa6695167 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst
@@ -104,10 +104,13 @@ aborting or finishing any DMA in progress, an implicit
``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will
free any previously allocated buffers, so this is typically something
that will be done at the start of the application.
- * - __u32
- - ``reserved``\ [1]
- - A place holder for future extensions. Drivers and applications
- must set the array to zero.
+ * - __u8
+ - ``flags``
+ - Specifies additional buffer management attributes.
+ See :ref:`memory-flags`.
+ * - __u8
+ - ``reserved``\ [3]
+ - Reserved for future extensions.
.. _v4l2-buf-capabilities:
.. _V4L2-BUF-CAP-SUPPORTS-MMAP:
@@ -158,8 +161,9 @@ aborting or finishing any DMA in progress, an implicit
- This capability is set by the driver to indicate that the queue supports
cache and memory management hints. However, it's only valid when the
queue is used for :ref:`memory mapping <mmap>` streaming I/O. See
- :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>` and
- :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>`.
+ :ref:`V4L2_BUF_FLAG_NO_CACHE_INVALIDATE <V4L2-BUF-FLAG-NO-CACHE-INVALIDATE>`,
+ :ref:`V4L2_BUF_FLAG_NO_CACHE_CLEAN <V4L2-BUF-FLAG-NO-CACHE-CLEAN>` and
+ :ref:`V4L2_MEMORY_FLAG_NON_COHERENT <V4L2-MEMORY-FLAG-NON-COHERENT>`.
.. raw:: latex
diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
index 2217b56c2686..eb0b1cd37abd 100644
--- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions
+++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
@@ -187,6 +187,8 @@ replace define V4L2_CAP_IO_MC device-capabilities
# V4L2 pix flags
replace define V4L2_PIX_FMT_PRIV_MAGIC :c:type:`v4l2_pix_format`
replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA format-flags
+replace define V4L2_PIX_FMT_HM12 :c:type:`v4l2_pix_format`
+replace define V4L2_PIX_FMT_SUNXI_TILED_NV12 :c:type:`v4l2_pix_format`
# V4L2 format flags
replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags