From 256fa3920874b0f1f4cb79ad6766493a22187153 Mon Sep 17 00:00:00 2001 From: Paul Kocialkowski Date: Tue, 22 Oct 2019 12:26:52 -0300 Subject: media: v4l: Add definitions for HEVC stateless decoding This introduces the required definitions for HEVC decoding support with stateless VPUs. The controls associated to the HEVC slice format provide the required meta-data for decoding slices extracted from the bitstream. They are not exported to the public V4L2 API since reworking this API will likely be needed for covering various use-cases and new hardware. Multi-slice decoding is exposed as a valid decoding mode to match current H.264 support but it is not yet implemented. The interface comes with the following limitations: * No custom quantization matrices (scaling lists); * Support for a single temporal layer only; * No slice entry point offsets support; * No conformance window support; * No VUI parameters support; * No support for SPS extensions: range, multilayer, 3d, scc, 4 bits; * No support for PPS extensions: range, multilayer, 3d, scc, 4 bits. Signed-off-by: Paul Kocialkowski [hverkuil-cisco@xs4all.nl: use 1ULL in flags defines in hevc-ctrls.h] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/biblio.rst | 9 + Documentation/media/uapi/v4l/ext-ctrls-codec.rst | 553 +++++++++++++++++++++- Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 18 + 3 files changed, 577 insertions(+), 3 deletions(-) (limited to 'Documentation/media/uapi') diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst index ad2ff258afa8..8095f57d3d75 100644 --- a/Documentation/media/uapi/v4l/biblio.rst +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -131,6 +131,15 @@ ITU-T Rec. H.264 Specification (04/2017 Edition) :author: International Telecommunication Union (http://www.itu.ch) +.. _hevc: + +ITU H.265/HEVC +============== + +:title: ITU-T Rec. H.265 | ISO/IEC 23008-2 "High Efficiency Video Coding" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + .. _jfif: JFIF diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index 6bb901de0939..a1209f68c5e8 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -1985,9 +1985,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - ``reference_ts`` - Timestamp of the V4L2 capture buffer to use as 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. + ``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. * - __u16 - ``frame_num`` - @@ -3695,3 +3695,550 @@ enum v4l2_mpeg_video_hevc_size_of_length_field - Indicates whether to generate SPS and PPS at every IDR. Setting it to 0 disables generating SPS and PPS at every IDR. Setting it to one enables generating SPS and PPS at every IDR. + +.. _v4l2-mpeg-hevc: + +``V4L2_CID_MPEG_VIDEO_HEVC_SPS (struct)`` + Specifies the Sequence Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.2 "Sequence parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_sps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``pic_width_in_luma_samples`` + - + * - __u16 + - ``pic_height_in_luma_samples`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``sps_max_dec_pic_buffering_minus1`` + - + * - __u8 + - ``sps_max_num_reorder_pics`` + - + * - __u8 + - ``sps_max_latency_increase_plus1`` + - + * - __u8 + - ``log2_min_luma_coding_block_size_minus3`` + - + * - __u8 + - ``log2_diff_max_min_luma_coding_block_size`` + - + * - __u8 + - ``log2_min_luma_transform_block_size_minus2`` + - + * - __u8 + - ``log2_diff_max_min_luma_transform_block_size`` + - + * - __u8 + - ``max_transform_hierarchy_depth_inter`` + - + * - __u8 + - ``max_transform_hierarchy_depth_intra`` + - + * - __u8 + - ``pcm_sample_bit_depth_luma_minus1`` + - + * - __u8 + - ``pcm_sample_bit_depth_chroma_minus1`` + - + * - __u8 + - ``log2_min_pcm_luma_coding_block_size_minus3`` + - + * - __u8 + - ``log2_diff_max_min_pcm_luma_coding_block_size`` + - + * - __u8 + - ``num_short_term_ref_pic_sets`` + - + * - __u8 + - ``num_long_term_ref_pics_sps`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u64 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags ` + +.. _hevc_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_HEVC_SPS_FLAG_SCALING_LIST_ENABLED`` + - 0x00000002 + - + * - ``V4L2_HEVC_SPS_FLAG_AMP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SPS_FLAG_SAMPLE_ADAPTIVE_OFFSET`` + - 0x00000008 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_ENABLED`` + - 0x00000010 + - + * - ``V4L2_HEVC_SPS_FLAG_PCM_LOOP_FILTER_DISABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT`` + - 0x00000040 + - + * - ``V4L2_HEVC_SPS_FLAG_SPS_TEMPORAL_MVP_ENABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SPS_FLAG_STRONG_INTRA_SMOOTHING_ENABLED`` + - 0x00000100 + - + +``V4L2_CID_MPEG_VIDEO_HEVC_PPS (struct)`` + Specifies the Picture Parameter Set fields (as extracted from the + bitstream) for the associated HEVC slice data. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.3.3 "Picture parameter set RBSP + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_pps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``num_extra_slice_header_bits`` + - + * - __s8 + - ``init_qp_minus26`` + - + * - __u8 + - ``diff_cu_qp_delta_depth`` + - + * - __s8 + - ``pps_cb_qp_offset`` + - + * - __s8 + - ``pps_cr_qp_offset`` + - + * - __u8 + - ``num_tile_columns_minus1`` + - + * - __u8 + - ``num_tile_rows_minus1`` + - + * - __u8 + - ``column_width_minus1[20]`` + - + * - __u8 + - ``row_height_minus1[22]`` + - + * - __s8 + - ``pps_beta_offset_div2`` + - + * - __s8 + - ``pps_tc_offset_div2`` + - + * - __u8 + - ``log2_parallel_merge_level_minus2`` + - + * - __u8 + - ``padding[4]`` + - Applications and drivers must set this to zero. + * - __u64 + - ``flags`` + - See :ref:`Picture Parameter Set Flags ` + +.. _hevc_pps_flags: + +``Picture Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_PPS_FLAG_DEPENDENT_SLICE_SEGMENT`` + - 0x00000001 + - + * - ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT`` + - 0x00000002 + - + * - ``V4L2_HEVC_PPS_FLAG_SIGN_DATA_HIDING_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT`` + - 0x00000008 + - + * - ``V4L2_HEVC_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSFORM_SKIP_ENABLED`` + - 0x00000020 + - + * - ``V4L2_HEVC_PPS_FLAG_CU_QP_DELTA_ENABLED`` + - 0x00000040 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT`` + - 0x00000080 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000100 + - + * - ``V4L2_HEVC_PPS_FLAG_WEIGHTED_BIPRED`` + - 0x00000200 + - + * - ``V4L2_HEVC_PPS_FLAG_TRANSQUANT_BYPASS_ENABLED`` + - 0x00000400 + - + * - ``V4L2_HEVC_PPS_FLAG_TILES_ENABLED`` + - 0x00000800 + - + * - ``V4L2_HEVC_PPS_FLAG_ENTROPY_CODING_SYNC_ENABLED`` + - 0x00001000 + - + * - ``V4L2_HEVC_PPS_FLAG_LOOP_FILTER_ACROSS_TILES_ENABLED`` + - 0x00002000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00004000 + - + * - ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED`` + - 0x00008000 + - + * - ``V4L2_HEVC_PPS_FLAG_PPS_DISABLE_DEBLOCKING_FILTER`` + - 0x00010000 + - + * - ``V4L2_HEVC_PPS_FLAG_LISTS_MODIFICATION_PRESENT`` + - 0x00020000 + - + * - ``V4L2_HEVC_PPS_FLAG_SLICE_SEGMENT_HEADER_EXTENSION_PRESENT`` + - 0x00040000 + - + +``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS (struct)`` + Specifies various slice-specific parameters, especially from the NAL unit + header, general slice segment header and weighted prediction parameter + parts of the bitstream. + These bitstream parameters are defined according to :ref:`hevc`. + They are described in section 7.4.7 "General slice segment header + semantics" of the specification. + +.. c:type:: v4l2_ctrl_hevc_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_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. + * - __u8 + - ``nal_unit_type`` + - + * - __u8 + - ``nuh_temporal_id_plus1`` + - + * - __u8 + - ``slice_type`` + - + (V4L2_HEVC_SLICE_TYPE_I, V4L2_HEVC_SLICE_TYPE_P or + V4L2_HEVC_SLICE_TYPE_B). + * - __u8 + - ``colour_plane_id`` + - + * - __u16 + - ``slice_pic_order_cnt`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - + * - __u8 + - ``collocated_ref_idx`` + - + * - __u8 + - ``five_minus_max_num_merge_cand`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_cb_qp_offset`` + - + * - __s8 + - ``slice_cr_qp_offset`` + - + * - __s8 + - ``slice_act_y_qp_offset`` + - + * - __s8 + - ``slice_act_cb_qp_offset`` + - + * - __s8 + - ``slice_act_cr_qp_offset`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __s8 + - ``slice_tc_offset_div2`` + - + * - __u8 + - ``pic_struct`` + - + * - __u8 + - ``num_active_dpb_entries`` + - The number of entries in ``dpb``. + * - __u8 + - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L0 reference elements as indices in the DPB. + * - __u8 + - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The list of L1 reference elements as indices in the DPB. + * - __u8 + - ``num_rps_poc_st_curr_before`` + - The number of reference pictures in the short-term set that come before + the current frame. + * - __u8 + - ``num_rps_poc_st_curr_after`` + - The number of reference pictures in the short-term set that come after + the current frame. + * - __u8 + - ``num_rps_poc_lt_curr`` + - The number of reference pictures in the long-term set. + * - __u8 + - ``padding[7]`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_hevc_dpb_entry` + - ``dpb[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The decoded picture buffer, for meta-data about reference frames. + * - struct :c:type:`v4l2_hevc_pred_weight_table` + - ``pred_weight_table`` + - The prediction weight coefficients for inter-picture prediction. + * - __u64 + - ``flags`` + - See :ref:`Slice Parameters Flags ` + +.. _hevc_slice_params_flags: + +``Slice Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_LUMA`` + - 0x00000001 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_SAO_CHROMA`` + - 0x00000002 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` + - 0x00000004 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_MVD_L1_ZERO`` + - 0x00000008 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_CABAC_INIT`` + - 0x00000010 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_COLLOCATED_FROM_L0`` + - 0x00000020 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_USE_INTEGER_MV`` + - 0x00000040 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` + - 0x00000080 + - + * - ``V4L2_HEVC_SLICE_PARAMS_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00000100 + - + +.. c:type:: v4l2_hevc_dpb_entry + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_hevc_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the V4L2 capture buffer to use as 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. + * - __u8 + - ``rps`` + - The reference set for the reference frame + (V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_BEFORE, + V4L2_HEVC_DPB_ENTRY_RPS_ST_CURR_AFTER or + V4L2_HEVC_DPB_ENTRY_RPS_LT_CURR) + * - __u8 + - ``field_pic`` + - Whether the reference is a field picture or a frame. + * - __u16 + - ``pic_order_cnt[2]`` + - The picture order count of the reference. Only the first element of the + array is used for frame pictures, while the first element identifies the + top field and the second the bottom field in field-coded pictures. + * - __u8 + - ``padding[2]`` + - Applications and drivers must set this to zero. + +.. c:type:: v4l2_hevc_pred_weight_table + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_hevc_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``luma_log2_weight_denom`` + - + * - __s8 + - ``delta_chroma_log2_weight_denom`` + - + * - __s8 + - ``delta_luma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - + * - __s8 + - ``luma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - + * - __s8 + - ``delta_chroma_weight_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - + * - __s8 + - ``chroma_offset_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - + * - __s8 + - ``delta_luma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - + * - __s8 + - ``luma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - + * - __s8 + - ``delta_chroma_weight_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - + * - __s8 + - ``chroma_offset_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX][2]`` + - + * - __u8 + - ``padding[6]`` + - Applications and drivers must set this to zero. + +``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE (enum)`` + Specifies the decoding mode to use. Currently exposes slice-based and + frame-based decoding but new modes might be added later on. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the decoding mode + that is expected for the buffer. + Drivers may expose a single or multiple decoding modes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_hevc_decode_mode + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_SLICE_BASED`` + - 0 + - Decoding is done at the slice granularity. + The OUTPUT buffer must contain a single slice. + * - ``V4L2_MPEG_VIDEO_HEVC_DECODE_MODE_FRAME_BASED`` + - 1 + - Decoding is done at the frame granularity. + The OUTPUT buffer must contain all slices needed to decode the + frame. The OUTPUT buffer must also contain both fields. + +``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE (enum)`` + Specifies the HEVC slice start code expected for each slice. + This control is used as a modifier for V4L2_PIX_FMT_HEVC_SLICE + pixel format. Applications that support V4L2_PIX_FMT_HEVC_SLICE + are required to set this control in order to specify the start code + that is expected for the buffer. + Drivers may expose a single or multiple start codes, depending + on what they can support. + + .. note:: + + This menu control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_mpeg_video_hevc_start_code + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_NONE`` + - 0 + - Selecting this value specifies that HEVC slices are passed + to the driver without any start code. + * - ``V4L2_MPEG_VIDEO_HEVC_START_CODE_ANNEX_B`` + - 1 + - Selecting this value specifies that HEVC slices are expected + to be prefixed by Annex B start codes. According to :ref:`hevc` + valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001. diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index 33aff21b7d11..6690928e657b 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -479,6 +479,24 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 decode parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_SPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_sps`, containing HEVC Sequence + Parameter Set for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_PPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_pps`, containing HEVC Picture + Parameter Set for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_slice_params`, containing HEVC + slice parameters for stateless video decoders. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| -- cgit v1.2.3-59-g8ed1b