drivers: video: common: introduce CCI utilities

Add a library for the Camera Common Interface, part of the MIPI CSI
protocol standard defining methods to configure a camera device over I2C,
such as which size for the register address/data.

Signed-off-by: Josuah Demangeon <me@josuah.net>

Author: josuah

drivers/video/Kconfig

@@ -50,6 +50,14 @@ config VIDEO_BUFFER_SMH_ATTRIBUTE
 	  1: SMH_REG_ATTR_NON_CACHEABLE
 	  2: SMH_REG_ATTR_EXTERNAL
 
+config VIDEO_I2C_RETRY_NUM
+	int "Number of attempts for retrying I2C communication if it failed"
+	default 3
+	help
+	  The default is there to reduce the chance of failure (i.e. occasional EMI) without
+	  flooding the I2C bus upon error with too many retries. There is a 1ms wait time between
+	  every retry.
+
 source "drivers/video/Kconfig.esp32_dvp"
 
 source "drivers/video/Kconfig.mcux_csi"

drivers/video/video_common.c

@@ -1,14 +1,23 @@
 /*
  * Copyright (c) 2019, Linaro Limited
- * Copyright (c) 2024, tinyVision.ai Inc.
+ * Copyright (c) 2024-2025, tinyVision.ai Inc.
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include <string.h>
 
-#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/video.h>
+#include <zephyr/kernel.h>
+#include <zephyr/logging/log.h>
+#include <zephyr/sys/byteorder.h>
+#include <zephyr/sys/util.h>
+
+#include "video_common.h"
+
+LOG_MODULE_REGISTER(video_common, CONFIG_VIDEO_LOG_LEVEL);
 
 #if defined(CONFIG_VIDEO_BUFFER_USE_SHARED_MULTI_HEAP)
 #include <zephyr/multi_heap/shared_multi_heap.h>
@@ -164,3 +173,141 @@ void video_closest_frmival(const struct device *dev, enum video_endpoint_id ep,
 		}
 	}
 }
+
+int video_read_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t *data)
+{
+	size_t addr_size = FIELD_GET(VIDEO_REG_ADDR_SIZE_MASK, reg_addr);
+	size_t data_size = FIELD_GET(VIDEO_REG_DATA_SIZE_MASK, reg_addr);
+	bool big_endian = FIELD_GET(VIDEO_REG_ENDIANNESS_MASK, reg_addr);
+	uint16_t addr = FIELD_GET(VIDEO_REG_ADDR_MASK, reg_addr);
+	uint8_t buf_w[sizeof(uint16_t)] = {0};
+	uint8_t *data_ptr;
+	int ret;
+
+	__ASSERT(addr_size > 0, "The address must have a address size flag");
+	__ASSERT(data_size > 0, "The address must have a data size flag");
+
+	if (big_endian) {
+		/* Casting between data sizes in big-endian requires re-aligning */
+		*data = 0;
+		data_ptr = (uint8_t *)data + sizeof(data) - data_size;
+	} else {
+		/* Casting between data sizes in little-endian is a no-op */
+		*data = 0;
+		data_ptr = (uint8_t *)data;
+	}
+
+	for (int i = 0; i < data_size; i++) {
+		if (addr_size == 1) {
+			buf_w[0] = addr + i;
+		} else {
+			sys_put_be16(addr + i, &buf_w[0]);
+		}
+
+		ret = i2c_write_read_dt(i2c, buf_w, addr_size, &data_ptr[i], 1);
+		if (ret != 0) {
+			LOG_ERR("Failed to read from register 0x%x", addr + i);
+			return ret;
+		}
+
+		LOG_HEXDUMP_DBG(buf_w, addr_size, "Data written to the I2C device...");
+		LOG_HEXDUMP_DBG(&data_ptr[i], 1, "... data read back from the I2C device");
+	}
+
+	*data = big_endian ? sys_be32_to_cpu(*data) : sys_le32_to_cpu(*data);
+
+	return 0;
+}
+
+static int video_write_reg_retry(const struct i2c_dt_spec *i2c, uint8_t *buf_w, size_t size)
+{
+	int ret = 0;
+
+	for (int i = 0; i < CONFIG_VIDEO_I2C_RETRY_NUM; i++) {
+		ret = i2c_write_dt(i2c, buf_w, size);
+		if (ret == 0) {
+			return 0;
+		}
+
+		k_sleep(K_MSEC(1));
+	}
+
+	LOG_HEXDUMP_ERR(buf_w, size, "failed to write register configuration over I2C");
+
+	return ret;
+}
+
+int video_write_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t data)
+{
+	size_t addr_size = FIELD_GET(VIDEO_REG_ADDR_SIZE_MASK, reg_addr);
+	size_t data_size = FIELD_GET(VIDEO_REG_DATA_SIZE_MASK, reg_addr);
+	bool big_endian = FIELD_GET(VIDEO_REG_ENDIANNESS_MASK, reg_addr);
+	uint16_t addr = FIELD_GET(VIDEO_REG_ADDR_MASK, reg_addr);
+	uint8_t buf_w[sizeof(uint16_t) + sizeof(uint32_t)] = {0};
+	uint8_t *data_ptr;
+	int ret;
+
+	__ASSERT(addr_size > 0, "The address must have a address size flag");
+	__ASSERT(data_size > 0, "The address must have a data size flag");
+
+	if (big_endian) {
+		/* Casting between data sizes in big-endian requires re-aligning */
+		data = sys_cpu_to_be32(data);
+		data_ptr = (uint8_t *)&data + sizeof(data) - data_size;
+	} else {
+		/* Casting between data sizes in little-endian is a no-op */
+		data = sys_cpu_to_le32(data);
+		data_ptr = (uint8_t *)&data;
+	}
+
+	for (int i = 0; i < data_size; i++) {
+		/* The address is always big-endian as per CCI standard */
+		if (addr_size == 1) {
+			buf_w[0] = addr + i;
+		} else {
+			sys_put_be16(addr + i, &buf_w[0]);
+		}
+
+		buf_w[addr_size] = data_ptr[i];
+
+		LOG_HEXDUMP_DBG(buf_w, addr_size + 1, "Data written to the I2C device");
+
+		ret = video_write_reg_retry(i2c, buf_w, addr_size + 1);
+		if (ret != 0) {
+			LOG_ERR("Failed to write to register 0x%x", addr + i);
+			return ret;
+		}
+	}
+
+	return 0;
+}
+
+int video_modify_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t field_mask,
+			 uint32_t field_value)
+{
+	uint32_t reg;
+	int ret;
+
+	ret = video_read_cci_reg(i2c, reg_addr, &reg);
+	if (ret != 0) {
+		return ret;
+	}
+
+	return video_write_cci_reg(i2c, reg_addr, (reg & ~field_mask) | field_value);
+}
+
+int video_write_cci_multiregs(const struct i2c_dt_spec *i2c, const struct video_reg *regs)
+{
+	int ret;
+
+	for (int i = 0; regs[i].addr != 0; i++) {
+		ret = video_write_cci_reg(i2c, regs[i].addr, regs[i].data);
+		if (ret != 0) {
+			LOG_ERR("Failed to write 0x%04x to register 0x%02x",
+				regs[i].data, regs[i].addr);
+			return ret;
+		}
+	}
+
+	return 0;
+}

drivers/video/video_common.h

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2025 tinyVision.ai Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_DRIVERS_VIDEO_COMMON_H_
+#define ZEPHYR_DRIVERS_VIDEO_COMMON_H_
+
+#include <stddef.h>
+
+#include <zephyr/device.h>
+#include <zephyr/drivers/i2c.h>
+#include <zephyr/kernel.h>
+#include <zephyr/sys/util.h>
+#include <zephyr/types.h>
+
+/**
+ * Type used by register tables that have either the address or value 16-bit wide.
+ */
+struct video_reg {
+	/** Address of the register, and other flags if used with the @ref video_cci API. */
+	uint32_t addr;
+	/** Value to write to this address */
+	uint32_t data;
+};
+
+/**
+ * @defgroup video_cci Video Camera Control Interface (CCI) handling
+ *
+ * The Camera Control Interface (CCI) is an I2C communication scheme part of MIPI-CSI.
+ * It defines how register addresses and register values are packed into I2C messages.
+ *
+ * After the I2C device address, I2C messages payload contain:
+ *
+ * 1. THe 8-bit or 16-bit of the address in big-endian, written to the device.
+ * 3. The 8-bit of the register data either read or written.
+ *
+ * To write to registers larger than 8-bit, multiple read/writes messages are issued.
+ * Endianness and segmentation of larger registers are defined on a per-sensor basis.
+ *
+ * @{
+ */
+
+/** @cond INTERNAL_HIDDEN */
+#define VIDEO_REG_ENDIANNESS_MASK		(uint32_t)(GENMASK(24, 24))
+#define VIDEO_REG_ADDR_SIZE_MASK		(uint32_t)(GENMASK(23, 20))
+#define VIDEO_REG_DATA_SIZE_MASK		(uint32_t)(GENMASK(19, 16))
+#define VIDEO_REG_ADDR_MASK			(uint32_t)(GENMASK(15, 0))
+
+#define VIDEO_REG(addr_size, data_size, endianness)                                                \
+	(FIELD_PREP(VIDEO_REG_ADDR_SIZE_MASK, (addr_size)) |                                       \
+	 FIELD_PREP(VIDEO_REG_DATA_SIZE_MASK, (data_size)) |                                       \
+	 FIELD_PREP(VIDEO_REG_ENDIANNESS_MASK, (endianness)))
+/** @endcond */
+
+/** Flag a register as 8-bit address size, 8-bit data size */
+#define VIDEO_REG_ADDR8_DATA8		VIDEO_REG(1, 1, false)
+/** Flag a register as 8-bit address size, 16-bit data size, little-endian */
+#define VIDEO_REG_ADDR8_DATA16_LE	VIDEO_REG(1, 2, false)
+/** Flag a register as 8-bit address size, 16-bit data size, big-endian */
+#define VIDEO_REG_ADDR8_DATA16_BE	VIDEO_REG(1, 2, true)
+/** Flag a register as 8-bit address size, 24-bit data size, little-endian */
+#define VIDEO_REG_ADDR8_DATA24_LE	VIDEO_REG(1, 3, false)
+/** Flag a register as 8-bit address size, 24-bit data size, big-endian */
+#define VIDEO_REG_ADDR8_DATA24_BE	VIDEO_REG(1, 3, true)
+/** Flag a register as 8-bit address size, 32-bit data size, little-endian */
+#define VIDEO_REG_ADDR8_DATA32_LE	VIDEO_REG(1, 4, false)
+/** Flag a register as 8-bit address size, 32-bit data size, big-endian */
+#define VIDEO_REG_ADDR8_DATA32_BE	VIDEO_REG(1, 4, true)
+/** Flag a register as 16-bit address size, 8-bit data size */
+#define VIDEO_REG_ADDR16_DATA8		VIDEO_REG(2, 1, false)
+/** Flag a register as 16-bit address size, 16-bit data size, little-endian */
+#define VIDEO_REG_ADDR16_DATA16_LE	VIDEO_REG(2, 2, false)
+/** Flag a register as 16-bit address size, 16-bit data size, big-endian */
+#define VIDEO_REG_ADDR16_DATA16_BE	VIDEO_REG(2, 2, true)
+/** Flag a register as 16-bit address size, 24-bit data size, little-endian */
+#define VIDEO_REG_ADDR16_DATA24_LE	VIDEO_REG(2, 3, false)
+/** Flag a register as 16-bit address size, 24-bit data size, big-endian */
+#define VIDEO_REG_ADDR16_DATA24_BE	VIDEO_REG(2, 3, true)
+/** Flag a register as 16-bit address size, 32-bit data size, little-endian */
+#define VIDEO_REG_ADDR16_DATA32_LE	VIDEO_REG(2, 4, false)
+/** Flag a register as 16-bit address size, 32-bit data size, big-endian */
+#define VIDEO_REG_ADDR16_DATA32_BE	VIDEO_REG(2, 4, true)
+
+/**
+ * @brief Write a Camera Control Interface register value with the specified address and size.
+ *
+ * The size of the register address and register data passed as flags in the high bits of
+ * @p reg_addr in the unused bits of the address.
+ *
+ * @brief i2c Reference to the video device on an I2C bus.
+ * @brief reg_addr Address of the register to fill with @reg_value along with size information.
+ * @brief reg_value Value to write at this address, the size to write is encoded in the address.
+ */
+int video_write_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t reg_value);
+
+
+/**
+ * @brief Perform a read-modify-write operation on a register given an address, mask and value.
+ *
+ * The size of the register address and register data passed as flags in the high bits of
+ * @p reg_addr in the unused bits of the address.
+ *
+ * @brief i2c Reference to the video device on an I2C bus.
+ * @brief reg_addr Address of the register to fill with @reg_value along with size information.
+ * @brief field_mask Mask of the field to insert into the existing value.
+ * @brief field_value Value to write at this address, the size to write is encoded in the address.
+ */
+int video_modify_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t field_mask,
+			 uint32_t field_value);
+
+/**
+ * @brief Read a Camera Control Interace register value from the specified address and size.
+ *
+ * The size of the register address and register data passed as flags in the high bits of
+ * @p reg_addr in the unused bits of the address.
+ *
+ * @brief i2c Reference to the video device on an I2C bus.
+ * @brief reg_addr Address of the register to fill with @reg_value along with size information.
+ * @brief reg_value Value to write at this address, the size to write is encoded in the address.
+ *                  This is a 32-bit integer pointer even when reading 8-bit or 16 bits value.
+ */
+int video_read_cci_reg(const struct i2c_dt_spec *i2c, uint32_t reg_addr, uint32_t *reg_value);
+
+/**
+ * @brief Write a complete table of registers to a device one by one.
+ *
+ * The address present in the registers need to be encoding the size information using the macros
+ * such as @ref VIDEO_ADDR16_REG8(). The last element must be empty (@c {0}) to mark the end of the
+ * table.
+ *
+ * @brief i2c Reference to the video device on an I2C bus.
+ * @brief regs Array of address/value pairs to write to the device sequentially.
+ */
+int video_write_cci_multiregs(const struct i2c_dt_spec *i2c, const struct video_reg *regs);
+
+#endif /* ZEPHYR_DRIVERS_VIDEO_COMMON_H_ */