[PATCH v12 27/86] media: uapi: Add V4L2_CID_BINNING control for binning configuration

Sakari Ailus
2026-04-09T20:15:30Z

Add V4L2_CID_BINNING control for configuring 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.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
---
.../media/drivers/camera-sensor.rst | 12 ++++++++
.../media/v4l/ext-ctrls-image-source.rst | 30 +++++++++++++++++++
drivers/media/v4l2-core/v4l2-ctrls-defs.c | 2 ++
include/uapi/linux/v4l2-controls.h | 2 ++
4 files changed, 46 insertions(+)

diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst
index d8ba809486c5..12f075379bc8 100644
--- a/Documentation/userspace-api/media/drivers/camera-sensor.rst
+++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst
@@ -120,6 +120,18 @@ 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
+<image_source_control_binning_factors>` control 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.
+
+Binning isn't affected by flipping.
+
.. _media_using_camera_sensor_drivers_embedded_data:

Embedded data
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
index 490cd16186cd..0ef76b02a6e1 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -160,3 +160,33 @@ Image Source Control IDs
interface for metadata streams. The control is used in conjunction with
:ref:`generic metadata formats <media-bus-format-generic-meta>` formats to
specify the layout of the data.
+
+.. _image_source_control_binning_factors:
+
+``V4L2_CID_BINNING_FACTORS (integer menu)``
+
+ This control determines 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).
diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
index 4618252d24f2..fee343667b69 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
@@ -1160,6 +1160,7 @@ const char *v4l2_ctrl_get_name(u32 id)
case V4L2_CID_CFA_PATTERN: return "Color Filter Array Pattern";
case V4L2_CID_CFA_PATTERN_FLIP: return "CFA Pattern Flip";
case V4L2_CID_METADATA_LAYOUT: return "Metadata Layout";
+ case V4L2_CID_BINNING_FACTORS: return "Binning Factors";

/* Image processing controls */
/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1438,6 +1439,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_FACTORS:
case V4L2_CID_LINK_FREQ:
*type = V4L2_CTRL_TYPE_INTEGER_MENU;
break;
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 1bf6d298e3c4..5496b1664432 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -1249,6 +1249,8 @@ enum v4l2_jpeg_chroma_subsampling {

#define V4L2_CID_METADATA_LAYOUT (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 12)

+#define V4L2_CID_BINNING_FACTORS (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 13)
+
/* Image processing controls */

#define V4L2_CID_IMAGE_PROC_CLASS_BASE (V4L2_CTRL_CLASS_IMAGE_PROC | 0x900)
--
2.47.3