From eabe3bc2689ad0993c57469eb7efb1291443cc74 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 15 May 2019 03:50:41 -0400 Subject: media: cec-ioc-receive.rst: document CEC_MSG_FL_RAW Document this new cec_msg flag. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/cec/cec-ioc-receive.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index c3a685ff05cb..4137903d672e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -223,6 +223,18 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). result of the :ref:`ioctl CEC_TRANSMIT `, and once via :ref:`ioctl CEC_RECEIVE `. + * .. _`CEC-MSG-FL-RAW`: + + - ``CEC_MSG_FL_RAW`` + - 2 + - Normally CEC messages are validated before transmitting them. If this + flag is set when :ref:`ioctl CEC_TRANSMIT ` is called, + then no validation takes place and the message is transmitted as-is. + This is useful when debugging CEC issues. + This flag is only allowed if the process has the ``CAP_SYS_RAWIO`` + capability. If that is not set, then the ``EPERM`` error code is + returned. + .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| @@ -358,7 +370,8 @@ ENOTTY EPERM The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` - has never been called. + has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that + did not have the ``CAP_SYS_RAWIO`` capability. ENONET The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` -- cgit v1.2.3 From 428d3c867df6f2f87721fe7384ea09ad3130f839 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 22 May 2019 05:22:20 -0400 Subject: media: cec-ioc-g-mode.rst: be more specific when EPERM is returned Document which capability is required, rather than just saying that "root permissions" are required. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index c53bb5f73f0d..d0902f356d65 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -294,7 +294,8 @@ EINVAL The requested mode is invalid. EPERM - Monitor mode is requested without having root permissions + Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` + capability. EBUSY Someone else is already an exclusive follower or initiator. -- cgit v1.2.3 From a82c3149ad8b4a84f9737a633250815d5cf0cc5e Mon Sep 17 00:00:00 2001 From: Steve Longerbeam Date: Fri, 3 May 2019 19:45:07 -0400 Subject: media: docs-rst: Clarify older field vs. first transmitted field Add a paragraph to make it more clear that video equipment will transmit fields in the same order the fields were captured, and replace some of the "is transmitted first" language with "is the older field", since the latter is the important info for motion compensation applications. Signed-off-by: Steve Longerbeam Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/field-order.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index d640e922a974..c422bebe4314 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -51,6 +51,11 @@ determined by the video standard. Hence the distinction between temporal and spatial order of fields. The diagrams below should make this clearer. +In V4L it is assumed that all video cameras transmit fields on the media +bus in the same order they were captured, so if the top field was +captured first (is the older field), the top field is also transmitted +first on the bus. + All video capture and output devices must report the current field order. Some drivers may permit the selection of a different order, to this end applications initialize the ``field`` field of struct @@ -101,10 +106,10 @@ enum v4l2_field * - ``V4L2_FIELD_INTERLACED`` - 4 - Images contain both fields, interleaved line by line. The temporal - order of the fields (whether the top or bottom field is first - transmitted) depends on the current video standard. M/NTSC - transmits the bottom field first, all other standards the top - field first. + order of the fields (whether the top or bottom field is older) + depends on the current video standard. In M/NTSC the bottom + field is the older field. In all other standards the top field + is the older field. * - ``V4L2_FIELD_SEQ_TB`` - 5 - Images contain both fields, the top field lines are stored first @@ -135,11 +140,11 @@ enum v4l2_field * - ``V4L2_FIELD_INTERLACED_TB`` - 8 - Images contain both fields, interleaved line by line, top field - first. The top field is transmitted first. + first. The top field is the older field. * - ``V4L2_FIELD_INTERLACED_BT`` - 9 - Images contain both fields, interleaved line by line, top field - first. The bottom field is transmitted first. + first. The bottom field is the older field. -- cgit v1.2.3 From 5902bca94ae05316ec7feab9b84cb07ffa5c1175 Mon Sep 17 00:00:00 2001 From: Philipp Zabel Date: Wed, 24 Apr 2019 06:43:47 -0400 Subject: media: v4l2-ctrl: add MPEG-2 profile and level controls Add MPEG-2 CID definitions for profiles and levels defined in ITU-T Rec. H.262. Signed-off-by: Philipp Zabel Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/ext-ctrls-codec.rst | 56 ++++++++++++++++++++++++ 1 file changed, 56 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index 4a8446203085..843c93e8e7bc 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -759,6 +759,32 @@ enum v4l2_mpeg_video_h264_level - +.. _v4l2-mpeg-video-mpeg2-level: + +``V4L2_CID_MPEG_VIDEO_MPEG2_LEVEL`` + (enum) + +enum v4l2_mpeg_video_mpeg2_level - + The level information for the MPEG2 elementary stream. Applicable to + MPEG2 codecs. Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_LOW`` + - Low Level (LL) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_MAIN`` + - Main Level (ML) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_HIGH_1440`` + - High-1440 Level (H-14) + * - ``V4L2_MPEG_VIDEO_MPEG2_LEVEL_HIGH`` + - High Level (HL) + + + .. _v4l2-mpeg-video-mpeg4-level: ``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL`` @@ -845,6 +871,36 @@ enum v4l2_mpeg_video_h264_profile - +.. _v4l2-mpeg-video-mpeg2-profile: + +``V4L2_CID_MPEG_VIDEO_MPEG2_PROFILE`` + (enum) + +enum v4l2_mpeg_video_mpeg2_profile - + The profile information for MPEG2. Applicable to MPEG2 codecs. + Possible values are: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SIMPLE`` + - Simple profile (SP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_MAIN`` + - Main profile (MP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SNR_SCALABLE`` + - SNR Scalable profile (SNR) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_SPATIALLY_SCALABLE`` + - Spatially Scalable profile (Spt) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_HIGH`` + - High profile (HP) + * - ``V4L2_MPEG_VIDEO_MPEG2_PROFILE_MULTIVIEW`` + - Multi-view profile (MVP) + + + .. _v4l2-mpeg-video-mpeg4-profile: ``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE`` -- cgit v1.2.3 From 1f0545d3ed1df3a915546cee60b56f855962ed69 Mon Sep 17 00:00:00 2001 From: Pawel Osciak Date: Fri, 24 May 2019 05:20:28 -0400 Subject: media: uapi: Add H264 low-level decoder API compound controls. Stateless video codecs will require both the H264 metadata and slices in order to be able to decode frames. This introduces the definitions for the structures used to pass the metadata from the userspace to the kernel. [hverkuil-cisco@xs4all.nl: add space after . in ".For"] [hverkuil-cisco@xs4all.nl: sync v4l2_ctrl_h264_decode_params struct layout with header] Co-developed-by: Maxime Ripard Reviewed-by: Paul Kocialkowski Reviewed-by: Tomasz Figa Signed-off-by: Pawel Osciak Signed-off-by: Guenter Roeck Signed-off-by: Maxime Ripard 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 | 569 ++++++++++++++++++++++ Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 30 ++ Documentation/media/videodev2.h.rst.exceptions | 5 + 4 files changed, 613 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst index ec33768c055e..8f4eb8823d82 100644 --- a/Documentation/media/uapi/v4l/biblio.rst +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -122,6 +122,15 @@ ITU BT.1119 :author: International Telecommunication Union (http://www.itu.ch) +.. _h264: + +ITU-T Rec. H.264 Specification (04/2017 Edition) +================================================ + +:title: ITU-T Recommendation H.264 "Advanced Video Coding for Generic Audiovisual Services" + +:author: International Telecommunication Union (http://www.itu.ch) + .. _jfif: JFIF diff --git a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst index 843c93e8e7bc..d6ea2ffd65c5 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-codec.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-codec.rst @@ -1451,6 +1451,575 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - - Layer number +.. _v4l2-mpeg-h264: + +``V4L2_CID_MPEG_VIDEO_H264_SPS (struct)`` + Specifies the sequence parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_sps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_sps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``profile_idc`` + - + * - __u8 + - ``constraint_set_flags`` + - See :ref:`Sequence Parameter Set Constraints Set Flags ` + * - __u8 + - ``level_idc`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``chroma_format_idc`` + - + * - __u8 + - ``bit_depth_luma_minus8`` + - + * - __u8 + - ``bit_depth_chroma_minus8`` + - + * - __u8 + - ``log2_max_frame_num_minus4`` + - + * - __u8 + - ``pic_order_cnt_type`` + - + * - __u8 + - ``log2_max_pic_order_cnt_lsb_minus4`` + - + * - __u8 + - ``max_num_ref_frames`` + - + * - __u8 + - ``num_ref_frames_in_pic_order_cnt_cycle`` + - + * - __s32 + - ``offset_for_ref_frame[255]`` + - + * - __s32 + - ``offset_for_non_ref_pic`` + - + * - __s32 + - ``offset_for_top_to_bottom_field`` + - + * - __u16 + - ``pic_width_in_mbs_minus1`` + - + * - __u16 + - ``pic_height_in_map_units_minus1`` + - + * - __u32 + - ``flags`` + - See :ref:`Sequence Parameter Set Flags ` + +.. _h264_sps_constraints_set_flags: + +``Sequence Parameter Set Constraints Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG`` + - 0x00000020 + - + +.. _h264_sps_flags: + +``Sequence Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE`` + - 0x00000001 + - + * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS`` + - 0x00000002 + - + * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO`` + - 0x00000004 + - + * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED`` + - 0x00000008 + - + * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY`` + - 0x00000010 + - + * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD`` + - 0x00000020 + - + * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE`` + - 0x00000040 + - + +``V4L2_CID_MPEG_VIDEO_H264_PPS (struct)`` + Specifies the picture parameter set (as extracted from the + bitstream) for the associated H264 slice data. This includes the + necessary parameters for configuring a stateless hardware decoding + pipeline for H264. The bitstream parameters are defined according + to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP + Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_pps + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_pps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``seq_parameter_set_id`` + - + * - __u8 + - ``num_slice_groups_minus1`` + - + * - __u8 + - ``num_ref_idx_l0_default_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_default_active_minus1`` + - + * - __u8 + - ``weighted_bipred_idc`` + - + * - __s8 + - ``pic_init_qp_minus26`` + - + * - __s8 + - ``pic_init_qs_minus26`` + - + * - __s8 + - ``chroma_qp_index_offset`` + - + * - __s8 + - ``second_chroma_qp_index_offset`` + - + * - __u16 + - ``flags`` + - See :ref:`Picture Parameter Set Flags ` + +.. _h264_pps_flags: + +``Picture Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE`` + - 0x00000001 + - + * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT`` + - 0x00000002 + - + * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED`` + - 0x00000004 + - + * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT`` + - 0x00000008 + - + * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED`` + - 0x00000010 + - + * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT`` + - 0x00000020 + - + * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE`` + - 0x00000040 + - + * - ``V4L2_H264_PPS_FLAG_PIC_SCALING_MATRIX_PRESENT`` + - 0x00000080 + - + +``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX (struct)`` + Specifies the scaling matrix (as extracted from the bitstream) for + the associated H264 slice data. The bitstream parameters are + defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling + List Semantics". For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_scaling_matrix + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``scaling_list_4x4[6][16]`` + - + * - __u8 + - ``scaling_list_8x8[6][64]`` + - + +``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API + and it is expected to change. + + This structure is expected to be passed as an array, with one + entry for each slice included in the bitstream buffer. + +.. c:type:: v4l2_ctrl_h264_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``size`` + - + * - __u32 + - ``header_bit_size`` + - + * - __u16 + - ``first_mb_in_slice`` + - + * - __u8 + - ``slice_type`` + - + * - __u8 + - ``pic_parameter_set_id`` + - + * - __u8 + - ``colour_plane_id`` + - + * - __u8 + - ``redundant_pic_cnt`` + - + * - __u16 + - ``frame_num`` + - + * - __u16 + - ``idr_pic_id`` + - + * - __u16 + - ``pic_order_cnt_lsb`` + - + * - __s32 + - ``delta_pic_order_cnt_bottom`` + - + * - __s32 + - ``delta_pic_order_cnt0`` + - + * - __s32 + - ``delta_pic_order_cnt1`` + - + * - struct :c:type:`v4l2_h264_pred_weight_table` + - ``pred_weight_table`` + - + * - __u32 + - ``dec_ref_pic_marking_bit_size`` + - + * - __u32 + - ``pic_order_cnt_bit_size`` + - + * - __u8 + - ``cabac_init_idc`` + - + * - __s8 + - ``slice_qp_delta`` + - + * - __s8 + - ``slice_qs_delta`` + - + * - __u8 + - ``disable_deblocking_filter_idc`` + - + * - __s8 + - ``slice_alpha_c0_offset_div2`` + - + * - __s8 + - ``slice_beta_offset_div2`` + - + * - __u8 + - ``num_ref_idx_l0_active_minus1`` + - + * - __u8 + - ``num_ref_idx_l1_active_minus1`` + - + * - __u32 + - ``slice_group_change_cycle`` + - + * - __u8 + - ``ref_pic_list0[32]`` + - Reference picture list after applying the per-slice modifications + * - __u8 + - ``ref_pic_list1[32]`` + - Reference picture list after applying the per-slice modifications + * - __u32 + - ``flags`` + - See :ref:`Slice Parameter Flags ` + +.. _h264_slice_flags: + +``Slice Parameter Set Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_SLICE_FLAG_FIELD_PIC`` + - 0x00000001 + - + * - ``V4L2_H264_SLICE_FLAG_BOTTOM_FIELD`` + - 0x00000002 + - + * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED`` + - 0x00000004 + - + * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH`` + - 0x00000008 + - + +``Prediction Weight Table`` + + The bitstream parameters are defined according to :ref:`h264`, + section 7.4.3.2 "Prediction Weight Table Semantics". For further + documentation, refer to the above specification, unless there is + an explicit comment stating otherwise. + +.. c:type:: v4l2_h264_pred_weight_table + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_pred_weight_table + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``luma_log2_weight_denom`` + - + * - __u16 + - ``chroma_log2_weight_denom`` + - + * - struct :c:type:`v4l2_h264_weight_factors` + - ``weight_factors[2]`` + - The weight factors at index 0 are the weight factors for the reference + list 0, the one at index 1 for the reference list 1. + +.. c:type:: v4l2_h264_weight_factors + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_weight_factors + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __s16 + - ``luma_weight[32]`` + - + * - __s16 + - ``luma_offset[32]`` + - + * - __s16 + - ``chroma_weight[32][2]`` + - + * - __s16 + - ``chroma_offset[32][2]`` + - + +``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS (struct)`` + Specifies the decode parameters (as extracted from the bitstream) + for the associated H264 slice data. This includes the necessary + parameters for configuring a stateless hardware decoding pipeline + for H264. The bitstream parameters are defined according to + :ref:`h264`. For further documentation, refer to the above + specification, unless there is an explicit comment stating + otherwise. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_h264_decode_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_h264_decode_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`v4l2_h264_dpb_entry` + - ``dpb[16]`` + - + * - __u16 + - ``num_slices`` + - Number of slices needed to decode the current frame + * - __u16 + - ``nal_ref_idc`` + - NAL reference ID value coming from the NAL Unit header + * - __u8 + - ``ref_pic_list_p0[32]`` + - Backward reference list used by P-frames in the original bitstream order + * - __u8 + - ``ref_pic_list_b0[32]`` + - Backward reference list used by B-frames in the original bitstream order + * - __u8 + - ``ref_pic_list_b1[32]`` + - Forward reference list used by B-frames in the original bitstream order + * - __s32 + - ``top_field_order_cnt`` + - Picture Order Count for the coded top field + * - __s32 + - ``bottom_field_order_cnt`` + - Picture Order Count for the coded bottom field + * - __u32 + - ``flags`` + - See :ref:`Decode Parameters Flags ` + +.. _h264_decode_params_flags: + +``Decode Parameters Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC`` + - 0x00000001 + - That picture is an IDR picture + +.. c:type:: v4l2_h264_dpb_entry + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_h264_dpb_entry + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u64 + - ``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. + * - __u16 + - ``frame_num`` + - + * - __u16 + - ``pic_num`` + - + * - __s32 + - ``top_field_order_cnt`` + - + * - __s32 + - ``bottom_field_order_cnt`` + - + * - __u32 + - ``flags`` + - See :ref:`DPB Entry Flags ` + +.. _h264_dpb_flags: + +``DPB Entries Flags`` + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID`` + - 0x00000001 + - The DPB entry is valid and should be considered + * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE`` + - 0x00000002 + - The DPB entry is currently being used as a reference frame + * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM`` + - 0x00000004 + - The DPB entry is a long term reference frame .. _v4l2-mpeg-mpeg2: diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index f824162d0ea9..dc500632095d 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -443,6 +443,36 @@ See also the examples in :ref:`control`. - n/a - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 quantization matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_sps`, containing H264 + sequence parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_PPS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_pps`, containing H264 + picture parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_scaling_matrix`, containing H264 + scaling matrices for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_slice_params`, containing H264 + slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_h264_decode_params`, containing H264 + decode parameters for stateless video decoders. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index 64d348e67df9..55cbe324b9fc 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -136,6 +136,11 @@ 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` +replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_PPS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SCALING_MATRIX :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_SLICE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_H264_DECODE_PARAMS :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities -- cgit v1.2.3 From 67e84a98af6505d78be9e1a383fadd8de2f9fed0 Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Fri, 24 May 2019 05:20:30 -0400 Subject: media: pixfmt: Add H264_SLICE_RAW format documentation The H264_SLICE_RAW format introduced before is meant for stateless decoders that will need the H264 parsed slice data without the start code. Let's document it. Signed-off-by: Maxime Ripard Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/pixfmt-compressed.rst | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index 6c961cfb74da..4b701fc7653e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -52,6 +52,31 @@ Compressed Formats - ``V4L2_PIX_FMT_H264_MVC`` - 'M264' - H264 MVC video elementary stream. + * .. _V4L2-PIX-FMT-H264-SLICE-RAW: + + - ``V4L2_PIX_FMT_H264_SLICE_RAW`` + - 'S264' + - H264 parsed slice data, without the start code and as + extracted from the H264 bitstream. This format is adapted for + stateless video decoders that implement an H264 pipeline + (using the :ref:`mem2mem` and :ref:`media-request-api`). + Metadata associated with the frame to decode are required to + be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``, + ``V4L2_CID_MPEG_VIDEO_H264_PPS``, + ``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``, + ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and + ``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the + :ref:`associated Codec Control IDs `. 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. + + .. note:: + + This format is not yet part of the public kernel API and it + is expected to change. + * .. _V4L2-PIX-FMT-H263: - ``V4L2_PIX_FMT_H263`` -- cgit v1.2.3 From 3e6a515ff4d40b690511a250ceb11a6e1eba4081 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 27 May 2019 05:11:32 -0400 Subject: media: media-ioc-enum-links.rst: fix incorrect reserved field documentation The reserved field array for struct media_link_desc has length 2, not 4. And the reserved field array of struct media_links_enum was never documented at all. Signed-off-by: Hans Verkuil Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/mediactl/media-ioc-enum-links.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst index a982f16e55a4..b827ebc398f8 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -84,6 +84,11 @@ returned during the enumeration process. - Pointer to a links array allocated by the application. Ignored if NULL. + * - __u32 + - ``reserved[4]`` + - Reserved for future extensions. Drivers and applications must set + the array to zero. + .. c:type:: media_pad_desc @@ -135,7 +140,7 @@ returned during the enumeration process. - Link flags, see :ref:`media-link-flag` for more details. * - __u32 - - ``reserved[4]`` + - ``reserved[2]`` - Reserved for future extensions. Drivers and applications must set the array to zero. -- cgit v1.2.3 From e96a8819a6c4fc578809ba79d64abca57145acb7 Mon Sep 17 00:00:00 2001 From: Marc Gonzalez Date: Wed, 5 Jun 2019 07:59:10 -0400 Subject: media: docs: fix minor typos Fix minor typos in the DVB demux documentation. Signed-off-by: Marc Gonzalez Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/dtv-core.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index ac005b46f23e..82c5b85ed9b1 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -11,12 +11,12 @@ Digital TV devices are implemented by several different drivers: - Frontend drivers that are usually implemented as two separate drivers: - - A tuner driver that implements the logic with commands the part of the - hardware with is responsible to tune into a digital TV transponder or + - A tuner driver that implements the logic which commands the part of + the hardware responsible for tuning into a digital TV transponder or physical channel. The output of a tuner is usually a baseband or Intermediate Frequency (IF) signal; - - A demodulator driver (a.k.a "demod") that implements the logic with + - A demodulator driver (a.k.a "demod") that implements the logic which commands the digital TV decoding hardware. The output of a demod is a digital stream, with multiple audio, video and data channels typically multiplexed using MPEG Transport Stream [#f1]_. -- cgit v1.2.3 From 84060c65a8fa14ea9974a8f15b8280517b869cdd Mon Sep 17 00:00:00 2001 From: Stanimir Varbanov Date: Thu, 30 May 2019 05:33:12 -0400 Subject: media: media/doc: Allow sizeimage to be set by v4l clients This changes v4l2_pix_format and v4l2_plane_pix_format sizeimage field description to allow v4l clients to set bigger image size in case of variable length compressed data. Presently s5p-mfc and mtk-vcodec codec drivers use that. Lets make it obvious in the documentation. Signed-off-by: Stanimir Varbanov Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst | 15 ++++++++++++++- Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 13 ++++++++++++- 2 files changed, 26 insertions(+), 2 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index 5688c816e334..db43dda5aafb 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -31,7 +31,20 @@ describing all planes of that format. * - __u32 - ``sizeimage`` - - Maximum size in bytes required for image data in this plane. + - Maximum size in bytes required for image data in this plane, + set by the driver. When the image consists of variable length + compressed data this is the number of bytes required by the + codec to support the worst-case compression scenario. + + The driver will set the value for uncompressed images. + + Clients are allowed to set the sizeimage field for variable length + compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at + :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the + value itself, or it may modify the provided value based on + alignment requirements or minimum/maximum size requirements. + If the client wants to leave this to the driver, then it should + set sizeimage to 0. * - __u32 - ``bytesperline`` - Distance in bytes between the leftmost pixels in two adjacent diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst index 71eebfc6d853..da6da2ef139a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -89,7 +89,18 @@ Single-planar format structure - Size in bytes of the buffer to hold a complete image, set by the driver. Usually this is ``bytesperline`` times ``height``. When the image consists of variable length compressed data this is the - maximum number of bytes required to hold an image. + number of bytes required by the codec to support the worst-case + compression scenario. + + The driver will set the value for uncompressed images. + + Clients are allowed to set the sizeimage field for variable length + compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at + :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the + value itself, or it may modify the provided value based on + alignment requirements or minimum/maximum size requirements. + If the client wants to leave this to the driver, then it should + set sizeimage to 0. * - __u32 - ``colorspace`` - Image colorspace, from enum :c:type:`v4l2_colorspace`. -- cgit v1.2.3 From 6aace2f89f785482efecbec3d61dfa41e0a64f9c Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 5 Jun 2019 10:31:06 -0400 Subject: media: Documentation: update email address Use hverkuil-cisco@xs4all.nl instead of hans.verkuil@cisco.com. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/cec/cec-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst index b614bf81aa20..0780ba07995a 100644 --- a/Documentation/media/uapi/cec/cec-api.rst +++ b/Documentation/media/uapi/cec/cec-api.rst @@ -39,7 +39,7 @@ Revision and Copyright ********************** Authors: -- Verkuil, Hans +- Verkuil, Hans - Initial version. -- cgit v1.2.3 From 13d93380fca826e49c42e8d83fc8a077cabbe6b8 Mon Sep 17 00:00:00 2001 From: Tomasz Figa Date: Wed, 12 Jun 2019 05:36:48 -0400 Subject: media: Clarify the meaning of file descriptors in VIDIOC_DQBUF When the application calls VIDIOC_DQBUF with the DMABUF memory type, the v4l2_buffer structure (or v4l2_plane structures) are filled with DMA-buf file descriptors. However, the current documentation does not explain whether those are new file descriptors referring to the same DMA-bufs or just the same integers as passed to VIDIOC_QBUF back in time. Clarify the documentation that it's the latter. Signed-off-by: Tomasz Figa Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/vidioc-qbuf.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index dbf7b445a27b..407302d80684 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -139,6 +139,14 @@ may continue as normal, but should be aware that data in the dequeued buffer might be corrupted. When using the multi-planar API, the planes array must be passed in as well. +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to +dequeue a :ref:`DMABUF ` buffer, the driver fills the ``m.fd`` field +with a file descriptor numerically the same as the one given to ``VIDIOC_QBUF`` +when the buffer was enqueued. No new file descriptor is created at dequeue time +and the value is only for the application convenience. When the multi-planar +API is used the ``m.fd`` fields of the passed array of struct +:c:type:`v4l2_plane` are filled instead. + By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the :ref:`open() ` function, ``VIDIOC_DQBUF`` returns -- cgit v1.2.3 From 7239682847b5a7d2633f39ddea1c0c11a69d5fd3 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:19 -0400 Subject: media: docs: v4l2-controls: remove repeated ioctl names Mentioning :ref:`VIDIOC_QUERYCTRL` renders all the three related ioctls. Explicitly adding VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU will make them render twice, so remove them Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/extended-controls.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 24274b398e63..1323afcf2b7d 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -96,9 +96,7 @@ if this control consists of more than one element. #. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use - the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL - `) and :ref:`VIDIOC_QUERYMENU ` - ioctls to check this. + :ref:`VIDIOC_QUERYCTRL` to check this. #. It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` -- cgit v1.2.3 From e050f55207c547f78cd65758f148dd1b4404f133 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:20 -0400 Subject: media: docs: v4l2-controls: fix indentation Fix indentation in example C code. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/extended-controls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 1323afcf2b7d..0e9787072a41 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -142,7 +142,7 @@ control class is found: while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; - /* ... */ + /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; } -- cgit v1.2.3 From 9e75efb0f2c56c7285f28bba877da14f428a730c Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:21 -0400 Subject: media: docs: v4l2-controls: add links to structs This section lacks links to struct definitions. Add one where each struct is introduced. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 64ab99abf0b6..0c3f486727ed 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -26,8 +26,9 @@ The control framework was created in order to implement all the rules of the V4L2 specification with respect to controls in a central place. And to make life as easy as possible for the driver developer. -Note that the control framework relies on the presence of a struct v4l2_device -for V4L2 drivers and struct v4l2_subdev for sub-device drivers. +Note that the control framework relies on the presence of a struct +:c:type:`v4l2_device` for V4L2 drivers and struct :c:type:`v4l2_subdev` for +sub-device drivers. Objects in the framework @@ -35,12 +36,13 @@ Objects in the framework There are two main objects: -The v4l2_ctrl object describes the control properties and keeps track of the -control's value (both the current value and the proposed new value). +The :c:type:`v4l2_ctrl` object describes the control properties and keeps +track of the control's value (both the current value and the proposed new +value). -v4l2_ctrl_handler is the object that keeps track of controls. It maintains a -list of v4l2_ctrl objects that it owns and another list of references to -controls, possibly to controls owned by other handlers. +:c:type:`v4l2_ctrl_handler` is the object that keeps track of controls. It +maintains a list of v4l2_ctrl objects that it owns and another list of +references to controls, possibly to controls owned by other handlers. Basic usage for V4L2 and sub-device drivers @@ -242,7 +244,7 @@ initializes the hardware to the default control values. It is recommended that you do this as this ensures that both the internal data structures and the hardware are in sync. -4) Finally: implement the v4l2_ctrl_ops +4) Finally: implement the :c:type:`v4l2_ctrl_ops` .. code-block:: none -- cgit v1.2.3 From e36160b84253d7125d0fa4109a3d69f0c55fc5d0 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:22 -0400 Subject: media: docs: v4l2-controls: rearrange control initialization sequence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The code snippet showing how to add controls to the driver’s top-level struct is present twice, but only the second time it is split in the V4L2 and subdev cases. Consolidate everything at the beginning. Also remove the "Where foo->bar is of type struct baz" sentences, this obvious from the code. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 40 +++++++++++++----------------- 1 file changed, 17 insertions(+), 23 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 0c3f486727ed..5281c9b1fd66 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -52,15 +52,29 @@ Basic usage for V4L2 and sub-device drivers 1.1) Add the handler to your driver's top-level struct: +For V4L2 drivers: + .. code-block:: none struct foo_dev { + ... + struct v4l2_device v4l2_dev; ... struct v4l2_ctrl_handler ctrl_handler; ... }; - struct foo_dev *foo; +For sub-device drivers: + +.. code-block:: none + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; 1.2) Initialize the handler: @@ -74,43 +88,23 @@ information. It is a hint only. 1.3) Hook the control handler into the driver: -1.3.1) For V4L2 drivers do this: +For V4L2 drivers: .. code-block:: none - struct foo_dev { - ... - struct v4l2_device v4l2_dev; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; - foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; -Where foo->v4l2_dev is of type struct v4l2_device. - Finally, remove all control functions from your v4l2_ioctl_ops (if any): vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. Those are now no longer needed. -1.3.2) For sub-device drivers do this: +For sub-device drivers: .. code-block:: none - struct foo_dev { - ... - struct v4l2_subdev sd; - ... - struct v4l2_ctrl_handler ctrl_handler; - ... - }; - foo->sd.ctrl_handler = &foo->ctrl_handler; -Where foo->sd is of type struct v4l2_subdev. - 1.4) Clean up the handler at the end: .. code-block:: none -- cgit v1.2.3 From 6b623dbfbd4f940de45b66ec07582aed0462f6da Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:23 -0400 Subject: media: docs: v4l2-controls: add links to functions This section lacks links to functions. Add one to simplify reading. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 67 ++++++++++++++++-------------- 1 file changed, 35 insertions(+), 32 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 5281c9b1fd66..41c0fd4009e9 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -114,7 +114,7 @@ For sub-device drivers: 2) Add controls: -You add non-menu controls by calling v4l2_ctrl_new_std: +You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: .. code-block:: none @@ -122,7 +122,8 @@ You add non-menu controls by calling v4l2_ctrl_new_std: const struct v4l2_ctrl_ops *ops, u32 id, s32 min, s32 max, u32 step, s32 def); -Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: +Menu and integer menu controls are added by calling +:c:func:`v4l2_ctrl_new_std_menu`: .. code-block:: none @@ -131,7 +132,7 @@ Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu: u32 id, s32 max, s32 skip_mask, s32 def); Menu controls with a driver specific menu are added by calling -v4l2_ctrl_new_std_menu_items: +:c:func:`v4l2_ctrl_new_std_menu_items`: .. code-block:: none @@ -141,7 +142,7 @@ v4l2_ctrl_new_std_menu_items: s32 skip_mask, s32 def, const char * const *qmenu); Integer menu controls with a driver specific menu can be added by calling -v4l2_ctrl_new_int_menu: +:c:func:`v4l2_ctrl_new_int_menu`: .. code-block:: none @@ -149,7 +150,8 @@ v4l2_ctrl_new_int_menu: const struct v4l2_ctrl_ops *ops, u32 id, s32 max, s32 def, const s64 *qmenu_int); -These functions are typically called right after the v4l2_ctrl_handler_init: +These functions are typically called right after the +:c:func:`v4l2_ctrl_handler_init`: .. code-block:: none @@ -188,33 +190,34 @@ These functions are typically called right after the v4l2_ctrl_handler_init: return err; } -The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new -control, but if you do not need to access the pointer outside the control ops, -then there is no need to store it. - -The v4l2_ctrl_new_std function will fill in most fields based on the control -ID except for the min, max, step and default values. These are passed in the -last four arguments. These values are driver specific while control attributes -like type, name, flags are all global. The control's current value will be set -to the default value. - -The v4l2_ctrl_new_std_menu function is very similar but it is used for menu -controls. There is no min argument since that is always 0 for menu controls, -and instead of a step there is a skip_mask argument: if bit X is 1, then menu -item X is skipped. - -The v4l2_ctrl_new_int_menu function creates a new standard integer menu -control with driver-specific items in the menu. It differs from -v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and takes -as the last argument an array of signed 64-bit integers that form an exact -menu item list. - -The v4l2_ctrl_new_std_menu_items function is very similar to -v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the driver -specific menu for an otherwise standard menu control. A good example for this -control is the test pattern control for capture/display/sensors devices that -have the capability to generate test patterns. These test patterns are hardware -specific, so the contents of the menu will vary from device to device. +The :c:func:`v4l2_ctrl_new_std` function returns the v4l2_ctrl pointer to +the new control, but if you do not need to access the pointer outside the +control ops, then there is no need to store it. + +The :c:func:`v4l2_ctrl_new_std` function will fill in most fields based on +the control ID except for the min, max, step and default values. These are +passed in the last four arguments. These values are driver specific while +control attributes like type, name, flags are all global. The control's +current value will be set to the default value. + +The :c:func:`v4l2_ctrl_new_std_menu` function is very similar but it is +used for menu controls. There is no min argument since that is always 0 for +menu controls, and instead of a step there is a skip_mask argument: if bit +X is 1, then menu item X is skipped. + +The :c:func:`v4l2_ctrl_new_int_menu` function creates a new standard +integer menu control with driver-specific items in the menu. It differs +from v4l2_ctrl_new_std_menu in that it doesn't have the mask argument and +takes as the last argument an array of signed 64-bit integers that form an +exact menu item list. + +The :c:func:`v4l2_ctrl_new_std_menu_items` function is very similar to +v4l2_ctrl_new_std_menu but takes an extra parameter qmenu, which is the +driver specific menu for an otherwise standard menu control. A good example +for this control is the test pattern control for capture/display/sensors +devices that have the capability to generate test patterns. These test +patterns are hardware specific, so the contents of the menu will vary from +device to device. Note that if something fails, the function will return NULL or an error and set ctrl_handler->error to the error code. If ctrl_handler->error was already -- cgit v1.2.3 From 270c0024a368806a84a7e15d6024cbd232752c04 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:24 -0400 Subject: media: docs: v4l2-controls: convert code blocks to C All these code blocks contain C code, enable C formatting for a nicer reading. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 74 +++++++++++++++--------------- 1 file changed, 37 insertions(+), 37 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 41c0fd4009e9..45541e05a0e7 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -54,7 +54,7 @@ Basic usage for V4L2 and sub-device drivers For V4L2 drivers: -.. code-block:: none +.. code-block:: c struct foo_dev { ... @@ -66,7 +66,7 @@ For V4L2 drivers: For sub-device drivers: -.. code-block:: none +.. code-block:: c struct foo_dev { ... @@ -78,7 +78,7 @@ For sub-device drivers: 1.2) Initialize the handler: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); @@ -90,7 +90,7 @@ information. It is a hint only. For V4L2 drivers: -.. code-block:: none +.. code-block:: c foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; @@ -101,13 +101,13 @@ Those are now no longer needed. For sub-device drivers: -.. code-block:: none +.. code-block:: c foo->sd.ctrl_handler = &foo->ctrl_handler; 1.4) Clean up the handler at the end: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_free(&foo->ctrl_handler); @@ -116,7 +116,7 @@ For sub-device drivers: You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -125,7 +125,7 @@ You add non-menu controls by calling :c:func:`v4l2_ctrl_new_std`: Menu and integer menu controls are added by calling :c:func:`v4l2_ctrl_new_std_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -134,7 +134,7 @@ Menu and integer menu controls are added by calling Menu controls with a driver specific menu are added by calling :c:func:`v4l2_ctrl_new_std_menu_items`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items( struct v4l2_ctrl_handler *hdl, @@ -144,7 +144,7 @@ Menu controls with a driver specific menu are added by calling Integer menu controls with a driver specific menu can be added by calling :c:func:`v4l2_ctrl_new_int_menu`: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl, const struct v4l2_ctrl_ops *ops, @@ -153,7 +153,7 @@ Integer menu controls with a driver specific menu can be added by calling These functions are typically called right after the :c:func:`v4l2_ctrl_handler_init`: -.. code-block:: none +.. code-block:: c static const s64 exp_bias_qmenu[] = { -2, -1, 0, 1, 2 @@ -232,7 +232,7 @@ a bit faster that way. 3) Optionally force initial control setup: -.. code-block:: none +.. code-block:: c v4l2_ctrl_handler_setup(&foo->ctrl_handler); @@ -243,7 +243,7 @@ the hardware are in sync. 4) Finally: implement the :c:type:`v4l2_ctrl_ops` -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_ops foo_ctrl_ops = { .s_ctrl = foo_s_ctrl, @@ -251,7 +251,7 @@ the hardware are in sync. Usually all you need is s_ctrl: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -304,7 +304,7 @@ Accessing Control Values The following union is used inside the control framework to access control values: -.. code-block:: none +.. code-block:: c union v4l2_ctrl_ptr { s32 *p_s32; @@ -316,7 +316,7 @@ values: The v4l2_ctrl struct contains these fields that can be used to access both current and new values: -.. code-block:: none +.. code-block:: c s32 val; struct { @@ -329,7 +329,7 @@ current and new values: If the control has a simple s32 type type, then: -.. code-block:: none +.. code-block:: c &ctrl->val == ctrl->p_new.p_s32 &ctrl->cur.val == ctrl->p_cur.p_s32 @@ -353,7 +353,7 @@ exception is for controls that return a volatile register such as a signal strength read-out that changes continuously. In that case you will need to implement g_volatile_ctrl like this: -.. code-block:: none +.. code-block:: c static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) { @@ -371,7 +371,7 @@ changes. To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: -.. code-block:: none +.. code-block:: c ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); if (ctrl) @@ -392,7 +392,7 @@ not to introduce deadlocks. Outside of the control ops you have to go through to helper functions to get or set a single control value safely in your driver: -.. code-block:: none +.. code-block:: c s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); @@ -403,7 +403,7 @@ will result in a deadlock since these helpers lock the handler as well. You can also take the handler lock yourself: -.. code-block:: none +.. code-block:: c mutex_lock(&state->ctrl_handler.lock); pr_info("String value is '%s'\n", ctrl1->p_cur.p_char); @@ -416,7 +416,7 @@ Menu Controls The v4l2_ctrl struct contains this union: -.. code-block:: none +.. code-block:: c union { u32 step; @@ -444,7 +444,7 @@ Custom Controls Driver specific controls can be created using v4l2_ctrl_new_custom(): -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_filter = { .ops = &ctrl_custom_ops, @@ -498,7 +498,7 @@ By default all controls are independent from the others. But in more complex scenarios you can get dependencies from one control to another. In that case you need to 'cluster' them: -.. code-block:: none +.. code-block:: c struct foo { struct v4l2_ctrl_handler ctrl_handler; @@ -522,7 +522,7 @@ composite control. Similar to how a 'struct' works in C. So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set all two controls belonging to the audio_cluster: -.. code-block:: none +.. code-block:: c static int foo_s_ctrl(struct v4l2_ctrl *ctrl) { @@ -544,7 +544,7 @@ all two controls belonging to the audio_cluster: In the example above the following are equivalent for the VOLUME case: -.. code-block:: none +.. code-block:: c ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] @@ -552,7 +552,7 @@ In the example above the following are equivalent for the VOLUME case: In practice using cluster arrays like this becomes very tiresome. So instead the following equivalent method is used: -.. code-block:: none +.. code-block:: c struct { /* audio cluster */ @@ -564,7 +564,7 @@ The anonymous struct is used to clearly 'cluster' these two control pointers, but it serves no other purpose. The effect is the same as creating an array with two control pointers. So you can just do: -.. code-block:: none +.. code-block:: c state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...); state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...); @@ -620,7 +620,7 @@ changing that control affects the control flags of the manual controls. In order to simplify this a special variation of v4l2_ctrl_cluster was introduced: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls, u8 manual_val, bool set_volatile); @@ -675,7 +675,7 @@ of another handler (e.g. for a video device node), then you should first add the controls to the first handler, add the other controls to the second handler and finally add the first handler to the second. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -689,7 +689,7 @@ all controls. Or you can add specific controls to a handler: -.. code-block:: none +.. code-block:: c volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); @@ -698,7 +698,7 @@ Or you can add specific controls to a handler: What you should not do is make two identical controls for two handlers. For example: -.. code-block:: none +.. code-block:: c v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...); @@ -719,7 +719,7 @@ not own. For example, if you have to find a volume control from a subdev. You can do that by calling v4l2_ctrl_find: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl *volume; @@ -728,7 +728,7 @@ You can do that by calling v4l2_ctrl_find: Since v4l2_ctrl_find will lock the handler you have to be careful where you use it. For example, this is not a good idea: -.. code-block:: none +.. code-block:: c struct v4l2_ctrl_handler ctrl_handler; @@ -737,7 +737,7 @@ use it. For example, this is not a good idea: ...and in video_ops.s_ctrl: -.. code-block:: none +.. code-block:: c case V4L2_CID_BRIGHTNESS: contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); @@ -759,7 +759,7 @@ not when it is used in consumer-level hardware. In that case you want to keep those low-level controls local to the subdev. You can do this by simply setting the 'is_private' flag of the control to 1: -.. code-block:: none +.. code-block:: c static const struct v4l2_ctrl_config ctrl_private = { .ops = &ctrl_custom_ops, @@ -796,7 +796,7 @@ Sometimes the platform or bridge driver needs to be notified when a control from a sub-device driver changes. You can set a notify callback by calling this function: -.. code-block:: none +.. code-block:: c void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv); -- cgit v1.2.3 From 025b941132352c6093cbb3a1f6760426e739dc79 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:25 -0400 Subject: media: docs: v4l2-controls: document file to include The tutorial in this section is almost complete, add the one missing bit. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 45541e05a0e7..407617b1d0ce 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -50,6 +50,10 @@ Basic usage for V4L2 and sub-device drivers 1) Prepare the driver: +.. code-block:: c + + #include + 1.1) Add the handler to your driver's top-level struct: For V4L2 drivers: -- cgit v1.2.3 From 40208924b988888f786850fae42fb5ca880fab80 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Thu, 13 Jun 2019 10:18:26 -0400 Subject: media: docs: v4l2-controls: remove outdated paragraph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This paragraph was added by commit a42b57f5aacf ("V4L/DVB: Documentation: add v4l2-controls.txt documenting the new controls API") back in 2010, when the controls API has been improved. Nowadays it is a bit anachronistic, so remove it. The same information is stated in up-to-date wording a few paragraphs later > You’re done! And this is sufficient for most of the drivers we have. No > need to do any validation of control values, or implement QUERYCTRL, > QUERY_EXT_CTRL and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS > are automatically supported. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-controls.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 407617b1d0ce..ebe2a55908be 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -98,11 +98,6 @@ For V4L2 drivers: foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; -Finally, remove all control functions from your v4l2_ioctl_ops (if any): -vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, -vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. -Those are now no longer needed. - For sub-device drivers: .. code-block:: c -- cgit v1.2.3 From 8c937ab966fdf639e517594b48f06b1f07309072 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Fri, 14 Jun 2019 11:14:29 -0400 Subject: media: docs: v4l2-controls: fix sentence rendered in a nonsense way This sentence renders as: > Since such compound controls need to expose more information about > themselves than is possible with ioctls VIDIOC_QUERYCTRL, > VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU the VIDIOC_QUERY_EXT_CTRL ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^ > ioctl was added. This does not make sense. Fix by providing an explicit link text. This results in: > Since such compound controls need to expose more information about > themselves than is possible with VIDIOC_QUERYCTRL the > VIDIOC_QUERY_EXT_CTRL ioctl was added. Signed-off-by: Luca Ceresoli Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/extended-controls.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 0e9787072a41..655362483730 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -85,11 +85,10 @@ be able to see such compound controls. In other words, these controls with compound types should only be used programmatically. Since such compound controls need to expose more information about -themselves than is possible with -:ref:`VIDIOC_QUERYCTRL` the -:ref:`VIDIOC_QUERY_EXT_CTRL ` ioctl was added. In -particular, this ioctl gives the dimensions of the N-dimensional array -if this control consists of more than one element. +themselves than is possible with :ref:`VIDIOC_QUERYCTRL ` +the :ref:`VIDIOC_QUERY_EXT_CTRL ` ioctl was added. In +particular, this ioctl gives the dimensions of the N-dimensional array if +this control consists of more than one element. .. note:: -- cgit v1.2.3 From 03f4175bd01f94b99688b087c82706a11efbde5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Almeida?= Date: Sat, 15 Jun 2019 22:09:59 -0400 Subject: media: docs: create vimc documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create vimc documentation file to explain its basic features, its topology, how to configure it and to document vimc's subdevices. Signed-off-by: André Almeida Suggested-by: Helen Koike [hverkuil-cisco@xs4all.nl: Fix typo: The ``v4l2-utils`` -> The ``v4l-utils`` package] Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/index.rst | 1 + Documentation/media/v4l-drivers/vimc.dot | 22 +++++++ Documentation/media/v4l-drivers/vimc.rst | 98 +++++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 Documentation/media/v4l-drivers/vimc.dot create mode 100644 Documentation/media/v4l-drivers/vimc.rst (limited to 'Documentation/media') diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 33a055907258..c4c78a28654c 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -64,5 +64,6 @@ For more details see the file COPYING in the source distribution of Linux. si476x soc-camera uvcvideo + vimc vivid zr364xx diff --git a/Documentation/media/v4l-drivers/vimc.dot b/Documentation/media/v4l-drivers/vimc.dot new file mode 100644 index 000000000000..57863a13fa39 --- /dev/null +++ b/Documentation/media/v4l-drivers/vimc.dot @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: GPL-2.0 + +digraph board { + rankdir=TB + n00000001 [label="{{} | Sensor A\n/dev/v4l-subdev0 | { 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000001:port0 -> n00000005:port0 [style=bold] + n00000001:port0 -> n0000000b [style=bold] + n00000003 [label="{{} | Sensor B\n/dev/v4l-subdev1 | { 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000003:port0 -> n00000008:port0 [style=bold] + n00000003:port0 -> n0000000f [style=bold] + n00000005 [label="{{ 0} | Debayer A\n/dev/v4l-subdev2 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000005:port1 -> n00000017:port0 + n00000008 [label="{{ 0} | Debayer B\n/dev/v4l-subdev3 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000008:port1 -> n00000017:port0 [style=dashed] + n0000000b [label="Raw Capture 0\n/dev/video0", shape=box, style=filled, fillcolor=yellow] + n0000000f [label="Raw Capture 1\n/dev/video1", shape=box, style=filled, fillcolor=yellow] + n00000013 [label="RGB/YUV Input\n/dev/video2", shape=box, style=filled, fillcolor=yellow] + n00000013 -> n00000017:port0 [style=dashed] + n00000017 [label="{{ 0} | Scaler\n/dev/v4l-subdev4 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000017:port1 -> n0000001a [style=bold] + n0000001a [label="RGB/YUV Capture\n/dev/video3", shape=box, style=filled, fillcolor=yellow] +} diff --git a/Documentation/media/v4l-drivers/vimc.rst b/Documentation/media/v4l-drivers/vimc.rst new file mode 100644 index 000000000000..4628b12d417f --- /dev/null +++ b/Documentation/media/v4l-drivers/vimc.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual Media Controller Driver (vimc) +========================================== + +The vimc driver emulates complex video hardware using the V4L2 API and the Media +API. It has a capture device and three subdevices: sensor, debayer and scaler. + +Topology +-------- + +The topology is hardcoded, although you could modify it in vimc-core and +recompile the driver to achieve your own topology. This is the default topology: + +.. _vimc_topology_graph: + +.. kernel-figure:: vimc.dot + :alt: vimc.dot + :align: center + + Media pipeline graph on vimc + +Configuring the topology +~~~~~~~~~~~~~~~~~~~~~~~~ + +Each subdevice will come with its default configuration (pixelformat, height, +width, ...). One needs to configure the topology in order to match the +configuration on each linked subdevice to stream frames through the pipeline. +If the configuration doesn't match, the stream will fail. The ``v4l-utils`` +package is a bundle of user-space applications, that comes with ``media-ctl`` and +``v4l2-ctl`` that can be used to configure the vimc configuration. This sequence +of commands fits for the default topology: + +.. code-block:: bash + + media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Sensor B":0[fmt:SBGGR8_1X8/640x480]' + media-ctl -d platform:vimc -V '"Debayer B":0[fmt:SBGGR8_1X8/640x480]' + v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=1920,height=1440 + v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81 + v4l2-ctl -z platform:vimc -d "Raw Capture 1" -v pixelformat=BA81 + +Subdevices +---------- + +Subdevices define the behavior of an entity in the topology. Depending on the +subdevice, the entity can have multiple pads of type source or sink. + +vimc-sensor: + Generates images in several formats using video test pattern generator. + Exposes: + + * 1 Pad source + +vimc-debayer: + Transforms images in bayer format into a non-bayer format. + Exposes: + + * 1 Pad sink + * 1 Pad source + +vimc-scaler: + Scale up the image by a factor of 3. E.g.: a 640x480 image becomes a + 1920x1440 image. (this value can be configured, see at + `Module options`_). + Exposes: + + * 1 Pad sink + * 1 Pad source + +vimc-capture: + Exposes node /dev/videoX to allow userspace to capture the stream. + Exposes: + + * 1 Pad sink + * 1 Pad source + +Module options +--------------- + +Vimc has a few module parameters to configure the driver. You should pass +those arguments to each subdevice, not to the vimc module. For example:: + + vimc_subdevice.param=value + +* ``vimc_scaler.sca_mult=`` + + Image size multiplier factor to be used to multiply both width and + height, so the image size will be ``sca_mult^2`` bigger than the + original one. Currently, only supports scaling up (the default value + is 3). + +* ``vimc_debayer.deb_mean_win_size=`` + + Window size to calculate the mean. Note: the window size needs to be an + odd number, as the main pixel stays in the center of the window, + otherwise the next odd number is considered (the default value is 3). -- cgit v1.2.3 From 4196ad7cc99fce466b50be5df94ca8a2f0d1cf42 Mon Sep 17 00:00:00 2001 From: Johan Korsnes Date: Tue, 18 Jun 2019 03:37:26 -0400 Subject: media: vivid.rst: describe display present control Signed-off-by: Johan Korsnes Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/v4l-drivers/vivid.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/media') diff --git a/Documentation/media/v4l-drivers/vivid.rst b/Documentation/media/v4l-drivers/vivid.rst index edb6f33e029c..7082fec4075d 100644 --- a/Documentation/media/v4l-drivers/vivid.rst +++ b/Documentation/media/v4l-drivers/vivid.rst @@ -941,6 +941,11 @@ Digital Video Controls affects the reported colorspace since DVI_D outputs will always use sRGB. +- Display Present: + + sets the presence of a "display" on the HDMI output. This affects + the tx_edid_present, tx_hotplug and tx_rxsense controls. + FM Radio Receiver Controls ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 1910ea428f28e5731a2cea32b86e71953829f15d Mon Sep 17 00:00:00 2001 From: Bastien Nocera Date: Mon, 24 Jun 2019 11:42:14 -0400 Subject: media: rc: Prefer KEY_NUMERIC_* for number buttons on remotes Prefer KEY_NUMERIC_* for number buttons on remotes. Now all the remotes use KEY_NUMERIC_[0-9] for the number buttons rather than keys that could be affected by modifiers (Caps-Lock, or Num-Lock) or regional keymaps. Created using: sed -i 's/KEY_\([0-9]\) /KEY_NUMERIC_\1 /' *.c sed -i 's/KEY_\([0-9]\)}/KEY_NUMERIC_\1}/' *.c sed -i 's/``KEY_\([0-9]\)/``KEY_NUMERIC_\1/' Documentation/media/uapi/rc/rc-tables.rst Signed-off-by: Bastien Nocera Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/rc-tables.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst index 177ac44fa0fa..468d8aa3849b 100644 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ b/Documentation/media/uapi/rc/rc-tables.rst @@ -54,7 +54,7 @@ the remote via /dev/input/event devices. - .. row 3 - - ``KEY_0`` + - ``KEY_NUMERIC_0`` - Keyboard digit 0 @@ -62,7 +62,7 @@ the remote via /dev/input/event devices. - .. row 4 - - ``KEY_1`` + - ``KEY_NUMERIC_1`` - Keyboard digit 1 @@ -70,7 +70,7 @@ the remote via /dev/input/event devices. - .. row 5 - - ``KEY_2`` + - ``KEY_NUMERIC_2`` - Keyboard digit 2 @@ -78,7 +78,7 @@ the remote via /dev/input/event devices. - .. row 6 - - ``KEY_3`` + - ``KEY_NUMERIC_3`` - Keyboard digit 3 @@ -86,7 +86,7 @@ the remote via /dev/input/event devices. - .. row 7 - - ``KEY_4`` + - ``KEY_NUMERIC_4`` - Keyboard digit 4 @@ -94,7 +94,7 @@ the remote via /dev/input/event devices. - .. row 8 - - ``KEY_5`` + - ``KEY_NUMERIC_5`` - Keyboard digit 5 @@ -102,7 +102,7 @@ the remote via /dev/input/event devices. - .. row 9 - - ``KEY_6`` + - ``KEY_NUMERIC_6`` - Keyboard digit 6 @@ -110,7 +110,7 @@ the remote via /dev/input/event devices. - .. row 10 - - ``KEY_7`` + - ``KEY_NUMERIC_7`` - Keyboard digit 7 @@ -118,7 +118,7 @@ the remote via /dev/input/event devices. - .. row 11 - - ``KEY_8`` + - ``KEY_NUMERIC_8`` - Keyboard digit 8 @@ -126,7 +126,7 @@ the remote via /dev/input/event devices. - .. row 12 - - ``KEY_9`` + - ``KEY_NUMERIC_9`` - Keyboard digit 9 -- cgit v1.2.3 From 46fb4749788159412622c5bb9d087a217cc00152 Mon Sep 17 00:00:00 2001 From: Bastien Nocera Date: Tue, 25 Jun 2019 08:03:48 -0400 Subject: media: doc-rst: Fix typos Not sure how codespell thinks "sroweam" is a real word. Signed-off-by: Bastien Nocera Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/rc-tables.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst index 468d8aa3849b..20d7c686922b 100644 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ b/Documentation/media/uapi/rc/rc-tables.rst @@ -196,7 +196,7 @@ the remote via /dev/input/event devices. - ``KEY_PAUSE`` - - Pause sroweam + - Pause stream - PAUSE / FREEZE @@ -220,7 +220,7 @@ the remote via /dev/input/event devices. - ``KEY_STOP`` - - Stop sroweam + - Stop stream - STOP @@ -228,7 +228,7 @@ the remote via /dev/input/event devices. - ``KEY_RECORD`` - - Start/stop recording sroweam + - Start/stop recording stream - CAPTURE / REC / RECORD/PAUSE @@ -577,7 +577,7 @@ the remote via /dev/input/event devices. - ``KEY_CLEAR`` - - Stop sroweam and return to default input video/audio + - Stop stream and return to default input video/audio - CLEAR / RESET / BOSS KEY @@ -593,7 +593,7 @@ the remote via /dev/input/event devices. - ``KEY_FAVORITES`` - - Open the favorites sroweam window + - Open the favorites stream window - TV WALL / Favorites -- cgit v1.2.3