Commit f4815b39 authored by Ezequiel Garcia's avatar Ezequiel Garcia Committed by Mauro Carvalho Chehab
Browse files

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: default avatarEzequiel Garcia <ezequiel@collabora.com>
Tested-by: default avatarJernej Skrabec <jernej.skrabec@siol.net>
Reviewed-by: default avatarJernej Skrabec <jernej.skrabec@siol.net>
Tested-by: default avatarDaniel Almeida <daniel.almeida@collabora.com>
Signed-off-by: default avatarHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent 3c994c6d

Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst

+214 −0
Original line number Diff line number Diff line
@@ -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

Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst

+0 −216
Original line number Diff line number Diff line
@@ -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.

Documentation/userspace-api/media/v4l/pixfmt-compressed.rst

+5 −5
Original line number Diff line number Diff line
@@ -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

Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst

+12 −0
Original line number Diff line number Diff line
@@ -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

drivers/media/v4l2-core/v4l2-ctrls.c

+6 −6
Original line number Diff line number Diff line
@@ -977,9 +977,6 @@ const char *v4l2_ctrl_get_name(u32 id) 
	case V4L2_CID_MPEG_VIDEO_LTR_COUNT:			return "LTR Count";

	case V4L2_CID_MPEG_VIDEO_FRAME_LTR_INDEX:		return "Frame LTR Index";

	case V4L2_CID_MPEG_VIDEO_USE_LTR_FRAMES:		return "Use LTR Frames";

	case V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE:		return "MPEG-2 Sequence Header";

	case V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE:			return "MPEG-2 Picture Header";

	case V4L2_CID_MPEG_VIDEO_MPEG2_QUANTISATION:		return "MPEG-2 Quantisation Matrices";

	case V4L2_CID_FWHT_I_FRAME_QP:				return "FWHT I-Frame QP Value";

	case V4L2_CID_FWHT_P_FRAME_QP:				return "FWHT P-Frame QP Value";
@@ -1228,6 +1225,9 @@ const char *v4l2_ctrl_get_name(u32 id) 
	case V4L2_CID_STATELESS_H264_DECODE_PARAMS:		return "H264 Decode Parameters";

	case V4L2_CID_STATELESS_FWHT_PARAMS:			return "FWHT Stateless Parameters";

	case V4L2_CID_STATELESS_VP8_FRAME:			return "VP8 Frame Parameters";

	case V4L2_CID_STATELESS_MPEG2_SEQUENCE:			return "MPEG-2 Sequence Header";

	case V4L2_CID_STATELESS_MPEG2_PICTURE:			return "MPEG-2 Picture Header";

	case V4L2_CID_STATELESS_MPEG2_QUANTISATION:		return "MPEG-2 Quantisation Matrices";



	/* Colorimetry controls */

	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1500,13 +1500,13 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type, 
	case V4L2_CID_RDS_TX_ALT_FREQS:

		*type = V4L2_CTRL_TYPE_U32;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE:

	case V4L2_CID_STATELESS_MPEG2_SEQUENCE:

		*type = V4L2_CTRL_TYPE_MPEG2_SEQUENCE;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE:

	case V4L2_CID_STATELESS_MPEG2_PICTURE:

		*type = V4L2_CTRL_TYPE_MPEG2_PICTURE;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_QUANTISATION:

	case V4L2_CID_STATELESS_MPEG2_QUANTISATION:

		*type = V4L2_CTRL_TYPE_MPEG2_QUANTISATION;

		break;

	case V4L2_CID_STATELESS_FWHT_PARAMS: