[PATCH v12 05/86] media: uapi: Add V4L2_CID_CFA_PATTERN for describing color patterns

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

Add V4L2_CID_CFA_PATTERN to tell the camera sensor's native Color Filter
Array (CFA) pattern.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
Reviewed-by: Mirela Rabulea <mirela.rabulea@nxp.com>
---
.../media/v4l/ext-ctrls-image-source.rst | 43 +++++++++++++++++++
.../media/v4l/subdev-formats.rst | 2 +
drivers/media/v4l2-core/v4l2-ctrls-defs.c | 1 +
include/uapi/linux/v4l2-controls.h | 6 +++
4 files changed, 52 insertions(+)

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 f9c0b7ad3b4e..b09ad4b4576e 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -93,3 +93,46 @@ Image Source Control IDs
representing a gain of exactly 1.0. For example, if this default value
is reported as being (say) 128, then a value of 192 would represent
a gain of exactly 1.5.
+
+``V4L2_CID_CFA_PATTERN (integer)``
+ This control determines the color components and native pixel order in the
+ sensor's CFA (Color Filter Array) when used in conjunction with
+ :ref:`generic raw mbus codes MEDIA_BUS_FMT_RAW_x (where 'x' is the bit
+ depth) <v4l2-mbus-pixelcode-generic-raw>` pixelcodes. The native pixel
+ order is constant for a given device, it is not affected by cropping or
+ flipping.
+
+ This control may only be used on V4L2 sub-devices.
+
+ This is a read-only control.
+
+ Available patterns:
+
+.. flat-table:: V4L2 Color Filter Array Patterns
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 2 1
+
+ * - Macro name
+ - Synopsis
+ - Value
+ * - V4L2_CFA_PATTERN_GRBG
+ - Bayer pattern (2x2 macroblocks). Each macroblock has a green filter in
+ the top-left and bottom-right pixels, a red filter in the top-right
+ pixel, and a blue filter in the bottom-left pixel.
+ - 0
+ * - V4L2_CFA_PATTERN_RGGB
+ - Bayer pattern (2x2 macroblocks). Each macroblock has a green filter in
+ the top-right and bottom-left pixels, a red filter in the top-left
+ pixel, and a blue filter in the bottom-right pixel.
+ - 1
+ * - V4L2_CFA_PATTERN_BGGR
+ - Bayer pattern (2x2 macroblocks). Each macroblock has a green filter in
+ the top-right and bottom-left pixels, a blue filter in the top-left
+ pixel, and a red filter in the bottom-right pixel.
+ - 2
+ * - V4L2_CFA_PATTERN_GBRG
+ - Bayer pattern (2x2 macroblocks). Each macroblock has a green filter in
+ the top-left and bottom-right pixels, a blue filter in the top-right
+ pixel, and a red filter in the bottom-left pixel.
+ - 3
diff --git a/Documentation/userspace-api/media/v4l/subdev-formats.rst b/Documentation/userspace-api/media/v4l/subdev-formats.rst
index fecb786cb8af..7d34c2991f81 100644
--- a/Documentation/userspace-api/media/v4l/subdev-formats.rst
+++ b/Documentation/userspace-api/media/v4l/subdev-formats.rst
@@ -3855,6 +3855,8 @@ organization is given as an example for the first pixel only.

\endgroup

+.. _v4l2-mbus-pixelcode-generic-raw:
+
Generic raw formats on serial interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
index aab785e8948c..4fafc7a3c233 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
@@ -1157,6 +1157,7 @@ const char *v4l2_ctrl_get_name(u32 id)
case V4L2_CID_TEST_PATTERN_BLUE: return "Blue Pixel Value";
case V4L2_CID_TEST_PATTERN_GREENB: return "Green (Blue) Pixel Value";
case V4L2_CID_NOTIFY_GAINS: return "Notify Gains";
+ case V4L2_CID_CFA_PATTERN: return "Color Filter Array Pattern";

/* Image processing controls */
/* Keep the order of the 'case's the same as in v4l2-controls.h! */
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 349d75d0da32..78c6fc69b1c1 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -1235,6 +1235,12 @@ enum v4l2_jpeg_chroma_subsampling {
#define V4L2_CID_UNIT_CELL_SIZE (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 8)
#define V4L2_CID_NOTIFY_GAINS (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 9)

+#define V4L2_CID_CFA_PATTERN (V4L2_CID_IMAGE_SOURCE_CLASS_BASE + 10)
+#define V4L2_CFA_PATTERN_GRBG 0U
+#define V4L2_CFA_PATTERN_RGGB 1U
+#define V4L2_CFA_PATTERN_BGGR 2U
+#define V4L2_CFA_PATTERN_GBRG 3U
+

/* Image processing controls */

--
2.47.3