Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c27bb30e authored by Paul Kocialkowski's avatar Paul Kocialkowski Committed by Mauro Carvalho Chehab
Browse files

media: v4l: Add definitions for MPEG-2 slice format and metadata 



Stateless video decoding engines require both the MPEG-2 slices and
associated metadata from the video stream in order to decode frames.

This introduces definitions for a new pixel format, describing buffers
with MPEG-2 slice data, as well as control structure sfor passing the
frame metadata to drivers.

This is based on work from both Florent Revest and Hugues Fruchet.

Signed-off-by: default avatarPaul Kocialkowski <paul.kocialkowski@bootlin.com>
Signed-off-by: default avatarMaxime Ripard <maxime.ripard@bootlin.com>
Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent 515c5a73

Documentation/media/uapi/v4l/extended-controls.rst

+176 −0
Original line number Diff line number Diff line
@@ -1497,6 +1497,182 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 






.. _v4l2-mpeg-mpeg2:



``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)``

    Specifies the slice parameters (as extracted from the bitstream) for the

    associated MPEG-2 slice data. This includes the necessary parameters for

    configuring a stateless hardware decoding pipeline for MPEG-2.

    The bitstream parameters are defined according to :ref:`mpeg2part2`.



.. c:type:: v4l2_ctrl_mpeg2_slice_params



.. cssclass:: longtable



.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params

    :header-rows:  0

    :stub-columns: 0

    :widths:       1 1 2



    * - __u32

      - ``bit_size``

      - Size (in bits) of the current slice data.

    * - __u32

      - ``data_bit_offset``

      - Offset (in bits) to the video data in the current slice data.

    * - struct :c:type:`v4l2_mpeg2_sequence`

      - ``sequence``

      - Structure with MPEG-2 sequence metadata, merging relevant fields from

	the sequence header and sequence extension parts of the bitstream.

    * - struct :c:type:`v4l2_mpeg2_picture`

      - ``picture``

      - Structure with MPEG-2 picture metadata, merging relevant fields from

	the picture header and picture coding extension parts of the bitstream.

    * - __u8

      - ``quantiser_scale_code``

      - Code used to determine the quantization scale to use for the IDCT.

    * - __u8

      - ``backward_ref_index``

      - Index for the V4L2 buffer to use as backward reference, used with

	B-coded and P-coded frames.

    * - __u8

      - ``forward_ref_index``

      - Index for the V4L2 buffer to use as forward reference, used with

	B-coded frames.



.. c:type:: v4l2_mpeg2_sequence



.. cssclass:: longtable



.. flat-table:: struct v4l2_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.

    * - __u8

      - ``profile_and_level_indication``

      - The current profile and level indication as extracted from the

	bitstream.

    * - __u8

      - ``progressive_sequence``

      - Indication that all the frames for the sequence are progressive instead

	of interlaced.

    * - __u8

      - ``chroma_format``

      - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4).



.. c:type:: v4l2_mpeg2_picture



.. cssclass:: longtable



.. flat-table:: struct v4l2_mpeg2_picture

    :header-rows:  0

    :stub-columns: 0

    :widths:       1 1 2



    * - __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

      - ``f_code[2][2]``

      - Motion vector codes.

    * - __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

      - ``picture_structure``

      - Picture structure (1: interlaced top field, 2: interlaced bottom field,

	3: progressive frame).

    * - __u8

      - ``top_field_first``

      - If set to 1 and interlaced stream, top field is output first.

    * - __u8

      - ``frame_pred_frame_dct``

      - If set to 1, only frame-DCT and frame prediction are used.

    * - __u8

      - ``concealment_motion_vectors``

      -  If set to 1, motion vectors are coded for intra macroblocks.

    * - __u8

      - ``q_scale_type``

      - This flag affects the inverse quantization process.

    * - __u8

      - ``intra_vlc_format``

      - This flag affects the decoding of transform coefficient data.

    * - __u8

      - ``alternate_scan``

      - This flag affects the decoding of transform coefficient data.

    * - __u8

      - ``repeat_first_field``

      - This flag affects the decoding process of progressive frames.

    * - __u8

      - ``progressive_frame``

      - Indicates whether the current frame is progressive.



``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)``

    Specifies quantization matrices (as extracted from the bitstream) for the

    associated MPEG-2 slice data.



.. c:type:: v4l2_ctrl_mpeg2_quantization



.. cssclass:: longtable



.. flat-table:: struct v4l2_ctrl_mpeg2_quantization

    :header-rows:  0

    :stub-columns: 0

    :widths:       1 1 2



    * - __u8

      - ``load_intra_quantiser_matrix``

      - One bit to indicate whether to load the ``intra_quantiser_matrix`` data.

    * - __u8

      - ``load_non_intra_quantiser_matrix``

      - One bit to indicate whether to load the ``non_intra_quantiser_matrix``

	data.

    * - __u8

      - ``load_chroma_intra_quantiser_matrix``

      - One bit to indicate whether to load the

	``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV

	formats.

    * - __u8

      - ``load_chroma_non_intra_quantiser_matrix``

      - One bit to indicate whether to load the

	``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0

	YUV formats.

    * - __u8

      - ``intra_quantiser_matrix[64]``

      - The quantization 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 quantization 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 quantization 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 quantization matrix coefficients for the chrominance component of

	non-intra-coded frames, in zigzag scanning order. Only relevant for

	non-4:2:0 YUV formats.



MFC 5.1 MPEG Controls

---------------------

Documentation/media/uapi/v4l/pixfmt-compressed.rst

+16 −0
Original line number Diff line number Diff line
@@ -60,6 +60,22 @@ Compressed Formats 
      - ``V4L2_PIX_FMT_MPEG2``

      - 'MPG2'

      - MPEG2 video elementary stream.

    * .. _V4L2-PIX-FMT-MPEG2-SLICE:



      - ``V4L2_PIX_FMT_MPEG2_SLICE``

      - '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:`codec` and :ref:`media-request-api`).

	Metadata associated with the frame to decode is required to be passed

	through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and

	quantization matrices can optionally be specified through the

	``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control.

	See the :ref:`associated Codec Control IDs <v4l2-mpeg-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

	capture buffer.

    * .. _V4L2-PIX-FMT-MPEG4:



      - ``V4L2_PIX_FMT_MPEG4``

Documentation/media/uapi/v4l/vidioc-queryctrl.rst

+12 −2
Original line number Diff line number Diff line
@@ -424,8 +424,18 @@ See also the examples in :ref:`control`. 
      - any

      - An unsigned 32-bit valued control ranging from minimum to maximum

	inclusive. The step value indicates the increment between values.





    * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS``

      - n/a

      - n/a

      - n/a

      - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2

	slice parameters for stateless video decoders.

    * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION``

      - n/a

      - n/a

      - n/a

      - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2

	quantization matrices for stateless video decoders.



.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|

Documentation/media/videodev2.h.rst.exceptions

+2 −0
Original line number Diff line number Diff line
@@ -129,6 +129,8 @@ replace symbol V4L2_CTRL_TYPE_STRING :c:type:`v4l2_ctrl_type` 
replace symbol V4L2_CTRL_TYPE_U16 :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTIZATION :c:type:`v4l2_ctrl_type`



# V4L2 capability defines

replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities

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

+63 −0
Original line number Diff line number Diff line
@@ -844,6 +844,8 @@ const char *v4l2_ctrl_get_name(u32 id) 
	case V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE:		return "Vertical MV Search Range";

	case V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER:		return "Repeat Sequence Header";

	case V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME:		return "Force Key Frame";

	case V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS:		return "MPEG-2 Slice Parameters";

	case V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION:		return "MPEG-2 Quantization Matrices";



	/* VPX controls */

	case V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS:		return "VPX Number of Partitions";
@@ -1292,6 +1294,12 @@ 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_SLICE_PARAMS:

		*type = V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION:

		*type = V4L2_CTRL_TYPE_MPEG2_QUANTIZATION;

		break;

	default:

		*type = V4L2_CTRL_TYPE_INTEGER;

		break;
@@ -1550,6 +1558,7 @@ static void std_log(const struct v4l2_ctrl *ctrl) 
static int std_validate(const struct v4l2_ctrl *ctrl, u32 idx,

			union v4l2_ctrl_ptr ptr)

{

	struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params;

	size_t len;

	u64 offset;

	s64 val;
@@ -1612,6 +1621,54 @@ static int std_validate(const struct v4l2_ctrl *ctrl, u32 idx, 
			return -ERANGE;

		return 0;



	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		p_mpeg2_slice_params = ptr.p;



		switch (p_mpeg2_slice_params->sequence.chroma_format) {

		case 1: /* 4:2:0 */

		case 2: /* 4:2:2 */

		case 3: /* 4:4:4 */

			break;

		default:

			return -EINVAL;

		}



		switch (p_mpeg2_slice_params->picture.intra_dc_precision) {

		case 0: /* 8 bits */

		case 1: /* 9 bits */

		case 11: /* 11 bits */

			break;

		default:

			return -EINVAL;

		}



		switch (p_mpeg2_slice_params->picture.picture_structure) {

		case 1: /* interlaced top field */

		case 2: /* interlaced bottom field */

		case 3: /* progressive */

			break;

		default:

			return -EINVAL;

		}



		switch (p_mpeg2_slice_params->picture.picture_coding_type) {

		case V4L2_MPEG2_PICTURE_CODING_TYPE_I:

		case V4L2_MPEG2_PICTURE_CODING_TYPE_P:

		case V4L2_MPEG2_PICTURE_CODING_TYPE_B:

			break;

		default:

			return -EINVAL;

		}



		if (p_mpeg2_slice_params->backward_ref_index >= VIDEO_MAX_FRAME ||

		    p_mpeg2_slice_params->forward_ref_index >= VIDEO_MAX_FRAME)

			return -EINVAL;



		return 0;



	case V4L2_CTRL_TYPE_MPEG2_QUANTIZATION:

		return 0;



	default:

		return -EINVAL;

	}
@@ -2186,6 +2243,12 @@ static struct v4l2_ctrl *v4l2_ctrl_new(struct v4l2_ctrl_handler *hdl, 
	case V4L2_CTRL_TYPE_U32:

		elem_size = sizeof(u32);

		break;

	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		elem_size = sizeof(struct v4l2_ctrl_mpeg2_slice_params);

		break;

	case V4L2_CTRL_TYPE_MPEG2_QUANTIZATION:

		elem_size = sizeof(struct v4l2_ctrl_mpeg2_quantization);

		break;

	default:

		if (type < V4L2_CTRL_COMPOUND_TYPES)

			elem_size = sizeof(s32);