diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l')
5 files changed, 572 insertions, 3 deletions
diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index d9868ee88a07..3e0cab153f0a 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -13,6 +13,7 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 + metafmt-arm-mali-c55 metafmt-c3-isp metafmt-d4xx metafmt-generic @@ -25,3 +26,4 @@ These formats are used for the :ref:`metadata` interface only. metafmt-vivid metafmt-vsp1-hgo metafmt-vsp1-hgt + v4l2-isp diff --git a/Documentation/userspace-api/media/v4l/metafmt-arm-mali-c55.rst b/Documentation/userspace-api/media/v4l/metafmt-arm-mali-c55.rst new file mode 100644 index 000000000000..696e0a645a7e --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-arm-mali-c55.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _v4l2-meta-fmt-mali-c55-params: +.. _v4l2-meta-fmt-mali-c55-stats: + +***************************************************************************** +V4L2_META_FMT_MALI_C55_STATS ('C55S'), V4L2_META_FMT_MALI_C55_PARAMS ('C55P') +***************************************************************************** + +3A Statistics +============= + +The ISP device collects different statistics over an input bayer frame. Those +statistics can be obtained by userspace from the +:ref:`mali-c55 3a stats <mali-c55-3a-stats>` metadata capture video node, using +the :c:type:`v4l2_meta_format` interface. The buffer contains a single instance +of the C structure :c:type:`mali_c55_stats_buffer` defined in +``mali-c55-config.h``, so the structure can be obtained from the buffer by: + +.. code-block:: C + + struct mali_c55_stats_buffer *stats = + (struct mali_c55_stats_buffer *)buf; + +For details of the statistics see :c:type:`mali_c55_stats_buffer`. + +Configuration Parameters +======================== + +The configuration parameters are passed to the :ref:`mali-c55 3a params +<mali-c55-3a-params>` metadata output video node, using the +:c:type:`v4l2_meta_format` interface. Rather than a single struct containing +sub-structs for each configurable area of the ISP, parameters for the Mali-C55 +use the v4l2-isp parameters system, through which groups of parameters are +defined as distinct structs or "blocks" which may be added to the data member of +:c:type:`v4l2_isp_params_buffer`. Userspace is responsible for populating the +data member with the blocks that need to be configured by the driver. Each +block-specific struct embeds :c:type:`v4l2_isp_params_block_header` as its first +member and userspace must populate the type member with a value from +:c:type:`mali_c55_param_block_type`. + +.. code-block:: c + + struct v4l2_isp_params_buffer *params = + (struct v4l2_isp_params_buffer *)buffer; + + params->version = MALI_C55_PARAM_BUFFER_V1; + params->data_size = 0; + + void *data = (void *)params->data; + + struct mali_c55_params_awb_gains *gains = + (struct mali_c55_params_awb_gains *)data; + + gains->header.type = MALI_C55_PARAM_BLOCK_AWB_GAINS; + gains->header.flags |= V4L2_ISP_PARAMS_FL_BLOCK_ENABLE; + gains->header.size = sizeof(struct mali_c55_params_awb_gains); + + gains->gain00 = 256; + gains->gain00 = 256; + gains->gain00 = 256; + gains->gain00 = 256; + + data += sizeof(struct mali_c55_params_awb_gains); + params->data_size += sizeof(struct mali_c55_params_awb_gains); + + struct mali_c55_params_sensor_off_preshading *blc = + (struct mali_c55_params_sensor_off_preshading *)data; + + blc->header.type = MALI_C55_PARAM_BLOCK_SENSOR_OFFS; + blc->header.flags |= V4L2_ISP_PARAMS_FL_BLOCK_ENABLE; + blc->header.size = sizeof(struct mali_c55_params_sensor_off_preshading); + + blc->chan00 = 51200; + blc->chan01 = 51200; + blc->chan10 = 51200; + blc->chan11 = 51200; + + params->data_size += sizeof(struct mali_c55_params_sensor_off_preshading); + +Arm Mali-C55 uAPI data types +============================ + +.. kernel-doc:: include/uapi/linux/media/arm/mali-c55-config.h diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst index 1904390df830..cf970750dd4c 100644 --- a/Documentation/userspace-api/media/v4l/subdev-formats.rst +++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst @@ -2225,6 +2225,174 @@ The following table list existing packed 48bit wide RGB formats. \endgroup +The following table list existing packed 60bit wide RGB formats. + +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| + +.. _v4l2-mbus-pixelcode-rgb-60: + +.. raw:: latex + + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} + +.. flat-table:: 60bit RGB formats + :header-rows: 3 + :stub-columns: 0 + :widths: 36 7 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + + * - Identifier + - Code + - + - :cspan:`31` Data organization + * - + - + - Bit + - + - + - + - + - 59 + - 58 + - 57 + - 56 + - 55 + - 54 + - 53 + - 52 + - 51 + - 50 + - 49 + - 48 + - 47 + - 46 + - 45 + - 44 + - 43 + - 42 + - 41 + - 40 + - 39 + - 38 + - 37 + - 36 + - 35 + - 34 + - 33 + - 32 + * - + - + - + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 20 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * .. _MEDIA-BUS-FMT-RGB202020-1X60: + + - MEDIA_BUS_FMT_RGB202020_1X60 + - 0x1026 + - + - + - + - + - + - r\ :sub:`19` + - r\ :sub:`18` + - r\ :sub:`17` + - r\ :sub:`16` + - r\ :sub:`15` + - r\ :sub:`14` + - r\ :sub:`13` + - r\ :sub:`12` + - r\ :sub:`11` + - r\ :sub:`10` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + - g\ :sub:`19` + - g\ :sub:`18` + - g\ :sub:`17` + - g\ :sub:`16` + - g\ :sub:`15` + - g\ :sub:`14` + - g\ :sub:`13` + - g\ :sub:`12` + * - + - + - + - g\ :sub:`11` + - g\ :sub:`10` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + - b\ :sub:`19` + - b\ :sub:`18` + - b\ :sub:`17` + - b\ :sub:`16` + - b\ :sub:`15` + - b\ :sub:`14` + - b\ :sub:`13` + - b\ :sub:`12` + - b\ :sub:`11` + - b\ :sub:`10` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + +.. raw:: latex + + \endgroup + On LVDS buses, usually each sample is transferred serialized in seven time slots per pixel clock, on three (18-bit) or four (24-bit) or five (30-bit) differential data pairs at the same time. The remaining bits are used @@ -2649,7 +2817,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{6.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-bayer: @@ -2662,10 +2830,14 @@ organization is given as an example for the first pixel only. * - Identifier - Code - - - :cspan:`15` Data organization + - :cspan:`19` Data organization * - - - Bit + - 19 + - 18 + - 17 + - 16 - 15 - 14 - 13 @@ -2695,6 +2867,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -2716,6 +2892,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2737,6 +2917,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2758,6 +2942,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -2779,6 +2967,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -2800,6 +2992,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2821,6 +3017,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2842,6 +3042,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -2863,6 +3067,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -2884,6 +3092,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2905,6 +3117,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`7` - g\ :sub:`6` - g\ :sub:`5` @@ -2926,6 +3142,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`7` - r\ :sub:`6` - r\ :sub:`5` @@ -2947,6 +3167,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - 0 - 0 - 0 @@ -2966,6 +3190,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -2987,6 +3215,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`7` - b\ :sub:`6` - b\ :sub:`5` @@ -3006,6 +3238,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - 0 - 0 - 0 @@ -3027,6 +3263,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -3046,6 +3286,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`1` - b\ :sub:`0` - 0 @@ -3067,6 +3311,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`1` - b\ :sub:`0` - 0 @@ -3086,6 +3334,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -3105,6 +3357,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`9` - b\ :sub:`8` - b\ :sub:`7` @@ -3126,6 +3382,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`9` - g\ :sub:`8` - g\ :sub:`7` @@ -3147,6 +3407,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`9` - g\ :sub:`8` - g\ :sub:`7` @@ -3168,6 +3432,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`9` - r\ :sub:`8` - r\ :sub:`7` @@ -3187,6 +3455,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`11` - b\ :sub:`10` - b\ :sub:`9` @@ -3208,6 +3480,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`11` - g\ :sub:`10` - g\ :sub:`9` @@ -3229,6 +3505,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`11` - g\ :sub:`10` - g\ :sub:`9` @@ -3250,6 +3530,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`11` - r\ :sub:`10` - r\ :sub:`9` @@ -3269,6 +3553,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - b\ :sub:`13` - b\ :sub:`12` - b\ :sub:`11` @@ -3290,6 +3578,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`13` - g\ :sub:`12` - g\ :sub:`11` @@ -3311,6 +3603,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - g\ :sub:`13` - g\ :sub:`12` - g\ :sub:`11` @@ -3332,6 +3628,10 @@ organization is given as an example for the first pixel only. - - - + - + - + - + - - r\ :sub:`13` - r\ :sub:`12` - r\ :sub:`11` @@ -3351,6 +3651,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SBGGR16_1X16 - 0x301d - + - + - + - + - - b\ :sub:`15` - b\ :sub:`14` - b\ :sub:`13` @@ -3372,6 +3676,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGBRG16_1X16 - 0x301e - + - + - + - + - - g\ :sub:`15` - g\ :sub:`14` - g\ :sub:`13` @@ -3393,6 +3701,10 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SGRBG16_1X16 - 0x301f - + - + - + - + - - g\ :sub:`15` - g\ :sub:`14` - g\ :sub:`13` @@ -3414,6 +3726,110 @@ organization is given as an example for the first pixel only. - MEDIA_BUS_FMT_SRGGB16_1X16 - 0x3020 - + - + - + - + - + - r\ :sub:`15` + - r\ :sub:`14` + - r\ :sub:`13` + - r\ :sub:`12` + - r\ :sub:`11` + - r\ :sub:`10` + - r\ :sub:`9` + - r\ :sub:`8` + - r\ :sub:`7` + - r\ :sub:`6` + - r\ :sub:`5` + - r\ :sub:`4` + - r\ :sub:`3` + - r\ :sub:`2` + - r\ :sub:`1` + - r\ :sub:`0` + * .. _MEDIA-BUS-FMT-SBGGR20-1X20: + + - MEDIA_BUS_FMT_SBGGR20_1X20 + - 0x3021 + - + - b\ :sub:`19` + - b\ :sub:`18` + - b\ :sub:`17` + - b\ :sub:`16` + - b\ :sub:`15` + - b\ :sub:`14` + - b\ :sub:`13` + - b\ :sub:`12` + - b\ :sub:`11` + - b\ :sub:`10` + - b\ :sub:`9` + - b\ :sub:`8` + - b\ :sub:`7` + - b\ :sub:`6` + - b\ :sub:`5` + - b\ :sub:`4` + - b\ :sub:`3` + - b\ :sub:`2` + - b\ :sub:`1` + - b\ :sub:`0` + * .. _MEDIA-BUS-FMT-SGBRG20-1X20: + + - MEDIA_BUS_FMT_SGBRG20_1X20 + - 0x3022 + - + - g\ :sub:`19` + - g\ :sub:`18` + - g\ :sub:`17` + - g\ :sub:`16` + - g\ :sub:`15` + - g\ :sub:`14` + - g\ :sub:`13` + - g\ :sub:`12` + - g\ :sub:`11` + - g\ :sub:`10` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + * .. _MEDIA-BUS-FMT-SGRBG20-1X20: + + - MEDIA_BUS_FMT_SGRBG20_1X20 + - 0x3023 + - + - g\ :sub:`19` + - g\ :sub:`18` + - g\ :sub:`17` + - g\ :sub:`16` + - g\ :sub:`15` + - g\ :sub:`14` + - g\ :sub:`13` + - g\ :sub:`12` + - g\ :sub:`11` + - g\ :sub:`10` + - g\ :sub:`9` + - g\ :sub:`8` + - g\ :sub:`7` + - g\ :sub:`6` + - g\ :sub:`5` + - g\ :sub:`4` + - g\ :sub:`3` + - g\ :sub:`2` + - g\ :sub:`1` + - g\ :sub:`0` + * .. _MEDIA-BUS-FMT-SRGGB20-1X20: + + - MEDIA_BUS_FMT_SRGGB20_1X20 + - 0x3024 + - + - r\ :sub:`19` + - r\ :sub:`18` + - r\ :sub:`17` + - r\ :sub:`16` - r\ :sub:`15` - r\ :sub:`14` - r\ :sub:`13` diff --git a/Documentation/userspace-api/media/v4l/v4l2-isp.rst b/Documentation/userspace-api/media/v4l/v4l2-isp.rst new file mode 100644 index 000000000000..facf6dba1ca7 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/v4l2-isp.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _v4l2-isp: + +************************ +Generic V4L2 ISP formats +************************ + +Generic ISP formats are metadata formats that define a mechanism to pass ISP +parameters and statistics between userspace and drivers in V4L2 buffers. They +are designed to allow extending them in a backward-compatible way. + +ISP parameters +============== + +The generic ISP configuration parameters format is realized by a defining a +single C structure that contains a header, followed by a binary buffer where +userspace programs a variable number of ISP configuration data block, one for +each supported ISP feature. + +The :c:type:`v4l2_isp_params_buffer` structure defines the buffer header which +is followed by a binary buffer of ISP configuration data. Userspace shall +correctly populate the buffer header with the generic parameters format version +and with the size (in bytes) of the binary data buffer where it will store the +ISP blocks configuration. + +Each *ISP configuration block* is preceded by an header implemented by the +:c:type:`v4l2_isp_params_block_header` structure, followed by the configuration +parameters for that specific block, defined by the ISP driver specific data +types. + +Userspace applications are responsible for correctly populating each block's +header fields (type, flags and size) and the block-specific parameters. + +ISP block enabling, disabling and configuration +----------------------------------------------- + +When userspace wants to configure and enable an ISP block it shall fully +populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE +bit in the block header's `flags` field. + +When userspace simply wants to disable an ISP block the +V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bit should be set in block header's `flags` +field. Drivers accept a configuration parameters block with no additional +data after the header in this case. + +If the configuration of an already active ISP block has to be updated, +userspace shall fully populate the ISP block parameters and omit setting the +V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the +header's `flags` field. + +Setting both the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and +V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the flags field is not allowed and +returns an error. + +Extension to the parameters format can be implemented by adding new blocks +definition without invalidating the existing ones. + +ISP statistics +============== + +Support for generic statistics format is not yet implemented in Video4Linux2. + +V4L2 ISP uAPI data types +======================== + +.. kernel-doc:: include/uapi/linux/media/v4l2-isp.h diff --git a/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst index 1995b39af9ba..b498d60752d7 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst @@ -54,7 +54,7 @@ are invoked. - ``count`` - The number of buffers to be removed with indices 'index' until 'index + count - 1'. All buffers in this range must be valid and in DEQUEUED state. - :ref:`VIDIOC_REMOVE_BUFS` will always check the validity of ``type`, if it is + :ref:`VIDIOC_REMOVE_BUFS` will always check the validity of ``type``, if it is invalid it returns ``EINVAL`` error code. If count is set to 0 :ref:`VIDIOC_REMOVE_BUFS` will do nothing and return 0. * - __u32 |