drivers: video: introduce "GET" sub-operations

The video_get_ctrl() API permits to retrieve a value from a device using
standard CIDs from <zephyr/drivers/video-controls.h>. The CIDs do not come
with a range information, and to know which value to apply to a video
driver, knowing the minimum and maximum value before-hand is required.
This prevents building generic layers that handle any video devices, such
as protocols such as USB UVC, GigE Vision, or anything making use of
"zephyr,camera" chosen node.

This commit introduces extra flags added to the CIDs that indicates to the
target device that instead of returning the current value, they should
return the minimum, maximum, or default value instead, with the same type
as the current value.

The GET_CUR operation having a flag of 0x00, this makes all drivers
implicitly support this new API, with an opt-in migration to also support
the extra controls, correctly rejecting the unsupported extra operations by
default.

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

Author: josuah

include/zephyr/drivers/video-controls.h

@@ -42,6 +42,31 @@ extern "C" {
  * @}
  */
 
+/**
+ * @name Control Get operations
+ *
+ * Extra flags for video controls to inquire about the dimensions of an existing
+ * control: the minimum, maximum, or default value.
+ *
+ * For instance, OR-ing @c VIDEO_CID_CAMERA_EXPOSURE and @c VIDEO_CTRL_GET_MAX
+ * permits to query the maximum exposure time instead of the current exposure
+ * time.
+ *
+ * If no Control Get flag is added to a CID, the behavior is to fetch the current
+ * value as with @ref VIDEO_CTRL_GET_CUR.
+ * These must only be used along with the @ref video_get_ctrl() API.
+ *
+ * @{
+ */
+#define VIDEO_CTRL_GET_CUR		0x00000000	/**< Get the current value */
+#define VIDEO_CTRL_GET_MIN		0x00001000	/**< Get the minimum value */
+#define VIDEO_CTRL_GET_MAX		0x00002000	/**< Get the maximum value */
+#define VIDEO_CTRL_GET_DEF		0x00003000	/**< Get the default value */
+#define VIDEO_CTRL_GET_MASK		0x0000f000	/**< Mask for get operations */
+/**
+ * @}
+ */
+
 /**
  * @name Generic class control IDs
  * @{

include/zephyr/drivers/video.h

@@ -16,7 +16,7 @@
  * @brief Video Interface
  * @defgroup video_interface Video Interface
  * @since 2.1
- * @version 1.0.0
+ * @version 1.1.0
  * @ingroup io_interfaces
  * @{
  */