video: add LINK_FREQ ctrl and a helper to retrieve it

Add a ctrl VIDEO_CID_LINK_FREQ to indicate to a sink
the frequency at which a device streams data over
CSI2. Since not all source device currently provide the
LINK_FREQ control, add a helper function to retrieve
it, with a fall-back by doing an approximate via the
PIXEL_RATE control.

Signed-off-by: Alain Volmat <alain.volmat@foss.st.com>

Author: Alain Volmat

drivers/video/video_common.c

@@ -10,6 +10,7 @@
 #include <zephyr/device.h>
 #include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/video.h>
+#include <zephyr/drivers/video-controls.h>
 #include <zephyr/kernel.h>
 #include <zephyr/logging/log.h>
 #include <zephyr/sys/byteorder.h>
@@ -390,3 +391,42 @@ int video_write_cci_multiregs16(const struct i2c_dt_spec *i2c, const struct vide
 
 	return 0;
 }
+
+int64_t video_get_csi_link_freq(const struct device *dev, uint8_t bpp, uint8_t lane_nb)
+{
+	struct video_control ctrl = {
+		.id = VIDEO_CID_LINK_FREQ,
+	};
+	struct video_ctrl_query ctrl_query = {
+		.id = VIDEO_CID_LINK_FREQ,
+	};
+	int ret;
+
+	/* Try to get the LINK_FREQ value from the source device */
+	ret = video_get_ctrl(dev, &ctrl);
+	if (ret < 0) {
+		goto fallback;
+	}
+
+	ret = video_query_ctrl(dev, &ctrl_query);
+	if (ret < 0) {
+		return ret;
+	}
+
+	if (!IN_RANGE(ctrl.val, ctrl_query.range.min, ctrl_query.range.max)) {
+		return -ERANGE;
+	}
+
+	return (int64_t)ctrl_query.int_menu[ctrl.val];
+
+fallback:
+	/* If VIDEO_CID_LINK_FREQ is not available, approximate from VIDEO_CID_PIXEL_RATE */
+	ctrl.id = VIDEO_CID_PIXEL_RATE;
+	ret = video_get_ctrl(dev, &ctrl);
+	if (ret < 0) {
+		return ret;
+	}
+
+	/* CSI D-PHY is using a DDR data bus so bitrate is twice the frequency */
+	return ctrl.val64 * bpp / (2 * lane_nb);
+}

drivers/video/video_ctrls.c

@@ -108,6 +108,9 @@ static inline void set_type_flag(uint32_t id, enum video_ctrl_type *type, uint32
 		*type = VIDEO_CTRL_TYPE_INTEGER64;
 		*flags |= VIDEO_CTRL_FLAG_READ_ONLY;
 		break;
+	case VIDEO_CID_LINK_FREQ:
+		*type = VIDEO_CTRL_TYPE_INTEGER_MENU;
+		break;
 	default:
 		*type = VIDEO_CTRL_TYPE_INTEGER;
 		break;
@@ -539,6 +542,8 @@ static inline const char *video_get_ctrl_name(uint32_t id)
 		return "Pixel Rate";
 	case VIDEO_CID_TEST_PATTERN:
 		return "Test Pattern";
+	case VIDEO_CID_LINK_FREQ:
+		return "Link Frequency";
 	default:
 		return NULL;
 	}

include/zephyr/drivers/video-controls.h

@@ -362,6 +362,9 @@ enum video_camera_orientation {
  */
 #define VIDEO_CID_IMAGE_PROC_CLASS_BASE 0x009f0900
 
+/** Link frequency, applicable for the CSI2 based devices */
+#define VIDEO_CID_LINK_FREQ (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 1)
+
 /** Pixel rate (pixels/second) in the device's pixel array. This control is read-only. */
 #define VIDEO_CID_PIXEL_RATE (VIDEO_CID_IMAGE_PROC_CLASS_BASE + 2)
 

include/zephyr/drivers/video.h

@@ -842,6 +842,23 @@ void video_closest_frmival_stepwise(const struct video_frmival_stepwise *stepwis
  */
 void video_closest_frmival(const struct device *dev, struct video_frmival_enum *match);
 
+/**
+ * @brief Return the link-frequency advertised by a device
+ *
+ * Device exposing a CSI link should advertise at least one of the following two controls:
+ *   - @ref VIDEO_CID_LINK_FREQ
+ *   - @ref VIDEO_CID_PIXEL_RATE
+ *
+ * At first the helper will try read the @ref VIDEO_CID_LINK_FREQ and if not available will
+ * approximate the link-frequency from the @ref VIDEO_CID_PIXEL_RATE value, taking into
+ * consideration the bits per pixel of the format and the number of lanes.
+ *
+ * @param dev Video device to query.
+ * @param bpp Amount of bits per pixel of the pixel format produced by the device
+ * @param lane_nb Number of CSI-2 lanes used
+ */
+int64_t video_get_csi_link_freq(const struct device *dev, uint8_t bpp, uint8_t lane_nb);
+
 /**
  * @defgroup video_pixel_formats Video pixel formats
  * The '|' characters separate the pixels or logical blocks, and spaces separate the bytes.