drivers: video: Implement video control framework

Implement the video control framework with the following features:

- Drivers initialize the control with a valid value range at boot which
  guides the application developer and the framework. Hence, the video
  framework could do all common works for drivers e.g., sanity check.

- Controls need to be cached to memory. Video framework handles
  get_ctrl(), drivers don't need to implement this API. It is because
  reading control value directly from registers are not only inefficient
  but also sometimes impossible, e.g. controls that scatter through
  several registers. Only "volatile" control needs to be updated at
  runtime.

- Only the devices (e.g., sensors) owning the controls need to
  implement set_ctrl(). Other devices of the pipeline do not need to
  propagate set_ctrl() and hence, do not need to implement this API

Signed-off-by: Phi Bang Nguyen <[email protected]>

Author: ngphibang

drivers/video/CMakeLists.txt

@@ -3,6 +3,7 @@
 zephyr_library()
 
 zephyr_library_sources(video_common.c)
+zephyr_library_sources(video_ctrls.c)
 zephyr_library_sources(video_device.c)
 
 zephyr_library_sources_ifdef(CONFIG_VIDEO_MCUX_CSI	video_mcux_csi.c)

drivers/video/gc2145.c

@@ -15,6 +15,7 @@
 
 #include <zephyr/logging/log.h>
 
+#include "video_ctrls.h"
 #include "video_device.h"
 
 LOG_MODULE_REGISTER(video_gc2145, CONFIG_VIDEO_LOG_LEVEL);
@@ -692,7 +693,13 @@ struct gc2145_config {
 #endif
 };
 
+struct gc2145_ctrls {
+	struct video_ctrl hflip;
+	struct video_ctrl vflip;
+};
+
 struct gc2145_data {
+	struct gc2145_ctrls ctrls;
 	struct video_format fmt;
 };
 
@@ -1103,13 +1110,13 @@ static int gc2145_get_caps(const struct device *dev, enum video_endpoint_id ep,
 	return 0;
 }
 
-static int gc2145_set_ctrl(const struct device *dev, unsigned int cid, void *value)
+static int gc2145_set_ctrl(const struct device *dev, struct video_control *ctrl)
 {
-	switch (cid) {
+	switch (ctrl->id) {
 	case VIDEO_CID_HFLIP:
-		return gc2145_set_ctrl_hmirror(dev, (int)value);
+		return gc2145_set_ctrl_hmirror(dev, ctrl->val);
 	case VIDEO_CID_VFLIP:
-		return gc2145_set_ctrl_vflip(dev, (int)value);
+		return gc2145_set_ctrl_vflip(dev, ctrl->val);
 	default:
 		return -ENOTSUP;
 	}
@@ -1123,6 +1130,20 @@ static DEVICE_API(video, gc2145_driver_api) = {
 	.set_ctrl = gc2145_set_ctrl,
 };
 
+static int gc2145_init_controls(const struct device *dev)
+{
+	int ret;
+	struct gc2145_data *drv_data = dev->data;
+	struct gc2145_ctrls *ctrls = &drv_data->ctrls;
+
+	ret = video_init_ctrl(&ctrls->hflip, dev, VIDEO_CID_HFLIP, 0, 1, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	return video_init_ctrl(&ctrls->vflip, dev, VIDEO_CID_VFLIP, 0, 1, 1, 0);
+}
+
 static int gc2145_init(const struct device *dev)
 {
 	struct video_format fmt;
@@ -1169,7 +1190,8 @@ static int gc2145_init(const struct device *dev)
 		return ret;
 	}
 
-	return 0;
+	/* Initialize controls */
+	return gc2145_init_controls(dev);
 }
 
 /* Unique Instance */

drivers/video/mt9m114.c

@@ -15,6 +15,7 @@
 #include <zephyr/drivers/video-controls.h>
 #include <zephyr/drivers/i2c.h>
 
+#include "video_ctrls.h"
 #include "video_device.h"
 
 LOG_MODULE_REGISTER(video_mt9m114, CONFIG_VIDEO_LOG_LEVEL);
@@ -65,7 +66,13 @@ struct mt9m114_config {
 	struct i2c_dt_spec i2c;
 };
 
+struct mt9m114_ctrls {
+	struct video_ctrl hflip;
+	struct video_ctrl vflip;
+};
+
 struct mt9m114_data {
+	struct mt9m114_ctrls ctrls;
 	struct video_format fmt;
 };
 
@@ -466,20 +473,20 @@ static int mt9m114_get_caps(const struct device *dev, enum video_endpoint_id ep,
 	return 0;
 }
 
-static int mt9m114_set_ctrl(const struct device *dev, unsigned int cid, void *value)
+static int mt9m114_set_ctrl(const struct device *dev, struct video_control *ctrl)
 {
 	int ret = 0;
 
-	switch (cid) {
+	switch (ctrl->id) {
 	case VIDEO_CID_HFLIP:
 		ret = mt9m114_modify_reg(dev, MT9M114_CAM_SENSOR_CTRL_READ_MODE, 2,
 					MT9M114_CAM_SENSOR_CTRL_HORZ_FLIP_EN,
-					(int)value ? MT9M114_CAM_SENSOR_CTRL_HORZ_FLIP_EN : 0);
+					ctrl->val ? MT9M114_CAM_SENSOR_CTRL_HORZ_FLIP_EN : 0);
 		break;
 	case VIDEO_CID_VFLIP:
 		ret = mt9m114_modify_reg(dev, MT9M114_CAM_SENSOR_CTRL_READ_MODE, 2,
 					MT9M114_CAM_SENSOR_CTRL_VERT_FLIP_EN,
-					(int)value ? MT9M114_CAM_SENSOR_CTRL_VERT_FLIP_EN : 0);
+					ctrl->val ? MT9M114_CAM_SENSOR_CTRL_VERT_FLIP_EN : 0);
 		break;
 	default:
 		return -ENOTSUP;
@@ -501,6 +508,21 @@ static DEVICE_API(video, mt9m114_driver_api) = {
 	.set_ctrl = mt9m114_set_ctrl,
 };
 
+static int mt9m114_init_controls(const struct device *dev)
+{
+	int ret;
+	struct mt9m114_data *drv_data = dev->data;
+	struct mt9m114_ctrls *ctrls = &drv_data->ctrls;
+
+
+	ret = video_init_ctrl(&ctrls->hflip, dev, VIDEO_CID_HFLIP, 0, 1, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	return video_init_ctrl(&ctrls->vflip, dev, VIDEO_CID_VFLIP, 0, 1, 1, 0);
+}
+
 static int mt9m114_init(const struct device *dev)
 {
 	struct video_format fmt;
@@ -546,7 +568,8 @@ static int mt9m114_init(const struct device *dev)
 	/* Suspend any stream */
 	mt9m114_set_state(dev, MT9M114_SYS_STATE_ENTER_SUSPEND);
 
-	return 0;
+	/* Initialize controls */
+	return mt9m114_init_controls(dev);
 }
 
 #if 1 /* Unique Instance */

drivers/video/ov2640.c

@@ -14,6 +14,7 @@
 #include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/gpio.h>
 
+#include "video_ctrls.h"
 #include "video_device.h"
 
 LOG_MODULE_REGISTER(video_ov2640, CONFIG_VIDEO_LOG_LEVEL);
@@ -441,7 +442,21 @@ struct ov2640_config {
 	uint8_t clock_rate_control;
 };
 
+struct ov2640_ctrls {
+	struct video_ctrl hflip;
+	struct video_ctrl vflip;
+	struct video_ctrl ae;
+	struct video_ctrl awb;
+	struct video_ctrl gain;
+	struct video_ctrl contrast;
+	struct video_ctrl brightness;
+	struct video_ctrl saturation;
+	struct video_ctrl jpeg;
+	struct video_ctrl test_pattern;
+};
+
 struct ov2640_data {
+	struct ov2640_ctrls ctrls;
 	struct video_format fmt;
 };
 
@@ -565,10 +580,7 @@ static int ov2640_set_level(const struct device *dev, int level,
 	int ret = 0;
 	const struct ov2640_config *cfg = dev->config;
 
-	level += (max_level / 2 + 1);
-	if (level < 0 || level > max_level) {
-		return -ENOTSUP;
-	}
+	level += max_level / 2 + 1;
 
 	/* Switch to DSP register bank */
 	ret |= ov2640_write_reg(&cfg->i2c, BANK_SEL, BANK_SEL_DSP);
@@ -580,48 +592,6 @@ static int ov2640_set_level(const struct device *dev, int level,
 	return ret;
 }
 
-static int ov2640_set_brightness(const struct device *dev, int level)
-{
-	int ret = 0;
-
-	ret = ov2640_set_level(dev, level, NUM_BRIGHTNESS_LEVELS,
-			ARRAY_SIZE(brightness_regs[0]), brightness_regs);
-
-	if (ret == -ENOTSUP) {
-		LOG_ERR("Brightness level %d not supported", level);
-	}
-
-	return ret;
-}
-
-static int ov2640_set_saturation(const struct device *dev, int level)
-{
-	int ret = 0;
-
-	ret = ov2640_set_level(dev, level, NUM_SATURATION_LEVELS,
-			ARRAY_SIZE(saturation_regs[0]), saturation_regs);
-
-	if (ret == -ENOTSUP) {
-		LOG_ERR("Saturation level %d not supported", level);
-	}
-
-	return ret;
-}
-
-static int ov2640_set_contrast(const struct device *dev, int level)
-{
-	int ret = 0;
-
-	ret = ov2640_set_level(dev, level, NUM_CONTRAST_LEVELS,
-			ARRAY_SIZE(contrast_regs[0]), contrast_regs);
-
-	if (ret == -ENOTSUP) {
-		LOG_ERR("Contrast level %d not supported", level);
-	}
-
-	return ret;
-}
-
 static int ov2640_set_output_format(const struct device *dev,
 				int output_format)
 {
@@ -925,47 +895,35 @@ static int ov2640_get_caps(const struct device *dev,
 	return 0;
 }
 
-static int ov2640_set_ctrl(const struct device *dev,
-				unsigned int cid, void *value)
+static int ov2640_set_ctrl(const struct device *dev, struct video_control *ctrl)
 {
-	int ret = 0;
-
-	switch (cid) {
+	switch (ctrl->id) {
 	case VIDEO_CID_HFLIP:
-		ret |= ov2640_set_horizontal_mirror(dev, (int)value);
-		break;
+		return ov2640_set_horizontal_mirror(dev, ctrl->val);
 	case VIDEO_CID_VFLIP:
-		ret |= ov2640_set_vertical_flip(dev, (int)value);
-		break;
+		return ov2640_set_vertical_flip(dev, ctrl->val);
 	case VIDEO_CID_EXPOSURE:
-		ret |= ov2640_set_exposure_ctrl(dev, (int)value);
-		break;
+		return ov2640_set_exposure_ctrl(dev, ctrl->val);
+	case VIDEO_CID_WHITE_BALANCE_TEMPERATURE:
+		return ov2640_set_white_bal(dev, ctrl->val);
 	case VIDEO_CID_GAIN:
-		ret |= ov2640_set_gain_ctrl(dev, (int)value);
-		break;
+		return ov2640_set_gain_ctrl(dev, ctrl->val);
 	case VIDEO_CID_BRIGHTNESS:
-		ret |= ov2640_set_brightness(dev, (int)value);
-		break;
-	case VIDEO_CID_SATURATION:
-		ret |= ov2640_set_saturation(dev, (int)value);
-		break;
-	case VIDEO_CID_WHITE_BALANCE_TEMPERATURE:
-		ret |= ov2640_set_white_bal(dev, (int)value);
-		break;
+		return ov2640_set_level(dev, ctrl->val, NUM_BRIGHTNESS_LEVELS,
+					ARRAY_SIZE(brightness_regs[0]), brightness_regs);
 	case VIDEO_CID_CONTRAST:
-		ret |= ov2640_set_contrast(dev, (int)value);
-		break;
-	case VIDEO_CID_TEST_PATTERN:
-		ret |= ov2640_set_colorbar(dev, (int)value);
-		break;
+		return ov2640_set_level(dev, ctrl->val, NUM_CONTRAST_LEVELS,
+					ARRAY_SIZE(contrast_regs[0]), contrast_regs);
+	case VIDEO_CID_SATURATION:
+		return ov2640_set_level(dev, ctrl->val, NUM_SATURATION_LEVELS,
+					ARRAY_SIZE(saturation_regs[0]), saturation_regs);
 	case VIDEO_CID_JPEG_COMPRESSION_QUALITY:
-		ret |= ov2640_set_quality(dev, (int)value);
-		break;
+		return ov2640_set_quality(dev, ctrl->val);
+	case VIDEO_CID_TEST_PATTERN:
+		return ov2640_set_colorbar(dev, ctrl->val);
 	default:
 		return -ENOTSUP;
 	}
-
-	return ret;
 }
 
 static DEVICE_API(video, ov2640_driver_api) = {
@@ -976,6 +934,61 @@ static DEVICE_API(video, ov2640_driver_api) = {
 	.set_ctrl = ov2640_set_ctrl,
 };
 
+static int ov2640_init_controls(const struct device *dev)
+{
+	int ret;
+	struct ov2640_data *drv_data = dev->data;
+	struct ov2640_ctrls *ctrls = &drv_data->ctrls;
+
+	ret = video_init_ctrl(&ctrls->hflip, dev, VIDEO_CID_HFLIP, 0, 1, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->vflip, dev, VIDEO_CID_VFLIP, 0, 1, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->ae, dev, VIDEO_CID_EXPOSURE, 0, 1, 1, 1);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->awb, dev, VIDEO_CID_WHITE_BALANCE_TEMPERATURE, 0, 1, 1, 1);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->gain, dev, VIDEO_CID_GAIN, 0, 1, 1, 1);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->brightness, dev, VIDEO_CID_BRIGHTNESS, -2, 2, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->contrast, dev, VIDEO_CID_CONTRAST, -2, 2, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->saturation, dev, VIDEO_CID_SATURATION, -2, 2, 1, 0);
+	if (ret) {
+		return ret;
+	}
+
+	ret = video_init_ctrl(&ctrls->saturation, dev, VIDEO_CID_JPEG_COMPRESSION_QUALITY, 5, 100,
+			      1, 50);
+	if (ret) {
+		return ret;
+	}
+
+	return video_init_ctrl(&ctrls->test_pattern, dev, VIDEO_CID_TEST_PATTERN, 0, 1, 1, 0);
+}
+
 static int ov2640_init(const struct device *dev)
 {
 	struct video_format fmt;
@@ -1020,7 +1033,12 @@ static int ov2640_init(const struct device *dev)
 	ret |= ov2640_set_exposure_ctrl(dev, 1);
 	ret |= ov2640_set_white_bal(dev, 1);
 
-	return ret;
+	if (ret) {
+		return ret;
+	}
+
+	/* Initialize controls */
+	return ov2640_init_controls(dev);
 }
 
 /* Unique Instance */