From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: smtp.subspace.kernel.org; arc=pass header.oldest-pass=0 smtp.remote-ip=100.103.45.18 ARC-Seal: i=2; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; cv=pass; t=1794305260; b=IyEm2eaxC1zQYpYXu8wPCuI8y6ndneDblhaTNx0wY4aOMHDH51k4cyAaUz1OmeY3mZ/A Ez4CZAA5y2k8xOtVNk4gCOmFL7jZYAzE9iZHPhA9VQ/n71ibZSuXsGtt22D/4WmIHOtNp SPaSn85N20KS2HWeJ/j7RKjaOkj3xM43DPaPCvFHA9hGFyInjj3UULeTMl7J4LD303wya FEL5QINCVd2F2L0OvtiCKUNcpc3ZDdDYO+KuBihTn4//nVmQSrFbkPl1r3jvY+7c2egkC Ia/wuBuZNnaSOcMxAmynFTQn8JELIutjL3z7zKkZi2rUME9gLRfbVvzVVLXasbqRG7A== ARC-Message-Signature: i=2; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; c=relaxed/relaxed; t=1794305260; h=Received:DKIM-Signature:Received:From:Date:Subject:MIME-Version: Content-Type:Message-Id:References:In-Reply-To:To:Cc:X-Mailer: X-Developer-Signature:X-Developer-Key:X-Endpoint-Received: X-Original-From:Reply-To:Content-Transfer-Encoding; bh=RvrcjA6Xqi7N/NUN+91OzDgqBAzlP1uXHryD1DRhBkE=; b=bRXxqCb0ZwmsEaCG5k+tqZ1r/R6ddKQR6UjJbUJGsn4b3iIIsPjpt7zNJBoCm5hKA9dN CVPkYkUinzC6RB1VCQaJD9zEi8rL4jm4pCsmRFC3kTBNpNqIHzSyjCpM+vHmGVthrjmZq GjjccR7i/L6vfintFqnYNKmvFxCOFx2wcC+qN/l3HQLHSf8Lin6HeKd2WHfrScLSpD8HT GnC9yRhbd73tu6+SSxQpQz2vd/QX8EWdGVUhK8FJLqPjhiff3yTrVmudO8nF3Gfo1SXhS vc4jAADVOKJ9tEZxze8fgGZPXbbr8+yX9XxLnnwrDyj7JDNGKwCUh+qzUEhoA1VSbJA== ARC-Authentication-Results: i=2; smtp.subspace.kernel.org; dkim=pass header.d=kernel.org header.i=@kernel.org header.a=rsa-sha256 header.s=k20260515 header.b=lgOiK7+4; arc=pass header.oldest-pass=0 smtp.remote-ip=100.103.45.18 Received: from smtp.kernel.org (quasi.space.kernel.org [100.103.45.18]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0419060A381A; Tue, 10 Nov 2026 10:07:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.a=rsa-sha256 header.s=k20260515 header.b=lgOiK7+4 Authentication-Results: smtp.kernel.org; arc=none smtp.remote-ip=100.80.115.77 ARC-Seal: i=1; d=kernel.org; s=arc20260519; a=rsa-sha256; cv=none; t=1794305259; b=kzV4VDNF3igK8f+ctHhvqFsFM6Z1eKUwdTFcf/PTmtl9czrXRDMUp7FiERgg3gNMY+RG 1yRW9btVgJHCWDKvSnPGsjEfnc2eYDEsbQ7a6CLYaXGAzxjGcfW11b1Qu7lbuGgZ5oduv rXuZ92VWmJzp8TvSBy5T8lQhkGsVYyv7wjHzWq6fKT1LIr0mAKRrhYNBIItwWOLRKRMW9 VCEhTp9jzrzjgTXWVyUdfXpGEQqtYql93VWA0rrpDDrlaHyTmYBYkCmtLGlkWQhdo2V4k u8d6QCx1vnZ1WcT0s2fCfY+eOfeAWVJTGKJaGyx8MkHjjOtYCQdTzfkACJjc7Ue7wMw== ARC-Message-Signature: i=1; d=kernel.org; s=arc20260519; a=rsa-sha256; c=relaxed/relaxed; t=1794305259; h=DKIM-Signature:Received:From:Date:Subject:MIME-Version:Content-Type: Message-Id:References:In-Reply-To:To:Cc:X-Mailer: X-Developer-Signature:X-Developer-Key:X-Endpoint-Received: X-Original-From:Reply-To:Content-Transfer-Encoding; bh=RvrcjA6Xqi7N/NUN+91OzDgqBAzlP1uXHryD1DRhBkE=; b=T4y/1veIrH4HP027FZrfWclZbNdXg39hvcujCwj85l76+2aJ4Y1OzHIuKvWdURMGNI2j kIBZ0tjIMzotkixZxUr4KHHq9ZI5DT/Q4lJpFugBa7hjczR9ziepJmr8v63se+gH9SPJO FFfBJlQMDpreT9Dgx80gqdlMc5dwihl7IsCKLCRmniRWnGZvep1o0P4GHVNnymVQIQQqh hKvNpV1zzUL0vIBf6DS1pJhhLdlueyZazIctx+Df6d1bsEVb82XHl8e6sCHSxl8ryJ73p FTYlVfI16Ynf0uQAI0aAOv2VUiWKprOcvz3dYRdwcU4OQxMmu/I+cMrlDEeF2iDHmVw== ARC-Authentication-Results: i=1; smtp.kernel.org; arc=none smtp.remote-ip=100.80.115.77 Received: from lkml.kernel.org (nexus.subspace.kernel.org [100.80.115.77]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by smtp.kernel.org (Postfix) with ESMTPS id 72F571F00903; Tue, 10 Nov 2026 10:07:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kernel.org; s=k20260515; t=1794305259; bh=RvrcjA6Xqi7N/NUN+91OzDgqBAzlP1uXHryD1DRhBkE=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To; b=lgOiK7+4EVDPdk/AUH1nLpDj0HqnxWoeobe4M4VxciWwhB5G8RwUwGRchzPA9ALCZ vktGxM6W4kPV67JB4MSPcs2DRN5xtNA2mMXEjjfYUBGmXXp8kRPvafvPF7hvXs5pS4 lhzfvBrUv3ECCMa+zrWBIWCHOTj4o2ry1SzhRUvphijbOGvsXw6Kq551WRtItbyfXy hK2sY5pV0e4n1nVubheWL4B5dCOP+TXYA7HfHyH1wta1Nf/+74rVMwAQgWozp+zDhn cqA5LiKAMQh7YRAg6uOQY11/2+Vgo8sgvul4Z5+h8I7j941NBdYjArQFSUI3P0G0BH Wz3Sv9sYLAA2A== Received: from nexus.subspace.kernel.org (localhost [IPv6:::1]) by lkml.kernel.org (Postfix) with ESMTP id 93BD548AC6; Tue, 10 Nov 2026 10:07:32 +0000 (UTC) From: Arun Iyengar via B4 Relay Date: Tue, 10 Nov 2026 10:07:40 +0000 Subject: [PATCH RFC 10/10] media: docs: Document the HEVC stateless encode uAPI X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Message-Id: <20261110-hevc-encode-uapi-v1-10-38ae9fcfedd4@gmail.com> References: <20261110-hevc-encode-uapi-v1-0-38ae9fcfedd4@gmail.com> In-Reply-To: <20261110-hevc-encode-uapi-v1-0-38ae9fcfedd4@gmail.com> To: Mauro Carvalho Chehab Cc: linux-media@vger.kernel.org, linux-kernel@vger.kernel.org, Paul Kocialkowski , Nicolas Dufresne , Hans Verkuil , Arun Iyengar X-Mailer: b4 0.15.2 X-Developer-Signature: v=1; a=ed25519-sha256; t=1794305251; l=22881; i=aiyengar1990@gmail.com; s=20261110; h=from:subject:message-id; bh=UZys/F/CdxHPzt3fAbOth3r1tKO5RLfRFaMupnn/Opg=; b=44cAJgm/VawVn4VXu6qUJ9cDmd/yuILvHTvbQWsQg6YQ1GMcay1lXGR5XN4ryjJ/wdkoqTDJT VEiSVkcHA2xBnjSwHIIw6mxXplo7Nj2/chZqvJvTD2bAbYUdM91PHXP X-Developer-Key: i=aiyengar1990@gmail.com; a=ed25519; pk=zXpRgUTrhaFe6jLyPqbBy3ccfkj04w0g2690Wv3mg+0= X-Endpoint-Received: by B4 Relay for aiyengar1990@gmail.com/20261110 with auth_id=1480 X-Original-From: Arun Iyengar Reply-To: aiyengar1990@gmail.com Content-Transfer-Encoding: 7bit From: Arun Iyengar Describe how a stateless HEVC encoder is used: the CAPTURE format and what each buffer receives, which parts of the parameter sets the kernel derives from the format, frame interval and stateful codec controls, how the QP is selected, how reference pictures are identified and kept, and how per-picture feedback is read back from completed requests. Document the V4L2_CID_STATELESS_HEVC_ENCODE_PARAMS and V4L2_CID_STATELESS_HEVC_ENCODE_FEEDBACK controls with their structures and flags, and the codec-agnostic struct v4l2_stateless_encode_stats, and add the new control types to the VIDIOC_QUERYCTRL and VIDIOC_G_EXT_CTRLS references. Signed-off-by: Arun Iyengar --- .../media/v4l/ext-ctrls-codec-stateless.rst | 411 +++++++++++++++++++++ .../userspace-api/media/v4l/pixfmt-compressed.rst | 3 + .../media/v4l/videodev2.h.rst.exceptions | 2 + .../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst | 8 + .../userspace-api/media/v4l/vidioc-queryctrl.rst | 12 + 5 files changed, 436 insertions(+) diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index d7a3b8ef03a7..177940a6f987 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -3079,6 +3079,417 @@ This structure contains all loop filter related parameters. See sections - Specifies if the short-term RPS is predicted from another short term RPS. See details in section 7.4.8 "Short-term reference picture set semantics" of the specification. +.. _v4l2-codec-stateless-hevc-encode: + +.. rubric:: HEVC stateless encoding + +A stateless HEVC encoder exposes ``V4L2_PIX_FMT_HEVC_SLICE`` on its CAPTURE +queue. Each CAPTURE buffer receives one complete access unit, with the start +codes selected by ``V4L2_CID_STATELESS_HEVC_START_CODE``. Applications set +the sequence and picture parameters with the ``V4L2_CID_STATELESS_HEVC_SPS`` +and ``V4L2_CID_STATELESS_HEVC_PPS`` controls, and the parameters of each +picture with ``V4L2_CID_STATELESS_HEVC_ENCODE_PARAMS``, in the request of the +OUTPUT buffer that holds the picture to encode. + +The kernel writes the video, sequence and picture parameter sets, and the +slice segment headers, unless the hardware writes them itself. It derives the +parts of the parameter sets that the SPS and PPS controls do not carry from +the rest of the configuration: + +- the coded size from the CAPTURE format, aligned to the minimum coding block + size, and the conformance window from the difference with the visible size; +- the profile, tier and level from ``V4L2_CID_MPEG_VIDEO_HEVC_PROFILE``, + ``V4L2_CID_MPEG_VIDEO_HEVC_TIER`` and ``V4L2_CID_MPEG_VIDEO_HEVC_LEVEL`` + when the encoder exposes them (otherwise the lowest level that fits the + coded size and frame rate); +- the VUI timing information from the frame interval set with + :ref:`VIDIOC_S_PARM `, and the colour description from the + colorimetry of the format. + +The values of the SPS and PPS controls are adjusted to what the encoder +supports, and can be read back after the encode run. A changed SPS only takes +effect with the next IRAP picture. + +The quantisation parameter comes from the stateful codec controls: from +``V4L2_CID_MPEG_VIDEO_HEVC_I_FRAME_QP``, ``V4L2_CID_MPEG_VIDEO_HEVC_P_FRAME_QP`` +and ``V4L2_CID_MPEG_VIDEO_HEVC_B_FRAME_QP`` when +``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE`` is 0, otherwise from the rate control +mode selected by ``V4L2_CID_MPEG_VIDEO_BITRATE_MODE``, within +``V4L2_CID_MPEG_VIDEO_HEVC_MIN_QP`` and ``V4L2_CID_MPEG_VIDEO_HEVC_MAX_QP``. +These controls can be part of the request too. + +Reference pictures are identified by the timestamp of the OUTPUT buffer they +were encoded from. The encoder keeps the reconstructed pictures internally: +a picture is kept when it is encoded with +``V4L2_HEVC_ENCODE_FLAG_REFERENCE`` and as long as each following picture +lists it in its reference picture set. When an encode run fails, the set of +kept pictures does not change. + +How each picture was encoded is reported by the read-only +``V4L2_CID_STATELESS_HEVC_ENCODE_FEEDBACK`` control. Applications do not set +it in requests, so its value at the end of the encode run is stored in the +request, and can be read with :ref:`VIDIOC_G_EXT_CTRLS ` +once the request completed. + +``V4L2_CID_STATELESS_HEVC_ENCODE_PARAMS (struct)`` + Specifies the parameters of the picture to encode: its NAL unit header, + the slice segment header syntax elements that are not derived from other + controls, and its reference picture set. These parameters are defined + according to :ref:`hevc`, sections 7.3.1.2 "NAL unit header syntax" and + 7.3.6 "Slice segment header syntax". When the picture is encoded as + several slices, all of them use these parameters. + +.. c:type:: v4l2_ctrl_hevc_encode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_encode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``nal_unit_type`` + - NAL unit type of the slice segments of the picture, from Table 7-1 of + the specification: one of the VCL types 0 (TRAIL_N) to 9 (RASL_R) + and 16 (BLA_W_LP) to 21 (CRA_NUT). The first picture is an IRAP + picture (16 to 21). + * - __u8 + - ``nuh_temporal_id_plus1`` + - TemporalId of the picture plus 1, from 1 to + ``sps_max_sub_layers_minus1`` + 1. It is 1 for IRAP pictures and + greater than 1 for TSA and STSA pictures. + * - __u8 + - ``slice_type`` + - ``V4L2_HEVC_SLICE_TYPE_I``, ``V4L2_HEVC_SLICE_TYPE_P`` or + ``V4L2_HEVC_SLICE_TYPE_B``. IRAP pictures are I pictures. An encoder + that cannot encode P pictures encodes them as I pictures; one that + cannot encode B pictures rejects them. + * - __u8 + - ``pic_parameter_set_id`` + - Identifies the PPS in use. The encoder supports a single PPS and + sets the value of the PPS control. + * - __s32 + - ``pic_order_cnt_val`` + - PicOrderCntVal of the picture, as described in section 8.3.1 + "Decoding process for picture order count". It is 0 for IDR + pictures, and from 0 to MaxPicOrderCntLsb - 1 for BLA pictures and + for a CRA picture that starts the bitstream. Otherwise it differs by + less than MaxPicOrderCntLsb / 2 from the picture order count of the + previous picture with TemporalId 0 that is not a RASL, RADL or + sub-layer non-reference picture, so that a decoder can derive it. + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - Number of entries of reference picture list 0, minus 1, used with + ``V4L2_HEVC_ENCODE_FLAG_NUM_REF_IDX_ACTIVE_OVERRIDE``. Otherwise the + PPS default applies. The encoder limits it to what it supports. + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - Same for reference picture list 1. + * - __u8 + - ``collocated_ref_idx`` + - Reference index of the collocated picture used for temporal motion + vector prediction, in list 0 when + ``V4L2_HEVC_ENCODE_FLAG_COLLOCATED_FROM_L0`` is set, in list 1 + otherwise. + * - __u8 + - ``five_minus_max_num_merge_cand`` + - Maximum number of merging motion vector prediction candidates + subtracted from 5. + * - __s8 + - ``slice_cb_qp_offset`` + - Difference added to ``pps_cb_qp_offset``, used when the PPS has + ``V4L2_HEVC_PPS_FLAG_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT``. + * - __s8 + - ``slice_cr_qp_offset`` + - Difference added to ``pps_cr_qp_offset``, used likewise. + * - __s8 + - ``slice_beta_offset_div2`` + - Deblocking parameter offset for beta divided by 2, used with + ``V4L2_HEVC_ENCODE_FLAG_DEBLOCKING_FILTER_OVERRIDE``. + * - __s8 + - ``slice_tc_offset_div2`` + - Deblocking parameter offset for tC divided by 2, used likewise. + * - __u8 + - ``num_refs`` + - Number of valid entries in ``refs``, up to + ``sps_max_dec_pic_buffering_minus1``. + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_hevc_encode_ref` + - ``refs[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - The reference picture set of the picture: every previously encoded + picture that the current picture or a following picture uses for + prediction, in any order. The encoder computes the picture order + count differences, codes the RPS and builds the reference picture + lists without modification, as described in section 8.3.4. Pictures + that are not listed are removed from the decoded picture buffer. + IDR pictures have no reference picture set and BLA pictures discard + it. An encoder that uses a single reference picture uses the one + entry that is used by the current picture. + * - __u64 + - ``flags`` + - See :ref:`HEVC Encode Parameters Flags ` + +.. c:type:: v4l2_hevc_encode_ref + +.. flat-table:: struct v4l2_hevc_encode_ref + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the OUTPUT buffer from which the reference picture was + encoded. 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 + - ``flags`` + - See :ref:`HEVC Encode Reference Flags ` + * - __u8 + - ``reserved[7]`` + - Applications and drivers must set this to zero. + +.. _hevc_encode_ref_flags: + +``HEVC Encode Reference Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_ENCODE_REF_FLAG_USED_BY_CURR_PIC`` + - 0x01 + - The current picture uses the reference picture for inter prediction + (it is in PocStCurrBefore, PocStCurrAfter or PocLtCurr). Otherwise it + is only kept for following pictures. P and B pictures have at least + one used reference, IRAP pictures have none. + * - ``V4L2_HEVC_ENCODE_REF_FLAG_LONG_TERM`` + - 0x02 + - The reference picture is a long-term reference picture. This + requires ``V4L2_HEVC_SPS_FLAG_LONG_TERM_REF_PICS_PRESENT``. Once a + picture is a long-term reference picture, it stays one. + +.. _hevc_encode_params_flags: + +``HEVC Encode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_ENCODE_FLAG_SLICE_SAO_LUMA`` + - 0x00000001 + - slice_sao_luma_flag. Ignored unless the SPS enables SAO. + * - ``V4L2_HEVC_ENCODE_FLAG_SLICE_SAO_CHROMA`` + - 0x00000002 + - slice_sao_chroma_flag. Ignored unless the SPS enables SAO. + * - ``V4L2_HEVC_ENCODE_FLAG_SLICE_TEMPORAL_MVP_ENABLED`` + - 0x00000004 + - slice_temporal_mvp_enabled_flag. Ignored unless the SPS enables + temporal motion vector prediction. + * - ``V4L2_HEVC_ENCODE_FLAG_MVD_L1_ZERO`` + - 0x00000008 + - mvd_l1_zero_flag, for B pictures. + * - ``V4L2_HEVC_ENCODE_FLAG_CABAC_INIT`` + - 0x00000010 + - cabac_init_flag, used when the PPS has + ``V4L2_HEVC_PPS_FLAG_CABAC_INIT_PRESENT``. + * - ``V4L2_HEVC_ENCODE_FLAG_COLLOCATED_FROM_L0`` + - 0x00000020 + - collocated_from_l0_flag, for B pictures. Always set for P pictures. + * - ``V4L2_HEVC_ENCODE_FLAG_SLICE_DEBLOCKING_FILTER_DISABLED`` + - 0x00000080 + - slice_deblocking_filter_disabled_flag, used with + ``V4L2_HEVC_ENCODE_FLAG_DEBLOCKING_FILTER_OVERRIDE``. + * - ``V4L2_HEVC_ENCODE_FLAG_SLICE_LOOP_FILTER_ACROSS_SLICES_ENABLED`` + - 0x00000100 + - slice_loop_filter_across_slices_enabled_flag. + * - ``V4L2_HEVC_ENCODE_FLAG_REFERENCE`` + - 0x00010000 + - Keep the reconstructed picture so that following pictures can + reference it. Without this flag, the encoder may not store the + reconstruction at all. + * - ``V4L2_HEVC_ENCODE_FLAG_NO_OUTPUT_OF_PRIOR_PICS`` + - 0x00020000 + - no_output_of_prior_pics_flag, for IRAP pictures. + * - ``V4L2_HEVC_ENCODE_FLAG_NO_PIC_OUTPUT`` + - 0x00040000 + - pic_output_flag is 0, when the PPS has + ``V4L2_HEVC_PPS_FLAG_OUTPUT_FLAG_PRESENT``. + * - ``V4L2_HEVC_ENCODE_FLAG_NUM_REF_IDX_ACTIVE_OVERRIDE`` + - 0x00080000 + - Use ``num_ref_idx_l0_active_minus1`` and + ``num_ref_idx_l1_active_minus1`` instead of the PPS defaults. + * - ``V4L2_HEVC_ENCODE_FLAG_DEBLOCKING_FILTER_OVERRIDE`` + - 0x00100000 + - deblocking_filter_override_flag, used when the PPS has + ``V4L2_HEVC_PPS_FLAG_DEBLOCKING_FILTER_OVERRIDE_ENABLED``. + +The flags that carry a slice header syntax element have the same values as +the ``V4L2_HEVC_SLICE_PARAMS_FLAG_*`` flags of the same element. + +``V4L2_CID_STATELESS_HEVC_ENCODE_FEEDBACK (struct)`` + Read-only. Describes how a picture was encoded: the values the encoder + used where it adjusted or derived them, and statistics measured while + encoding. The encoder sets it when the encode run completes, so that it + is stored in the request. + +.. c:type:: v4l2_ctrl_hevc_encode_feedback + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_hevc_encode_feedback + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``timestamp`` + - Timestamp of the OUTPUT buffer that was encoded. + * - __s32 + - ``pic_order_cnt_val`` + - Picture order count of the picture. + * - __u8 + - ``nal_unit_type`` + - NAL unit type of the slice segments. + * - __u8 + - ``nuh_temporal_id_plus1`` + - TemporalId of the picture plus 1. + * - __u8 + - ``slice_type`` + - Slice type that was used. + * - __s8 + - ``slice_qp`` + - Luma quantisation parameter of the first slice (SliceQpY). + * - __u8 + - ``num_ref_idx_l0_active`` + - Number of entries in reference picture list 0. + * - __u8 + - ``num_ref_idx_l1_active`` + - Number of entries in reference picture list 1. + * - __u8 + - ``reserved0[2]`` + - Applications and drivers must set this to zero. + * - __u8 + - ``ref_idx_l0[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - For each entry of reference picture list 0, its index in the + ``refs`` array of the encode parameters. + * - __u8 + - ``ref_idx_l1[V4L2_HEVC_DPB_ENTRIES_NUM_MAX]`` + - Same for reference picture list 1. + * - __u8 + - ``reserved1[4]`` + - Applications and drivers must set this to zero. + * - struct :c:type:`v4l2_stateless_encode_stats` + - ``stats`` + - Statistics measured while encoding the picture. + * - __u64 + - ``flags`` + - See :ref:`HEVC Encode Feedback Flags ` + +.. _hevc_encode_feedback_flags: + +``HEVC Encode Feedback Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_HEVC_ENCODE_FEEDBACK_FLAG_REFERENCE`` + - 0x00000001 + - The reconstructed picture was kept for reference. + +.. c:type:: v4l2_stateless_encode_stats + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_stateless_encode_stats + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``flags`` + - Which statistics are valid, see + :ref:`Stateless Encode Statistics Flags `. + The fields of the statistics that are not valid are zero. + * - __u32 + - ``header_size`` + - Number of bytes written by the kernel at the start of the CAPTURE + buffer (parameter sets, access unit delimiter, slice header) before + the data produced by the hardware. Always valid. + * - __u32 + - ``qp_sum`` + - Sum of the luma quantisation parameters of the blocks counted in + ``qp_count``. + * - __u32 + - ``qp_count`` + - Number of blocks summed in ``qp_sum``: ``qp_sum`` / ``qp_count`` is + the average QP of the picture. + * - __s8 + - ``qp_min`` + - Smallest luma quantisation parameter used in the picture. + * - __s8 + - ``qp_max`` + - Largest luma quantisation parameter used in the picture. + * - __u8 + - ``reserved0[6]`` + - Applications and drivers must set this to zero. + * - __u64 + - ``sse_luma`` + - Sum of squared errors between the source and reconstructed luma + samples, from which the PSNR of the picture can be computed. + * - __u32 + - ``num_intra_blocks`` + - Number of 8x8 luma blocks coded with intra prediction. + * - __u32 + - ``num_inter_blocks`` + - Number of 8x8 luma blocks coded with inter prediction, skipped + blocks included. + * - __u32 + - ``num_skip_blocks`` + - Number of 8x8 luma blocks coded in skip mode, counted in + ``num_inter_blocks`` too. + * - __u32 + - ``reserved1`` + - Applications and drivers must set this to zero. + +.. _stateless_encode_stats_flags: + +``Stateless Encode Statistics Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_STATELESS_ENCODE_STATS_FLAG_QP`` + - 0x00000001 + - ``qp_sum``, ``qp_count``, ``qp_min`` and ``qp_max`` are valid. + * - ``V4L2_STATELESS_ENCODE_STATS_FLAG_SSE_LUMA`` + - 0x00000002 + - ``sse_luma`` is valid. + * - ``V4L2_STATELESS_ENCODE_STATS_FLAG_BLOCKS`` + - 0x00000004 + - ``num_intra_blocks`` and ``num_inter_blocks`` are valid. + * - ``V4L2_STATELESS_ENCODE_STATS_FLAG_SKIP_BLOCKS`` + - 0x00000008 + - ``num_skip_blocks`` is valid. + .. _v4l2-codec-stateless-av1: ``V4L2_CID_STATELESS_AV1_SEQUENCE (struct)`` diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst index 235f955d3cd5..7483444ec823 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst @@ -221,6 +221,9 @@ Compressed Formats See the :ref:`associated Codec Control IDs `. Buffers associated with this pixel format must contain the appropriate number of macroblocks to decode a full corresponding frame. + Stateless video encoders use this pixel format on their CAPTURE queue: + each buffer then receives one complete access unit, as described in + :ref:`HEVC stateless encoding `. * .. _V4L2-PIX-FMT-FWHT: - ``V4L2_PIX_FMT_FWHT`` diff --git a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions index 6182b4e2d2ee..6c8ac563413f 100644 --- a/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions +++ b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions @@ -168,6 +168,8 @@ replace symbol V4L2_CTRL_TYPE_HEVC_PPS :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_ENCODE_PARAMS :c:type:`V4L.v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_HEVC_ENCODE_FEEDBACK :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AV1_SEQUENCE :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY :c:type:`V4L.v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_AV1_FRAME :c:type:`V4L.v4l2_ctrl_type` diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst index d78328152b75..0cc67e210359 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst @@ -286,6 +286,14 @@ still cause this situation. - ``p_hevc_decode_params`` - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_hevc_encode_params` * + - ``p_hevc_encode_params`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_encode_params`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_ENCODE_PARAMS``. + * - struct :c:type:`v4l2_ctrl_hevc_encode_feedback` * + - ``p_hevc_encode_feedback`` + - A pointer to a struct :c:type:`v4l2_ctrl_hevc_encode_feedback`. Valid if this + control is of type ``V4L2_CTRL_TYPE_HEVC_ENCODE_FEEDBACK``. * - struct :c:type:`v4l2_ctrl_av1_sequence` * - ``p_av1_sequence`` - A pointer to a struct :c:type:`v4l2_ctrl_av1_sequence`. Valid if this control is diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst index 82c8b52e771c..cd9ef6b559a4 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst @@ -543,6 +543,18 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_hevc_ext_sps_st_rps`, containing HEVC extended Short-Term RPS for stateless video decoders. + * - ``V4L2_CTRL_TYPE_HEVC_ENCODE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_encode_params`, containing HEVC + encoding parameters for stateless video encoders. + * - ``V4L2_CTRL_TYPE_HEVC_ENCODE_FEEDBACK`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_hevc_encode_feedback`, containing HEVC + encoding feedback from stateless video encoders. * - ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR`` - n/a - n/a -- 2.55.0