Skip to contentSkip to conversation

Sub-device configuration models

PATCH Superseded Sakari Ailus 3 participants 12 messages Nov 22, 2024 Media (V4L/DVB)

v1 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

cover Sub-device configuration models

Hello everyone,

I've been recently working (with others) on sub-device streams support as well as on internal pads. The two can be used to make sub-device configuration more versatile.

At the same time, the added interfaces are much more useful if we require specific semantics of those interfaces, so that the user space knows exactly what e.g. a given selection target signifies. However, as the same selection rectangle could be used for a different purpose on a non-raw sensor device, we need a way to tell how should the user space determine how to use a given interface.

I'm proposing to solve this problem by introducing sub-device configuration models, and by the common raw sensor model, also present in this patchset, in particular.

This has been (and will, for some time, continue to be) the reason why I have reviewed few sensor driver related patches lately. As we're introducing a new interface, it's beneficial to be able to use that interface right from the start, rather than trying to later on offer compatibility support, which is almost always a fair amount of work with less than desirable results in the driver.

With this solved, I believe we can enable the use of the streams UAPI.

Comments are welcome.

RFC v1 is <[email protected]> on LMML.

We may end up postponing merging three last patches (those adding controls) until current control values are moved to sub-device (and video device) state. Discussion is needed on the topic.

The compiled documentation can be found here <URL:https://www.retiisi.eu/~sailus/v4l2/tmp/common-raw/output/userspace-api/media/v4l/dev-subdev.html#media-subdev-config-model-common-raw-sensor>.

since v1:

- Rework the documentation according to the comments (spelling fixes, alignment mostly).

- Include separate patches for binning and sub-sampling controls.

- Allow binning, scaling and scaling to be configured using the compose rectangle. This will change to just scaling in the three last patches.

Sakari Ailus (8):
media: Documentation: Rework embedded data documentation
media: Documentation: Add a hyphen to list-based
media: Documentation: Reword split of sensor driver to two classes
media: Documentation: Add subdev configuration models, raw sensor
model
media: uapi: Add V4L2_CID_CONFIG_MODEL control
media: uapi: Add V4L2_CID_BINNING control for binning configuration
media: uapi: Add controls for sub-sampling configuration
media: Documentation: Add binning and sub-sampling controls

 .../media/drivers/camera-sensor.rst           |  53 ++-
 .../media/v4l/common-raw-sensor.dia           | 441 ++++++++++++++++++
 .../media/v4l/common-raw-sensor.svg           | 134 ++++++
 .../userspace-api/media/v4l/dev-subdev.rst    |   2 +
 .../media/v4l/ext-ctrls-camera.rst            |  40 ++
 .../media/v4l/ext-ctrls-image-process.rst     |   4 +
 .../media/v4l/subdev-config-model.rst         | 208 +++++++++
 drivers/media/v4l2-core/v4l2-ctrls-defs.c     |   9 +
 include/uapi/linux/v4l2-controls.h            |   6 +
 9 files changed, 883 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/userspace-api/media/v4l/common-raw-sensor.dia
 create mode 100644 Documentation/userspace-api/media/v4l/common-raw-sensor.svg
 create mode 100644 Documentation/userspace-api/media/v4l/subdev-config-model.rst

base-commit: f188c7293d34f9ac50c1005da2613d519d97db83

Signature · 1 line
2.39.5
#1 lore raw

PATCH 1/8 media: Documentation: Rework embedded data documentation

Rework embedded data documentation by removing the reference to the pixel data stream. The specific documentation of the embedded data interface will be elsewhere, in the near future either CCS or common raw camera sensor model documentation.

---
 .../userspace-api/media/drivers/camera-sensor.rst   | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)
Documentation/userspace-api/media/drivers/camera-sensor.rst +6 -7
index dc415b8f6c8e..8e1083417ae1 100644
@@ -111,13 +111,12 @@ the sensor configuration for the captured frame back to the host. While CSI-2 is
 the most common data interface used by such sensors, embedded data can be
 available on other interfaces as well.
 
-Such sensors expose two internal sink pads (pads that have both the
-``MEDIA_PAD_FL_SINK <MEDIA-PAD-FL-SINK>`` and ``MEDIA_PAD_FL_INTERNAL
-<MEDIA-PAD-FL-INTERNAL>`` flags set) to model the source of the image and
-embedded data streams. Both of these pads produces a single stream, and the
-sub-device routes those streams to the external (source) pad. If the sub-device
-driver supports disabling embedded data, this can be done by disabling the
-embedded data route via the ``VIDIOC_SUBDEV_S_ROUTING`` IOCTL.
+Embedded data support is indicated by the precence of an internal sink pad (pad
+that has both the ``MEDIA_PAD_FL_SINK <MEDIA-PAD-FL-SINK>`` and
+``MEDIA_PAD_FL_INTERNAL <MEDIA-PAD-FL-INTERNAL>`` flags set) with a metadata
+format to model the embedded data stream. If the sub-device driver supports
+disabling embedded data, this can be done by disabling the embedded data route
+via the ``VIDIOC_SUBDEV_S_ROUTING`` IOCTL.
 
 In general, changing the embedded data format from the driver-configured values
 is not supported. The height of the metadata is device-specific and the width
Signature · 1 line
2.39.5
#2 lore raw

PATCH 2/8 media: Documentation: Add a hyphen to list-based

In reply to Sakari Ailus

Add a hyphen to list-based for uniform spelling in camera-sensor.rst.

---
 Documentation/userspace-api/media/drivers/camera-sensor.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/drivers/camera-sensor.rst +3 -3
index 8e1083417ae1..9a1e8aa9fc77 100644
@@ -26,10 +26,10 @@ of cropping and scaling operations from the device's pixel array's size.
 
 An example of such a driver is the CCS driver.
 
-Register list based drivers
+Register list-based drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Register list based drivers generally, instead of able to configure the device
+Register list-based drivers generally, instead of able to configure the device
 they control based on user requests, are limited to a number of preset
 configurations that combine a number of different parameters that on hardware
 level are independent. How a driver picks such configuration is based on the
@@ -67,7 +67,7 @@ is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in
 the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same
 sub-device. The unit of that control is pixels per second.
 
-Register list based drivers need to implement read-only sub-device nodes for the
+Register list-based drivers need to implement read-only sub-device nodes for the
 purpose. Devices that are not register list based need these to configure the
 device's internal processing pipeline.
 
Signature · 1 line
2.39.5
#3 lore raw

PATCH 3/8 media: Documentation: Reword split of sensor driver to two classes

In reply to Sakari Ailus

The sensor drivers do not configure the output size of the sensors but the entire internal pipeline. Reflect this in the documentation.

---
 .../userspace-api/media/drivers/camera-sensor.rst      | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
Documentation/userspace-api/media/drivers/camera-sensor.rst +6 -4
index 9a1e8aa9fc77..bc55c861fb69 100644
@@ -10,11 +10,13 @@ used to control the camera sensor drivers.
 
 You may also find :ref:`media_writing_camera_sensor_drivers` useful.
 
-Frame size
-----------
+Sensor internal pipeline configuration
+--------------------------------------
 
-There are two distinct ways to configure the frame size produced by camera
-sensors.
+Camera sensors have an internal processing pipeline including cropping and
+binning functionality. The sensor drivers belong to two distinct classes, freely
+configurable and register list-based drivers, depending on how the driver
+configures this functionality.
 
 Freely configurable camera sensor drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Signature · 1 line
2.39.5
#4 lore raw

PATCH 4/8 media: Documentation: Add subdev configuration models, raw sensor model

In reply to Sakari Ailus

Sub-device configuration models define what V4L2 API elements are available on a compliant sub-device and how do they behave.

The patch also adds a model for common raw sensors.

---
 .../media/drivers/camera-sensor.rst           |   4 +
 .../media/v4l/common-raw-sensor.dia           | 441 ++++++++++++++++++
 .../media/v4l/common-raw-sensor.svg           | 134 ++++++
 .../userspace-api/media/v4l/dev-subdev.rst    |   2 +
 .../media/v4l/subdev-config-model.rst         | 203 ++++++++
 5 files changed, 784 insertions(+)
 create mode 100644 Documentation/userspace-api/media/v4l/common-raw-sensor.dia
 create mode 100644 Documentation/userspace-api/media/v4l/common-raw-sensor.svg
 create mode 100644 Documentation/userspace-api/media/v4l/subdev-config-model.rst
Documentation/userspace-api/media/drivers/camera-sensor.rst +4 -0
index bc55c861fb69..5bc4c79d230c 100644
@@ -18,6 +18,8 @@ binning functionality. The sensor drivers belong to two distinct classes, freely
 configurable and register list-based drivers, depending on how the driver
 configures this functionality.
 
+Also see :ref:`media_subdev_config_model_common_raw_sensor`.
+
 Freely configurable camera sensor drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -105,6 +107,8 @@ values programmed by the register sequences. The default values of these
 controls shall be 0 (disabled). Especially these controls shall not be inverted,
 independently of the sensor's mounting rotation.
 
+.. _media_using_camera_sensor_drivers_embedded_data:
+
 Embedded data
 -------------
 
Documentation/userspace-api/media/v4l/common-raw-sensor.dia new file +441 -0

441 lines not on this page · raw message

Documentation/userspace-api/media/v4l/common-raw-sensor.svg new file +134 -0

134 lines not on this page · raw message

Documentation/userspace-api/media/v4l/dev-subdev.rst +2 -0
index dcfcbd52490d..4d145bd3bd09 100644
@@ -838,3 +838,5 @@ stream while it may be possible to enable and disable the embedded data stream.
 
 The embedded data format does not need to be configured on the sensor's pads as
 the format is dictated by the pixel data format in this case.
+
+.. include:: subdev-config-model.rst
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +203 -0

203 lines not on this page · raw message

Signature · 1 line
2.39.5
#5 lore raw

Re: [PATCH 4/8] media: Documentation: Add subdev configuration models, raw sensor model

Hi Sakari,

3 small details

Quoted 6 lines · Sakari Ailus

Sub-device configuration models define what V4L2 API elements are available on a compliant sub-device and how do they behave.

The patch also adds a model for common raw sensors.

[SNIP]

Documentation/userspace-api/media/v4l/subdev-config-model.rst line 120

Quoted 7 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +7 -0
+
+The combination of the analogue crop and binning, sub-sampling and scaling
+operations may result in an image size that may be larger than desirable. For
+this purpose, a digital crop operation may be performed on the image after these
+operations. The resulting image size is further output by the sensor.
+
+Drivers may only support some of even none of these configurations, in which
                                   |
				   +-> or ?
Quoted 8 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +8 -0
+case they do not expose the corresponding selection rectangles.
+
+Also refer to :ref:`Selection targets <v4l2-selection-targets-table>`.
+
+.. flat-table:: Selection targets on pads
+    :header-rows: 1
+
+    * - Pad/Stream

Documentation/userspace-api/media/v4l/subdev-config-model.rst line 138

Quoted 10 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +10 -0
+      - Selection target/format
+      - Mandatory (X/-)
+      - Modifiable (X/-)
+      - Synopsis
+    * - 1/0
+      - Format
+      - X
+      - \-
+      - Image data format. The width and height fields of this format are the
+        same than those for the V4L2_SEL_TGT_CROP_BOUNDS rectangle. The media
                --------------
                     |
		     +-> same as
Quoted 4 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +4 -0
+        bus code of this format reflects the native pixel depth of the sensor.
+    * - 1/0
+      - V4L2_SEL_TGT_CROP_BOUNDS
+      - X

Documentation/userspace-api/media/v4l/subdev-config-model.rst line 183

Quoted 10 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +10 -0
+      - \-
+      - X
+      - Digital crop. This rectangle is relative to the V4L2_SEL_TGT_COMPOSE
+        rectangle on (pad, stream) pair 1/0.
+    * - 0/0
+      - Format
+      - X
+      - X
+      - Image data source format. The width and height fields of the format are
+        the same than for the V4L2_SEL_TGT_CROP rectangle on (pad, stream) pair
                    --------
                       |
                       +-> same as

Documentation/userspace-api/media/v4l/subdev-config-model.rst line 190

Quoted 7 lines
Documentation/userspace-api/media/v4l/subdev-config-model.rst new file +7 -0
+        0/0 and the media bus code reflects the pixel data output of the sensor.
+    * - 0/1
+      - Format
+      - X
+      - \-
+      - Embedded data source format.
+

--
Kind Regards
Mehdi Djait

#6 lore raw

Re: [PATCH 4/8] media: Documentation: Add subdev configuration models, raw sensor model

Hi Mehdi,

Quoted 3 lines · Mehdi Djait

Hi Sakari,

3 small details

Thanks, I'll address these in the next version.

This was meant to be RFC v2 btw., it's still a bit too early for merging I think.

Signature · 1 line
Sakari Ailus
#7 lore raw

PATCH 5/8 media: uapi: Add V4L2_CID_CONFIG_MODEL control

In reply to Sakari Ailus

Add the V4L2_CID_CONFIG_MODEL control for the configuration model.

---
 .../userspace-api/media/v4l/ext-ctrls-image-process.rst      | 4 ++++
 drivers/media/v4l2-core/v4l2-ctrls-defs.c                    | 5 +++++
 include/uapi/linux/v4l2-controls.h                           | 3 +++
 3 files changed, 12 insertions(+)
Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst +4 -0
index 27803dca8d3e..928e8e3eed7f 100644
@@ -55,3 +55,7 @@ Image Process Control IDs
     control value divided by e.g. 0x100, meaning that to get no
     digital gain the control value needs to be 0x100. The no-gain
     configuration is also typically the default.
+
+``V4L2_CID_CONFIG_MODEL (bitmask)``
+    Which configuration models the sub-device supports. Please see
+    :ref:`media_subdev_config_model`.
drivers/media/v4l2-core/v4l2-ctrls-defs.c +5 -0
index 1ea52011247a..24c9c25e20d1 100644
@@ -1164,6 +1164,7 @@ const char *v4l2_ctrl_get_name(u32 id)
 	case V4L2_CID_TEST_PATTERN:		return "Test Pattern";
 	case V4L2_CID_DEINTERLACING_MODE:	return "Deinterlacing Mode";
 	case V4L2_CID_DIGITAL_GAIN:		return "Digital Gain";
+	case V4L2_CID_CONFIG_MODEL:		return "Sub-device configuration model";
 
 	/* DV controls */
 	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1481,6 +1482,10 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 	case V4L2_CID_DV_RX_POWER_PRESENT:
 		*type = V4L2_CTRL_TYPE_BITMASK;
 		break;
+	case V4L2_CID_CONFIG_MODEL:
+		*flags |= V4L2_CTRL_FLAG_READ_ONLY;
+		*type = V4L2_CTRL_TYPE_BITMASK;
+		break;
 	case V4L2_CID_MIN_BUFFERS_FOR_CAPTURE:
 	case V4L2_CID_MIN_BUFFERS_FOR_OUTPUT:
 		*type = V4L2_CTRL_TYPE_INTEGER;
include/uapi/linux/v4l2-controls.h +3 -0
index 974fd254e573..0152240229ab 100644
@@ -1225,6 +1225,9 @@ enum v4l2_jpeg_chroma_subsampling {
 #define V4L2_CID_TEST_PATTERN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 3)
 #define V4L2_CID_DEINTERLACING_MODE		(V4L2_CID_IMAGE_PROC_CLASS_BASE + 4)
 #define V4L2_CID_DIGITAL_GAIN			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 5)
+#define V4L2_CID_CONFIG_MODEL			(V4L2_CID_IMAGE_PROC_CLASS_BASE + 6)
+
+#define V4L2_CID_CONFIG_MODEL_COMMON_RAW	(1ULL << 0)
 
 /*  DV-class control IDs defined by V4L2 */
 #define V4L2_CID_DV_CLASS_BASE			(V4L2_CTRL_CLASS_DV | 0x900)
Signature · 1 line
2.39.5
#8 lore raw

PATCH 6/8 media: uapi: Add V4L2_CID_BINNING control for binning configuration

In reply to Sakari Ailus

Add V4L2_CID_BINNING control for configuting binning and enumerating a camera sensor's binning capabilities. The control combines horizontal and vertical binning into a single control as the two are generally related.

New drivers should use this control to configure binning.

---
 .../media/drivers/camera-sensor.rst           | 10 +++++++
 .../media/v4l/ext-ctrls-camera.rst            | 29 +++++++++++++++++++
 drivers/media/v4l2-core/v4l2-ctrls-defs.c     |  2 ++
 include/uapi/linux/v4l2-controls.h            |  1 +
 4 files changed, 42 insertions(+)
Documentation/userspace-api/media/drivers/camera-sensor.rst +10 -0
index 5bc4c79d230c..c6167c91f46c 100644
@@ -107,6 +107,16 @@ values programmed by the register sequences. The default values of these
 controls shall be 0 (disabled). Especially these controls shall not be inverted,
 independently of the sensor's mounting rotation.
 
+Binning
+-------
+
+Binning has traditionally been configured using :ref:`the compose selection
+rectangle <v4l2-selection-targets-table>`. The :ref:`V4L2_CID_BINNING
+<v4l2-cid-camera-sensor-binning>` is also available for binning configuration and
+users should use it when it's available. Drivers supporting the control shall
+also support the compose rectangle, albeit the rectangle may be read-only when
+the control is present.
+
 .. _media_using_camera_sensor_drivers_embedded_data:
 
 Embedded data
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +29 -0
index cdc515c60468..3fbab0e78719 100644
@@ -672,3 +672,32 @@ enum v4l2_scene_mode -
 
     As modes differ for each sensor, menu items are not standardized by this
     control and are left to the programmer.
+
+.. _v4l2-cid-camera-sensor-binning:
+
+``V4L2_CID_BINNING (integer menu)``
+
+    Horizontal and vertical binning factors. Binning combines several
+    horizontal, vertical or both pixel values into a single pixel. It is a way
+    to scale an image. Binning typically produces fairly good quality output.
+
+    Determines both horizontal and vertical binning factors for a camera
+    sensor. The values are encoded in the following way:
+
+.. flat-table::
+    :header-rows:  1
+    :stub-columns: 0
+
+    * - Bits
+      - Synopsis
+    * - 48--63
+      - Horizontal binning numerator.
+    * - 32--47
+      - Horizontal binning denominator.
+    * - 16--31
+      - Vertical binning numerator.
+    * - 0--15
+      - Vertical binning denominator.
+
+For instance, a value of ``0x0001000300020003`` indicates binning by 3
+(horizontally) * 3/2 (vertically).
drivers/media/v4l2-core/v4l2-ctrls-defs.c +2 -0
index 24c9c25e20d1..3a84051ec11c 100644
@@ -1087,6 +1087,7 @@ const char *v4l2_ctrl_get_name(u32 id)
 	case V4L2_CID_CAMERA_ORIENTATION:	return "Camera Orientation";
 	case V4L2_CID_CAMERA_SENSOR_ROTATION:	return "Camera Sensor Rotation";
 	case V4L2_CID_HDR_SENSOR_MODE:		return "HDR Sensor Mode";
+	case V4L2_CID_BINNING:			return "Binning Factors";
 
 	/* FM Radio Modulator controls */
 	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1424,6 +1425,7 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 	case V4L2_CID_HDR_SENSOR_MODE:
 		*type = V4L2_CTRL_TYPE_MENU;
 		break;
+	case V4L2_CID_BINNING:
 	case V4L2_CID_LINK_FREQ:
 		*type = V4L2_CTRL_TYPE_INTEGER_MENU;
 		break;
include/uapi/linux/v4l2-controls.h +1 -0
index 0152240229ab..8d5815a058d7 100644
@@ -1088,6 +1088,7 @@ enum v4l2_auto_focus_range {
 #define V4L2_CID_CAMERA_SENSOR_ROTATION		(V4L2_CID_CAMERA_CLASS_BASE+35)
 
 #define V4L2_CID_HDR_SENSOR_MODE		(V4L2_CID_CAMERA_CLASS_BASE+36)
+#define V4L2_CID_BINNING_FACTORS		(V4L2_CID_CAMERA_CLASS_BASE+37)
 
 /* FM Modulator class control IDs */
 
Signature · 1 line
2.39.5
#9 lore raw

PATCH 7/8 media: uapi: Add controls for sub-sampling configuration

In reply to Sakari Ailus

Sub-sampling is a way to decrease the data rates after the pixel array by systematically discarding some samples, either vertically or horizontally or both. Add two controls for the purpose and document them. The sub-sampling configuration is taken into account in the compose rectangle.

---
 .../userspace-api/media/drivers/camera-sensor.rst  | 14 ++++++++++++--
 .../userspace-api/media/v4l/ext-ctrls-camera.rst   | 11 +++++++++++
 drivers/media/v4l2-core/v4l2-ctrls-defs.c          |  2 ++
 include/uapi/linux/v4l2-controls.h                 |  2 ++
 4 files changed, 27 insertions(+), 2 deletions(-)
Documentation/userspace-api/media/drivers/camera-sensor.rst +12 -2
index c6167c91f46c..e65e82c5940a 100644
@@ -107,8 +107,8 @@ values programmed by the register sequences. The default values of these
 controls shall be 0 (disabled). Especially these controls shall not be inverted,
 independently of the sensor's mounting rotation.
 
-Binning
--------
+Binning and sub-sampling
+------------------------
 
 Binning has traditionally been configured using :ref:`the compose selection
 rectangle <v4l2-selection-targets-table>`. The :ref:`V4L2_CID_BINNING
@@ -117,6 +117,16 @@ users should use it when it's available. Drivers supporting the control shall
 also support the compose rectangle, albeit the rectangle may be read-only when
 the control is present.
 
+Sub-sampling is often supported as part of a camera sensor's binning
+functionality and performed after the binning operation. Sub-sampling typically
+produces quality-wise worse results than binning. Sub-sampling factors are
+independent horizontally and vertically and they are controlled using two
+controls, :ref:`V4L2_CID_SUBSAMPLING_HORIZONTAL and
+V4L2_CID_SUBSAMPLING_VERTICAL <v4l2-cid-camera-sensor-subsampling>`. In
+sub-sampling, the image size before sub-sampling is horizontally and vertically
+divided by the respective sub-sampling factors. Drivers supporting the control shall
+also reflect the sub-sampling configuration in the compose rectangle.
+
 .. _media_using_camera_sensor_drivers_embedded_data:
 
 Embedded data
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +11 -0
index 3fbab0e78719..38fa97397793 100644
@@ -701,3 +701,14 @@ enum v4l2_scene_mode -
 
 For instance, a value of ``0x0001000300020003`` indicates binning by 3
 (horizontally) * 3/2 (vertically).
+
+.. _v4l2-cid-camera-sensor-subsampling:
+
+``V4L2_CID_SUBSAMPLING_HORIZONTAL`` and ``V4L2_CID_SUBSAMPLING_VERTICAL``
+(integer)
+
+    Horizontal and vertical subsampling factors.
+
+    Sub-sampling is used to downscale an image, horizontally and vertically, by
+    discarding a part of the image data. Typically sub-sampling produces lower
+    quality images than binning.
drivers/media/v4l2-core/v4l2-ctrls-defs.c +2 -0
index 3a84051ec11c..62d19b09fd6d 100644
@@ -1088,6 +1088,8 @@ const char *v4l2_ctrl_get_name(u32 id)
 	case V4L2_CID_CAMERA_SENSOR_ROTATION:	return "Camera Sensor Rotation";
 	case V4L2_CID_HDR_SENSOR_MODE:		return "HDR Sensor Mode";
 	case V4L2_CID_BINNING:			return "Binning Factors";
+	case V4L2_CID_SUBSAMPLING_HORIZONTAL:	return "Sub-Sampling Factor, Horizontal";
+	case V4L2_CID_SUBSAMPLING_VERTICAL:	return "Sub-Sampling Factor, Vertical";
 
 	/* FM Radio Modulator controls */
 	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
include/uapi/linux/v4l2-controls.h +2 -0
index 8d5815a058d7..e85747e2181b 100644
@@ -1089,6 +1089,8 @@ enum v4l2_auto_focus_range {
 
 #define V4L2_CID_HDR_SENSOR_MODE		(V4L2_CID_CAMERA_CLASS_BASE+36)
 #define V4L2_CID_BINNING_FACTORS		(V4L2_CID_CAMERA_CLASS_BASE+37)
+#define V4L2_CID_SUBSAMPLING_HORIZONTAL		(V4L2_CID_CAMERA_CLASS_BASE+38)
+#define V4L2_CID_SUBSAMPLING_VERTICAL		(V4L2_CID_CAMERA_CLASS_BASE+39)
 
 /* FM Modulator class control IDs */
 
Signature · 1 line
2.39.5
#10 lore raw

PATCH 8/8 media: Documentation: Add binning and sub-sampling controls

In reply to Sakari Ailus

Document the binning and scaling controls (V4L2_CID_BINNING and V4L2_CID_SUBSAMPLING_{HORIZONTAL,VERTICAL}) in the common raw sensor model.

---
 .../userspace-api/media/v4l/subdev-config-model.rst   | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/subdev-config-model.rst +8 -3
index 25030b80734f..ae39a1bfd2f7 100644
@@ -161,9 +161,14 @@ Also refer to :ref:`Selection targets <v4l2-selection-targets-table>`.
       - \-
       - X
       - Binning, sub-sampling and scaling. This rectangle is relative to the
-        V4L2_SEL_TGT_CROP rectangle on the same (pad, stream). The combination
-        of binning, sub-sampling and scaling is configured using this selection
-        target.
+        V4L2_SEL_TGT_CROP rectangle on the same (pad, stream). Binning is
+        configured using the :ref:`V4L2_CID_BINNING
+        <v4l2-cid-camera-sensor-binning>` control and sub-sampling is configured
+        using the :ref:`V4L2_CID_SUBSAMPLING_HORIZONTAL and
+        V4L2_CID_SUBSAMPLING_VERTICAL <v4l2-cid-camera-sensor-subsampling>`
+        controls. Further on, scaling may be configured by setting the compose
+        rectangle, relative to analogue crop rectangle after binning and
+        sub-sampling.
     * - 2/0
       - Format
       - X
Signature · 1 line
2.39.5
#11 lore raw
In reply to Sakari Ailus

Hi folks,

Quoted 2 lines · Sakari Ailus

The compiled documentation can be found here <URL:https://www.retiisi.eu/~sailus/v4l2/tmp/common-raw/output/userspace-api/media/v4l/dev-subdev.html#media-subdev-config-model-common-raw-sensor>.

The patches depend on the metadata patches that haven't been merged yet. All of them can be found in <URL:https://git.linuxtv.org/sailus/media_tree.git/log/?h=metadata>.

Signature · 1 line
Sakari Ailus