drivers: video: Add video query control API

Application can query information about a control given the control id,
the framework fill the rest of the structure. Application can also
enumerate all kinds of device's supported controls by iterating with
VIDEO_CTRL_FLAG_NEXT_CTRL on the same API.

Signed-off-by: Phi Bang Nguyen <phibang.nguyen@nxp.com>

Author: ngphibang

drivers/video/video_ctrls.c

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include <stdio.h>
+
 #include <zephyr/drivers/video.h>
 #include <zephyr/drivers/video-controls.h>
 #include <zephyr/logging/log.h>
@@ -67,6 +69,7 @@ int video_init_ctrl(struct video_ctrl *ctrl, const struct device *dev, uint32_t
 	int ret;
 	uint32_t flags;
 	enum video_ctrl_type type;
+	struct video_ctrl *vc;
 	struct video_device *vdev = video_find_vdev(dev);
 
 	if (!vdev) {
@@ -95,6 +98,14 @@ int video_init_ctrl(struct video_ctrl *ctrl, const struct device *dev, uint32_t
 	ctrl->def = def;
 	ctrl->val = def;
 
+	/* Insert in an ascending order of ctrl's id */
+	SYS_DLIST_FOR_EACH_CONTAINER(&vdev->ctrls, vc, node) {
+		if (vc->id > ctrl->id) {
+			sys_dlist_insert(&vc->node, &ctrl->node);
+			return 0;
+		}
+	}
+
 	sys_dlist_append(&vdev->ctrls, &ctrl->node);
 
 	return 0;
@@ -173,3 +184,131 @@ int video_set_ctrl(const struct device *dev, struct video_control *control)
 
 	return 0;
 }
+
+static inline const char *video_get_ctrl_name(uint32_t id)
+{
+	switch (id) {
+	/* User controls */
+	case VIDEO_CID_BRIGHTNESS:
+		return "Brightness";
+	case VIDEO_CID_CONTRAST:
+		return "Contrast";
+	case VIDEO_CID_SATURATION:
+		return "Saturation";
+	case VIDEO_CID_HUE:
+		return "Hue";
+	case VIDEO_CID_EXPOSURE:
+		return "Exposure";
+	case VIDEO_CID_GAIN:
+		return "Gain";
+	case VIDEO_CID_HFLIP:
+		return "Horizontal Flip";
+	case VIDEO_CID_VFLIP:
+		return "Vertical Flip";
+	case VIDEO_CID_POWER_LINE_FREQUENCY:
+		return "Power Line Frequency";
+
+	/* Camera controls */
+	case VIDEO_CID_ZOOM_ABSOLUTE:
+		return "Zoom, Absolute";
+
+	/* JPEG encoder controls */
+	case VIDEO_CID_JPEG_COMPRESSION_QUALITY:
+		return "Compression Quality";
+
+	/* Image processing controls */
+	case VIDEO_CID_PIXEL_RATE:
+		return "Pixel Rate";
+	case VIDEO_CID_TEST_PATTERN:
+		return "Test Pattern";
+	default:
+		return NULL;
+	}
+}
+
+int video_query_ctrl(const struct device *dev, struct video_ctrl_query *cq)
+{
+	int ret;
+	struct video_device *vdev;
+	struct video_ctrl *ctrl = NULL;
+
+	if (cq->id & VIDEO_CTRL_FLAG_NEXT_CTRL) {
+		vdev = video_find_vdev(dev);
+		cq->id &= ~VIDEO_CTRL_FLAG_NEXT_CTRL;
+		while (vdev) {
+			SYS_DLIST_FOR_EACH_CONTAINER(&vdev->ctrls, ctrl, node) {
+				if (ctrl->id > cq->id) {
+					goto fill_query;
+				}
+			}
+			vdev = video_find_vdev(vdev->src_dev);
+		}
+		return -ENOTSUP;
+	}
+
+	ret = video_find_ctrl(dev, cq->id, &ctrl);
+	if (ret) {
+		return ret;
+	}
+
+fill_query:
+	cq->id = ctrl->id;
+	cq->type = ctrl->type;
+	cq->flags = ctrl->flags;
+	cq->min = ctrl->min;
+	cq->max = ctrl->max;
+	cq->step = ctrl->step;
+	cq->def = ctrl->def;
+	cq->name = video_get_ctrl_name(cq->id);
+
+	return 0;
+}
+
+void video_print_ctrl(const struct device *const dev, const struct video_ctrl_query *const cq)
+{
+	uint8_t i = 0;
+	const char *type = NULL;
+	char typebuf[8];
+
+	__ASSERT(dev && cq, "Invalid arguments");
+
+	/* Get type of the control */
+	switch (cq->type) {
+	case VIDEO_CTRL_TYPE_BOOLEAN:
+		type = "bool";
+		break;
+	case VIDEO_CTRL_TYPE_INTEGER:
+		type = "int";
+		break;
+	case VIDEO_CTRL_TYPE_INTEGER64:
+		type = "int64";
+		break;
+	case VIDEO_CTRL_TYPE_MENU:
+		type = "menu";
+		break;
+	case VIDEO_CTRL_TYPE_STRING:
+		type = "string";
+		break;
+	default:
+		break;
+	}
+	snprintf(typebuf, sizeof(typebuf), "(%s)", type);
+
+	/* Get current value of the control */
+	struct video_control vc = {.id = cq->id};
+
+	video_get_ctrl(dev, &vc);
+
+	/* Print the control information */
+	if (cq->type == VIDEO_CTRL_TYPE_INTEGER64) {
+		LOG_INF("%32s 0x%08x %-8s (flags=0x%02x) : min=%lld max=%lld step=%lld "
+			"default=%lld value=%lld ",
+			cq->name, cq->id, typebuf, cq->flags, cq->range.min64, cq->range.max64,
+			cq->range.step64, cq->range.def64, vc.val64);
+	} else {
+		LOG_INF("%32s 0x%08x %-8s (flags=0x%02x) : min=%d max=%d step=%d default=%d "
+			"value=%d ",
+			cq->name, cq->id, typebuf, cq->flags, cq->range.min, cq->range.max,
+			cq->range.step, cq->range.def, vc.val);
+	}
+}

include/zephyr/drivers/video-controls.h

@@ -78,6 +78,9 @@ enum video_power_line_frequency {
 /** Balance of colors in direction of blue (cold) or red (warm) */
 #define VIDEO_CID_WHITE_BALANCE_TEMPERATURE (VIDEO_CID_BASE + 26)
 
+/** Last base CID + 1 */
+#define VIDEO_CID_LASTP1 (VIDEO_CID_BASE + 44)
+
 /**
  * @}
  */
@@ -160,6 +163,16 @@ enum video_power_line_frequency {
  */
 #define VIDEO_CID_PRIVATE_BASE 0x08000000
 
+/**
+ * @}
+ */
+
+/**
+ * @name Query flags, to be ORed with the control ID
+ * @{
+ */
+#define VIDEO_CTRL_FLAG_NEXT_CTRL 0x80000000
+
 /**
  * @}
  */
@@ -183,6 +196,33 @@ struct video_control {
 	int32_t val;
 };
 
+/**
+ * @struct video_control_query
+ * @brief Video control query structure
+ *
+ * Used to query information about a control.
+ */
+struct video_ctrl_query {
+	/** control id */
+	uint32_t id;
+	/** control type */
+	uint32_t type;
+	/** control name */
+	const char *name;
+	/** control flags */
+	uint32_t flags;
+	/** control minimum value, inclusive */
+	int32_t min;
+	/** control maximum value, inclusive */
+	int32_t max;
+	/** control value step */
+	int32_t step;
+	/** control default value for VIDEO_CTRL_TYPE_INTEGER, _BOOLEAN, _MENU or
+	 * _INTEGER_MENU, not valid for other types
+	 */
+	int32_t def;
+};
+
 /**
  * @}
  */

include/zephyr/drivers/video.h

@@ -672,6 +672,41 @@ int video_set_ctrl(const struct device *dev, struct video_control *control);
  */
 int video_get_ctrl(const struct device *dev, struct video_control *control);
 
+struct video_ctrl_query;
+
+/**
+ * @brief Query information about a control.
+ *
+ * Applications set the id field of the query structure, the function fills the rest of this
+ * structure. It is possible to enumerate base class controls (i.e., VIDEO_CID_BASE + x) by calling
+ * this function with successive id values starting from VIDEO_CID_BASE up to and exclusive
+ * VIDEO_CID_LASTP1. The function may return -ENOTSUP if a control in this range is not supported.
+ * Applications can also enumerate private controls by starting at VIDEO_CID_PRIVATE_BASE and
+ * incrementing the id until the driver returns -ENOTSUP. For other control classes, it's a bit more
+ * difficult. Hence, the best way to enumerate all kinds of device's supported controls is to
+ * iterate with VIDEO_CTRL_FLAG_NEXT_CTRL.
+ *
+ * @param dev Pointer to the device structure.
+ * @param cq Pointer to the control query struct.
+ *
+ * @retval 0 If successful.
+ * @retval -EINVAL If the control id is invalid.
+ * @retval -ENOTSUP If the control id is not supported.
+ */
+int video_query_ctrl(const struct device *dev, struct video_ctrl_query *cq);
+
+/**
+ * @brief Print all the information of a control.
+ *
+ * Print all the information of a control including its name, type, flag, range,
+ * menu (if any) and current value, i.e. by invoking the video_get_ctrl(), in a
+ * human readble format.
+ *
+ * @param dev Pointer to the device structure.
+ * @param cq Pointer to the control query struct.
+ */
+void video_print_ctrl(const struct device *const dev, const struct video_ctrl_query *const cq);
+
 /**
  * @brief Register/Unregister k_poll signal for a video endpoint.
  *

samples/drivers/video/capture/src/main.c

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2019 Linaro Limited
+ * Copyright 2025 NXP
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -174,6 +175,16 @@ int main(void)
 		fie.index++;
 	}
 
+	/* Get supported controls */
+	LOG_INF("- Supported controls:");
+
+	struct video_ctrl_query cq = {.id = VIDEO_CTRL_FLAG_NEXT_CTRL};
+
+	while (!video_query_ctrl(video_dev, &cq)) {
+		video_print_ctrl(video_dev, &cq);
+		cq.id |= VIDEO_CTRL_FLAG_NEXT_CTRL;
+	}
+
 	/* Set controls */
 	struct video_control ctrl = {VIDEO_CID_HFLIP, 1};