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

media: uapi: mpeg2: Split sequence and picture parameters 



Typically, bitstreams are composed of a sequence header,
followed by a number of picture header and picture coding extension
headers. Each picture can be composed of a number of slices.

Let's split the MPEG-2 uAPI to follow these semantics more closely,
allowing more usage flexibility. Having these controls split up
allows applications to set a sequence control at the beginning
of a sequence, and then set a picture control for each frame.

While here add padding fields where needed, and document
the uAPI header thoroughly.

Note that the V4L2_CTRL_TYPE_{} defines had to be moved because
it clashes with existing ones. This is not really an issue
since they will be re-defined when the controls are moved
out of staging.

Signed-off-by: default avatarEzequiel Garcia <ezequiel@collabora.com>
Tested-by: default avatarJonas Karlman <jonas@kwiboo.se>
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 88e78409

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

+42 −22
Original line number Diff line number Diff line
@@ -1636,14 +1636,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 
    * - __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.

    * - __u64

      - ``backward_ref_ts``

      - Timestamp of the V4L2 capture buffer to use as backward reference, used
@@ -1661,14 +1653,28 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 
    * - __u32

      - ``quantiser_scale_code``

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

    * - __u8

      - ``reserved``

      - Applications and drivers must set this to zero.



.. c:type:: v4l2_mpeg2_sequence

``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_mpeg2_sequence

.. flat-table:: struct v4l2_ctrl_mpeg2_sequence

    :header-rows:  0

    :stub-columns: 0

    :widths:       1 1 2
@@ -1690,7 +1696,7 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 
    * - __u8

      - ``chroma_format``

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

    * - __u32

    * - __u8

      - ``flags``

      - See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`.
@@ -1706,11 +1712,22 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 
    :widths:       1 1 2



    * - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE``

      - 0x00000001

      - 0x01

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

	of interlaced.



.. c:type:: v4l2_mpeg2_picture

``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
@@ -1720,30 +1737,33 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - 


.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}|



.. flat-table:: struct v4l2_mpeg2_picture

.. flat-table:: struct v4l2_ctrl_mpeg2_picture

    :header-rows:  0

    :stub-columns: 0

    :widths:       1 1 2



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

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

      - Motion vector codes.

      - ``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

      - ``picture_structure``

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

	3: progressive frame).

    * - __u32

      - ``flags``

      - See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`.

      - ``reserved[5]``

      - Applications and drivers must set this to zero.





.. _mpeg2_picture_flags:

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

+3 −2
Original line number Diff line number Diff line
@@ -114,8 +114,9 @@ Compressed Formats 
	This format is adapted for stateless video decoders that implement a

	MPEG-2 pipeline (using the :ref:`mem2mem` 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

	quantisation matrices can optionally be specified through the

	through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE``,

        ``V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE``, and ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS``

        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>`.

	Exactly one output and one capture buffer must be provided for use with

Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst

+12 −0
Original line number Diff line number Diff line
@@ -429,6 +429,18 @@ See also the examples in :ref:`control`. 
      - n/a

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

	quantisation matrices for stateless video decoders.

    * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``

      - n/a

      - n/a

      - n/a

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

	sequence parameters for stateless video decoders.

    * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``

      - n/a

      - n/a

      - n/a

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

	picture parameters for stateless video decoders.

    * - ``V4L2_CTRL_TYPE_AREA``

      - n/a

      - n/a

Documentation/userspace-api/media/videodev2.h.rst.exceptions

+2 −0
Original line number Diff line number Diff line
@@ -134,6 +134,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_SEQUENCE :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`v4l2_ctrl_type`

replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type`

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

+44 −12
Original line number Diff line number Diff line
@@ -977,6 +977,8 @@ 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_SLICE_PARAMS:		return "MPEG-2 Slice Parameters";

	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";
@@ -1499,6 +1501,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_SEQUENCE:

		*type = V4L2_CTRL_TYPE_MPEG2_SEQUENCE;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE:

		*type = V4L2_CTRL_TYPE_MPEG2_PICTURE;

		break;

	case V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS:

		*type = V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS;

		break;
@@ -1703,7 +1711,8 @@ static bool std_equal(const struct v4l2_ctrl *ctrl, u32 idx, 
static void std_init_compound(const struct v4l2_ctrl *ctrl, u32 idx,

			      union v4l2_ctrl_ptr ptr)

{

	struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params;

	struct v4l2_ctrl_mpeg2_sequence *p_mpeg2_sequence;

	struct v4l2_ctrl_mpeg2_picture *p_mpeg2_picture;

	struct v4l2_ctrl_mpeg2_quantisation *p_mpeg2_quant;

	struct v4l2_ctrl_vp8_frame *p_vp8_frame;

	struct v4l2_ctrl_fwht_params *p_fwht_params;
@@ -1720,13 +1729,18 @@ static void std_init_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
	 * v4l2_ctrl_type enum.

	 */

	switch ((u32)ctrl->type) {

	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		p_mpeg2_slice_params = p;

	case V4L2_CTRL_TYPE_MPEG2_SEQUENCE:

		p_mpeg2_sequence = p;



		/* 4:2:0 */

		p_mpeg2_slice_params->sequence.chroma_format = 1;

		p_mpeg2_sequence->chroma_format = 1;

		break;

	case V4L2_CTRL_TYPE_MPEG2_PICTURE:

		p_mpeg2_picture = p;



		/* interlaced top field */

		p_mpeg2_slice_params->picture.picture_structure = 1;

		p_mpeg2_slice_params->picture.picture_coding_type =

		p_mpeg2_picture->picture_structure = V4L2_MPEG2_PIC_TOP_FIELD;

		p_mpeg2_picture->picture_coding_type =

					V4L2_MPEG2_PIC_CODING_TYPE_I;

		break;

	case V4L2_CTRL_TYPE_MPEG2_QUANTISATION:
@@ -1909,6 +1923,8 @@ static void std_log(const struct v4l2_ctrl *ctrl) 
static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx,

				 union v4l2_ctrl_ptr ptr)

{

	struct v4l2_ctrl_mpeg2_sequence *p_mpeg2_sequence;

	struct v4l2_ctrl_mpeg2_picture *p_mpeg2_picture;

	struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params;

	struct v4l2_ctrl_vp8_frame *p_vp8_frame;

	struct v4l2_ctrl_fwht_params *p_fwht_params;
@@ -1926,10 +1942,10 @@ static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
	unsigned int i;



	switch ((u32)ctrl->type) {

	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		p_mpeg2_slice_params = p;

	case V4L2_CTRL_TYPE_MPEG2_SEQUENCE:

		p_mpeg2_sequence = p;



		switch (p_mpeg2_slice_params->sequence.chroma_format) {

		switch (p_mpeg2_sequence->chroma_format) {

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

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

		case 3: /* 4:4:4 */
@@ -1937,8 +1953,12 @@ static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
		default:

			return -EINVAL;

		}

		break;



	case V4L2_CTRL_TYPE_MPEG2_PICTURE:

		p_mpeg2_picture = p;



		switch (p_mpeg2_slice_params->picture.intra_dc_precision) {

		switch (p_mpeg2_picture->intra_dc_precision) {

		case 0: /* 8 bits */

		case 1: /* 9 bits */

		case 2: /* 10 bits */
@@ -1948,7 +1968,7 @@ static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
			return -EINVAL;

		}



		switch (p_mpeg2_slice_params->picture.picture_structure) {

		switch (p_mpeg2_picture->picture_structure) {

		case V4L2_MPEG2_PIC_TOP_FIELD:

		case V4L2_MPEG2_PIC_BOTTOM_FIELD:

		case V4L2_MPEG2_PIC_FRAME:
@@ -1957,7 +1977,7 @@ static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
			return -EINVAL;

		}



		switch (p_mpeg2_slice_params->picture.picture_coding_type) {

		switch (p_mpeg2_picture->picture_coding_type) {

		case V4L2_MPEG2_PIC_CODING_TYPE_I:

		case V4L2_MPEG2_PIC_CODING_TYPE_P:

		case V4L2_MPEG2_PIC_CODING_TYPE_B:
@@ -1965,7 +1985,13 @@ static int std_validate_compound(const struct v4l2_ctrl *ctrl, u32 idx, 
		default:

			return -EINVAL;

		}

		zero_reserved(*p_mpeg2_picture);

		break;



	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		p_mpeg2_slice_params = p;



		zero_reserved(*p_mpeg2_slice_params);

		break;



	case V4L2_CTRL_TYPE_MPEG2_QUANTISATION:
@@ -2934,6 +2960,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_SEQUENCE:

		elem_size = sizeof(struct v4l2_ctrl_mpeg2_sequence);

		break;

	case V4L2_CTRL_TYPE_MPEG2_PICTURE:

		elem_size = sizeof(struct v4l2_ctrl_mpeg2_picture);

		break;

	case V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS:

		elem_size = sizeof(struct v4l2_ctrl_mpeg2_slice_params);

		break;