media: uapi: move MPEG-2 stateless controls out of staging

Until now, the MPEG-2 V4L2 API was not exported as a public API,
and only defined in a private media header (media/mpeg2-ctrls.h).

After reviewing the MPEG-2 specification in detail, and reworking
the controls so they match the MPEG-2 semantics properly,
we can consider it ready.

Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com>
Tested-by: Jernej Skrabec <jernej.skrabec@siol.net>
Reviewed-by: Jernej Skrabec <jernej.skrabec@siol.net>
Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
This commit is contained in:
Ezequiel Garcia
2021-05-23 19:21:31 +02:00
committed by Mauro Carvalho Chehab
parent 3c994c6d21
commit f4815b3991
14 changed files with 367 additions and 369 deletions
@@ -1244,3 +1244,217 @@ FWHT Flags
* - __u8
- ``padding[3]``
- Applications and drivers must set this to zero.
.. _v4l2-codec-stateless-mpeg2:
``V4L2_CID_STATELESS_MPEG2_SEQUENCE (struct)``
Specifies the sequence parameters (as extracted from the bitstream) for the
associated MPEG-2 slice data. This includes fields matching the syntax
elements from the sequence header and sequence extension parts of the
bitstream as specified by :ref:`mpeg2part2`.
.. c:type:: v4l2_ctrl_mpeg2_sequence
.. raw:: latex
\small
.. cssclass:: longtable
.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}|
.. flat-table:: struct v4l2_ctrl_mpeg2_sequence
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u16
- ``horizontal_size``
- The width of the displayable part of the frame's luminance component.
* - __u16
- ``vertical_size``
- The height of the displayable part of the frame's luminance component.
* - __u32
- ``vbv_buffer_size``
- Used to calculate the required size of the video buffering verifier,
defined (in bits) as: 16 * 1024 * vbv_buffer_size.
* - __u16
- ``profile_and_level_indication``
- The current profile and level indication as extracted from the
bitstream.
* - __u8
- ``chroma_format``
- The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4).
* - __u8
- ``flags``
- See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`.
.. _mpeg2_sequence_flags:
``MPEG-2 Sequence Flags``
.. cssclass:: longtable
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE``
- 0x01
- Indication that all the frames for the sequence are progressive instead
of interlaced.
.. raw:: latex
\normalsize
``V4L2_CID_STATELESS_MPEG2_PICTURE (struct)``
Specifies the picture parameters (as extracted from the bitstream) for the
associated MPEG-2 slice data. This includes fields matching the syntax
elements from the picture header and picture coding extension parts of the
bitstream as specified by :ref:`mpeg2part2`.
.. c:type:: v4l2_ctrl_mpeg2_picture
.. raw:: latex
\small
.. cssclass:: longtable
.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}|
.. flat-table:: struct v4l2_ctrl_mpeg2_picture
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u64
- ``backward_ref_ts``
- Timestamp of the V4L2 capture buffer to use as backward reference, used
with B-coded and P-coded frames. The timestamp refers to the
``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the
:c:func:`v4l2_timeval_to_ns()` function to convert the struct
:c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64.
* - __u64
- ``forward_ref_ts``
- Timestamp for the V4L2 capture buffer to use as forward reference, used
with B-coded frames. The timestamp refers to the ``timestamp`` field in
struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
function to convert the struct :c:type:`timeval` in struct
:c:type:`v4l2_buffer` to a __u64.
* - __u32
- ``flags``
- See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`.
* - __u8
- ``f_code[2][2]``
- Motion vector codes.
* - __u8
- ``picture_coding_type``
- Picture coding type for the frame covered by the current slice
(V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or
V4L2_MPEG2_PICTURE_CODING_TYPE_B).
* - __u8
- ``picture_structure``
- Picture structure (1: interlaced top field, 2: interlaced bottom field,
3: progressive frame).
* - __u8
- ``intra_dc_precision``
- Precision of Discrete Cosine transform (0: 8 bits precision,
1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision).
* - __u8
- ``reserved[5]``
- Applications and drivers must set this to zero.
.. _mpeg2_picture_flags:
``MPEG-2 Picture Flags``
.. cssclass:: longtable
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - ``V4L2_MPEG2_PIC_FLAG_TOP_FIELD_FIRST``
- 0x00000001
- If set and it's an interlaced stream, top field is output first.
* - ``V4L2_MPEG2_PIC_FLAG_FRAME_PRED_DCT``
- 0x00000002
- If set only frame-DCT and frame prediction are used.
* - ``V4L2_MPEG2_PIC_FLAG_CONCEALMENT_MV``
- 0x00000004
- If set motion vectors are coded for intra macroblocks.
* - ``V4L2_MPEG2_PIC_FLAG_Q_SCALE_TYPE``
- 0x00000008
- This flag affects the inverse quantization process.
* - ``V4L2_MPEG2_PIC_FLAG_INTRA_VLC``
- 0x00000010
- This flag affects the decoding of transform coefficient data.
* - ``V4L2_MPEG2_PIC_FLAG_ALT_SCAN``
- 0x00000020
- This flag affects the decoding of transform coefficient data.
* - ``V4L2_MPEG2_PIC_FLAG_REPEAT_FIRST``
- 0x00000040
- This flag affects the decoding process of progressive frames.
* - ``V4L2_MPEG2_PIC_FLAG_PROGRESSIVE``
- 0x00000080
- Indicates whether the current frame is progressive.
.. raw:: latex
\normalsize
``V4L2_CID_STATELESS_MPEG2_QUANTISATION (struct)``
Specifies quantisation matrices, in zigzag scanning order, for the
associated MPEG-2 slice data. This control is initialized by the kernel
to the matrices default values. If a bitstream transmits a user-defined
quantisation matrices load, applications are expected to use this control.
Applications are also expected to set the control loading the default
values, if the quantisation matrices need to be reset, for instance on a
sequence header. This process is specified by section 6.3.7.
"Quant matrix extension" of the specification.
.. c:type:: v4l2_ctrl_mpeg2_quantisation
.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}|
.. cssclass:: longtable
.. raw:: latex
\small
.. flat-table:: struct v4l2_ctrl_mpeg2_quantisation
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u8
- ``intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for intra-coded frames, in zigzag
scanning order. It is relevant for both luma and chroma components,
although it can be superseded by the chroma-specific matrix for
non-4:2:0 YUV formats.
* - __u8
- ``non_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for non-intra-coded frames, in
zigzag scanning order. It is relevant for both luma and chroma
components, although it can be superseded by the chroma-specific matrix
for non-4:2:0 YUV formats.
* - __u8
- ``chroma_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for the chominance component of
intra-coded frames, in zigzag scanning order. Only relevant for
non-4:2:0 YUV formats.
* - __u8
- ``chroma_non_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for the chrominance component of
non-intra-coded frames, in zigzag scanning order. Only relevant for
non-4:2:0 YUV formats.
.. raw:: latex
\normalsize
@@ -1606,222 +1606,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
``V4L2_CID_MPEG_VIDEO_H264_HIER_CODING_L6_BR (integer)``
Indicates bit rate (bps) for hierarchical coding layer 6 for H264 encoder.
.. _v4l2-mpeg-mpeg2:
``V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE (struct)``
Specifies the sequence parameters (as extracted from the bitstream) for the
associated MPEG-2 slice data. This includes fields matching the syntax
elements from the sequence header and sequence extension parts of the
bitstream as specified by :ref:`mpeg2part2`.
.. note::
This compound control is not yet part of the public kernel API and
it is expected to change.
.. c:type:: v4l2_ctrl_mpeg2_sequence
.. cssclass:: longtable
.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}|
.. flat-table:: struct v4l2_ctrl_mpeg2_sequence
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u16
- ``horizontal_size``
- The width of the displayable part of the frame's luminance component.
* - __u16
- ``vertical_size``
- The height of the displayable part of the frame's luminance component.
* - __u32
- ``vbv_buffer_size``
- Used to calculate the required size of the video buffering verifier,
defined (in bits) as: 16 * 1024 * vbv_buffer_size.
* - __u16
- ``profile_and_level_indication``
- The current profile and level indication as extracted from the
bitstream.
* - __u8
- ``chroma_format``
- The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4).
* - __u8
- ``flags``
- See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`.
.. _mpeg2_sequence_flags:
``MPEG-2 Sequence Flags``
.. cssclass:: longtable
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE``
- 0x01
- Indication that all the frames for the sequence are progressive instead
of interlaced.
``V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE (struct)``
Specifies the picture parameters (as extracted from the bitstream) for the
associated MPEG-2 slice data. This includes fields matching the syntax
elements from the picture header and picture coding extension parts of the
bitstream as specified by :ref:`mpeg2part2`.
.. note::
This compound control is not yet part of the public kernel API and
it is expected to change.
.. c:type:: v4l2_ctrl_mpeg2_picture
.. raw:: latex
\small
.. cssclass:: longtable
.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}|
.. flat-table:: struct v4l2_ctrl_mpeg2_picture
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u64
- ``backward_ref_ts``
- Timestamp of the V4L2 capture buffer to use as backward reference, used
with B-coded and P-coded frames. The timestamp refers to the
``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the
:c:func:`v4l2_timeval_to_ns()` function to convert the struct
:c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64.
* - __u64
- ``forward_ref_ts``
- Timestamp for the V4L2 capture buffer to use as forward reference, used
with B-coded frames. The timestamp refers to the ``timestamp`` field in
struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
function to convert the struct :c:type:`timeval` in struct
:c:type:`v4l2_buffer` to a __u64.
* - __u32
- ``flags``
- See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`.
* - __u8
- ``f_code[2][2]``
- Motion vector codes.
* - __u8
- ``picture_coding_type``
- Picture coding type for the frame covered by the current slice
(V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or
V4L2_MPEG2_PICTURE_CODING_TYPE_B).
* - __u8
- ``picture_structure``
- Picture structure (1: interlaced top field, 2: interlaced bottom field,
3: progressive frame).
* - __u8
- ``intra_dc_precision``
- Precision of Discrete Cosine transform (0: 8 bits precision,
1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision).
* - __u8
- ``reserved[5]``
- Applications and drivers must set this to zero.
.. _mpeg2_picture_flags:
``MPEG-2 Picture Flags``
.. cssclass:: longtable
.. flat-table::
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - ``V4L2_MPEG2_PIC_FLAG_TOP_FIELD_FIRST``
- 0x00000001
- If set and it's an interlaced stream, top field is output first.
* - ``V4L2_MPEG2_PIC_FLAG_FRAME_PRED_DCT``
- 0x00000002
- If set only frame-DCT and frame prediction are used.
* - ``V4L2_MPEG2_PIC_FLAG_CONCEALMENT_MV``
- 0x00000004
- If set motion vectors are coded for intra macroblocks.
* - ``V4L2_MPEG2_PIC_FLAG_Q_SCALE_TYPE``
- 0x00000008
- This flag affects the inverse quantization process.
* - ``V4L2_MPEG2_PIC_FLAG_INTRA_VLC``
- 0x00000010
- This flag affects the decoding of transform coefficient data.
* - ``V4L2_MPEG2_PIC_FLAG_ALT_SCAN``
- 0x00000020
- This flag affects the decoding of transform coefficient data.
* - ``V4L2_MPEG2_PIC_FLAG_REPEAT_FIRST``
- 0x00000040
- This flag affects the decoding process of progressive frames.
* - ``V4L2_MPEG2_PIC_FLAG_PROGRESSIVE``
- 0x00000080
- Indicates whether the current frame is progressive.
.. raw:: latex
\normalsize
``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTISATION (struct)``
Specifies quantisation matrices (as extracted from the bitstream) for the
associated MPEG-2 slice data.
.. note::
This compound control is not yet part of the public kernel API and
it is expected to change.
.. c:type:: v4l2_ctrl_mpeg2_quantisation
.. tabularcolumns:: |p{0.8cm}|p{8.0cm}|p{8.5cm}|
.. cssclass:: longtable
.. raw:: latex
\small
.. flat-table:: struct v4l2_ctrl_mpeg2_quantisation
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
* - __u8
- ``intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for intra-coded frames, in zigzag
scanning order. It is relevant for both luma and chroma components,
although it can be superseded by the chroma-specific matrix for
non-4:2:0 YUV formats.
* - __u8
- ``non_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for non-intra-coded frames, in
zigzag scanning order. It is relevant for both luma and chroma
components, although it can be superseded by the chroma-specific matrix
for non-4:2:0 YUV formats.
* - __u8
- ``chroma_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for the chominance component of
intra-coded frames, in zigzag scanning order. Only relevant for
non-4:2:0 YUV formats.
* - __u8
- ``chroma_non_intra_quantiser_matrix[64]``
- The quantisation matrix coefficients for the chrominance component of
non-intra-coded frames, in zigzag scanning order. Only relevant for
non-4:2:0 YUV formats.
.. raw:: latex
\normalsize
``V4L2_CID_FWHT_I_FRAME_QP (integer)``
Quantization parameter for an I frame for FWHT. Valid range: from 1
to 31.
@@ -112,13 +112,13 @@ Compressed Formats
- 'MG2S'
- MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
This format is adapted for stateless video decoders that implement a
MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
MPEG-2 pipeline with the :ref:`stateless_decoder`.
Metadata associated with the frame to decode is required to be passed
through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE`` and
``V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE`` controls.
through the ``V4L2_CID_STATELESS_MPEG2_SEQUENCE`` and
``V4L2_CID_STATELESS_MPEG2_PICTURE`` controls.
Quantisation matrices can optionally be specified through the
``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTISATION`` control.
See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`.
``V4L2_CID_STATELESS_MPEG2_QUANTISATION`` control.
See the :ref:`associated Codec Control IDs <v4l2-codec-stateless-mpeg2>`.
Exactly one output and one capture buffer must be provided for use with
this pixel format. The output buffer must contain the appropriate number
of macroblocks to decode a full corresponding frame to the matching
@@ -221,6 +221,18 @@ still cause this situation.
- ``p_vp8_frame``
- A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is
of type ``V4L2_CTRL_TYPE_VP8_FRAME``.
* - struct :c:type:`v4l2_ctrl_mpeg2_sequence` *
- ``p_mpeg2_sequence``
- A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_sequence`. Valid if this control is
of type ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``.
* - struct :c:type:`v4l2_ctrl_mpeg2_picture` *
- ``p_mpeg2_picture``
- A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_picture`. Valid if this control is
of type ``V4L2_CTRL_TYPE_MPEG2_PICTURE``.
* - struct :c:type:`v4l2_ctrl_mpeg2_quantisation` *
- ``p_mpeg2_quantisation``
- A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is
of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``.
* - struct :c:type:`v4l2_ctrl_hdr10_cll_info` *
- ``p_hdr10_cll``
- A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is