|
Zephyr Project API 4.4.99
A Scalable Open Source RTOS
|
Video Driver APIs, for use by the Video Subsystem. More...
Topics | |
| Video Controls | |
| Types used to access drivers video controls. | |
| Video interface bus types | |
Bus type values for the devicetree bus-type property. | |
Files | |
| file | video.h |
| Main header file for video driver API. | |
| file | arducam_mega.h |
| Copyright (c) 2023 Arducam Technology Co., Ltd. | |
| file | stm32_dcmi.h |
| STM32 DCMI specific controls. | |
Data Structures | |
| struct | video_device |
| Storage type for a wrapper type around a video device. More... | |
| struct | video_driver_api |
| @driver_ops{Video} More... | |
Functions | |
| struct video_device * | video_find_vdev (const struct device *dev) |
| Find the video_device associated with a video device. | |
| static int | video_driver_set_format (const struct device *dev, struct video_format *fmt) |
| Set video format of a driver. | |
| static int | video_driver_get_format (const struct device *dev, struct video_format *fmt) |
| Get video format of a driver. | |
| static int | video_driver_set_frmival (const struct device *dev, struct video_frmival *frmival) |
| Apply a video frame interval to a driver. | |
| static int | video_driver_get_frmival (const struct device *dev, struct video_frmival *frmival) |
| Get video frame interval of a driver. | |
| static int | video_driver_enum_frmival (const struct device *dev, struct video_frmival_enum *fie) |
| List video frame intervals. | |
| static int | video_driver_enqueue (const struct device *dev, struct video_buffer *vbuf) |
| Pass a video buffer to a driver. | |
| static int | video_driver_dequeue (const struct device *dev, struct video_buffer **vbuf, k_timeout_t timeout) |
| Dequeue a video buffer from a driver. | |
| static int | video_driver_flush (const struct device *dev, bool cancel) |
| Flush endpoint buffers from a driver. | |
| static int | video_driver_set_stream (const struct device *dev, bool enable, enum video_buf_type type) |
| Start or stop the video driver function. | |
| static int | video_driver_get_volatile_ctrl (const struct device *dev, uint32_t cid) |
| Get a volatile video control value of a driver. | |
| static int | video_driver_set_ctrl (const struct device *dev, uint32_t cid) |
| Set a video control value of a driver. | |
| static int | video_driver_get_caps (const struct device *dev, struct video_caps *caps) |
| Get the capabilities of a video driver endpoint. | |
| static int | video_driver_transform_cap (const struct device *const dev, const struct video_format_cap *const cap, struct video_format_cap *const res_cap, enum video_buf_type type, uint16_t ind) |
| Transform a video format capability from one end to the other end of a m2m video device. | |
| static int | video_driver_set_signal (const struct device *dev, struct k_poll_signal *sig) |
| Register/Unregister k_poll signal for a video endpoint. | |
| static int | video_driver_set_selection (const struct device *dev, struct video_selection *sel) |
| Set video selection (crop/compose). | |
| static int | video_driver_get_selection (const struct device *dev, struct video_selection *sel) |
| Get video selection (crop/compose). | |
| typedef int(* | video_api_format_t) (const struct device *dev, struct video_format *fmt) |
| @def_driverbackendgroup{Video,video_interface} | |
| typedef int(* | video_api_frmival_t) (const struct device *dev, struct video_frmival *frmival) |
| Callback API to set or get video frame interval. | |
| typedef int(* | video_api_enum_frmival_t) (const struct device *dev, struct video_frmival_enum *fie) |
| Callback API to enumerate supported frame intervals for a format. | |
| typedef int(* | video_api_enqueue_t) (const struct device *dev, struct video_buffer *buf) |
| Callback API to enqueue a buffer in the driver incoming queue. | |
| typedef int(* | video_api_dequeue_t) (const struct device *dev, struct video_buffer **buf, k_timeout_t timeout) |
| Callback API to dequeue a buffer from the driver outgoing queue. | |
| typedef int(* | video_api_flush_t) (const struct device *dev, bool cancel) |
| Callback API to flush endpoint buffers. | |
| typedef int(* | video_api_set_stream_t) (const struct device *dev, bool enable, enum video_buf_type type) |
| Callback API to control stream status. | |
| typedef int(* | video_api_ctrl_t) (const struct device *dev, uint32_t cid) |
| Callback API to set or get a video control value. | |
| typedef int(* | video_api_get_caps_t) (const struct device *dev, struct video_caps *caps) |
| Callback API to get capabilities of a video endpoint. | |
| typedef int(* | video_api_transform_cap_t) (const struct device *const dev, const struct video_format_cap *const cap, struct video_format_cap *const res_cap, enum video_buf_type type, uint16_t ind) |
| Callback API to transform a format capability across m2m device endpoints. | |
| typedef int(* | video_api_set_signal_t) (const struct device *dev, struct k_poll_signal *sig) |
| Callback API to register or unregister poll signal for buffer events. | |
| typedef int(* | video_api_selection_t) (const struct device *dev, struct video_selection *sel) |
| Callback API to set or get video selection (crop/compose). | |
MIPI CSI-2 Data Types | |
Standard MIPI CSI-2 data type identifiers for camera sensor interfaces These constants define the data type field values used in MIPI CSI-2 packet headers to identify the format and encoding of transmitted image data. The data type field is 6 bits wide, allowing values from 0x00 to 0x3F. | |
| static uint8_t | video_mipi_data_type (uint32_t pixfmt) |
| Map pixel formats to their MIPI data type equivalent. | |
| #define | VIDEO_MIPI_CSI2_DT_NULL 0x10 |
| NULL data type - used for padding or synchronization. | |
| #define | VIDEO_MIPI_CSI2_DT_BLANKING 0x11 |
| Blanking data - horizontal/vertical blanking information. | |
| #define | VIDEO_MIPI_CSI2_DT_EMBEDDED_8 0x12 |
| Embedded 8-bit data - sensor metadata or configuration data. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV420_8 0x18 |
| YUV 4:2:0 format with 8 bits per component. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV420_10 0x19 |
| YUV 4:2:0 format with 10 bits per component. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV420_CSPS_8 0x1c |
| YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 8-bit format. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV420_CSPS_10 0x1d |
| YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 10-bit format. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV422_8 0x1e |
| YUV 4:2:2 format with 8 bits per component. | |
| #define | VIDEO_MIPI_CSI2_DT_YUV422_10 0x1f |
| YUV 4:2:2 format with 10 bits per component. | |
| #define | VIDEO_MIPI_CSI2_DT_RGB444 0x20 |
| RGB format with 4 bits per color component. | |
| #define | VIDEO_MIPI_CSI2_DT_RGB555 0x21 |
| RGB format with 5 bits per color component. | |
| #define | VIDEO_MIPI_CSI2_DT_RGB565 0x22 |
| RGB format with 5-6-5 bits per R-G-B components. | |
| #define | VIDEO_MIPI_CSI2_DT_RGB666 0x23 |
| RGB format with 6 bits per color component. | |
| #define | VIDEO_MIPI_CSI2_DT_RGB888 0x24 |
| RGB format with 8 bits per color component. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW6 0x28 |
| Raw sensor data with 6 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW7 0x29 |
| Raw sensor data with 7 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW8 0x2a |
| Raw sensor data with 8 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW10 0x2b |
| Raw sensor data with 10 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW12 0x2c |
| Raw sensor data with 12 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_RAW14 0x2d |
| Raw sensor data with 14 bits per pixel. | |
| #define | VIDEO_MIPI_CSI2_DT_USER(n) |
| User-defined data type generator macro. | |
| #define VIDEO_MIPI_CSI2_DT_BLANKING 0x11 |
#include <video.h>
Blanking data - horizontal/vertical blanking information.
| #define VIDEO_MIPI_CSI2_DT_EMBEDDED_8 0x12 |
#include <video.h>
Embedded 8-bit data - sensor metadata or configuration data.
| #define VIDEO_MIPI_CSI2_DT_NULL 0x10 |
#include <video.h>
NULL data type - used for padding or synchronization.
| #define VIDEO_MIPI_CSI2_DT_RAW10 0x2b |
#include <video.h>
Raw sensor data with 10 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RAW12 0x2c |
#include <video.h>
Raw sensor data with 12 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RAW14 0x2d |
#include <video.h>
Raw sensor data with 14 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RAW6 0x28 |
#include <video.h>
Raw sensor data with 6 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RAW7 0x29 |
#include <video.h>
Raw sensor data with 7 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RAW8 0x2a |
#include <video.h>
Raw sensor data with 8 bits per pixel.
| #define VIDEO_MIPI_CSI2_DT_RGB444 0x20 |
#include <video.h>
RGB format with 4 bits per color component.
| #define VIDEO_MIPI_CSI2_DT_RGB555 0x21 |
#include <video.h>
RGB format with 5 bits per color component.
| #define VIDEO_MIPI_CSI2_DT_RGB565 0x22 |
#include <video.h>
RGB format with 5-6-5 bits per R-G-B components.
| #define VIDEO_MIPI_CSI2_DT_RGB666 0x23 |
#include <video.h>
RGB format with 6 bits per color component.
| #define VIDEO_MIPI_CSI2_DT_RGB888 0x24 |
#include <video.h>
RGB format with 8 bits per color component.
| #define VIDEO_MIPI_CSI2_DT_USER | ( | n | ) |
#include <video.h>
User-defined data type generator macro.
Generates user-defined data type identifier for custom or proprietary formats. The MIPI CSI-2 specification reserves data types 0x30 to 0x37 for user-specific implementations.
| n | User-defined type index (0-7) |
| #define VIDEO_MIPI_CSI2_DT_YUV420_10 0x19 |
#include <video.h>
YUV 4:2:0 format with 10 bits per component.
| #define VIDEO_MIPI_CSI2_DT_YUV420_8 0x18 |
#include <video.h>
YUV 4:2:0 format with 8 bits per component.
| #define VIDEO_MIPI_CSI2_DT_YUV420_CSPS_10 0x1d |
#include <video.h>
YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 10-bit format.
| #define VIDEO_MIPI_CSI2_DT_YUV420_CSPS_8 0x1c |
#include <video.h>
YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 8-bit format.
| #define VIDEO_MIPI_CSI2_DT_YUV422_10 0x1f |
#include <video.h>
YUV 4:2:2 format with 10 bits per component.
| #define VIDEO_MIPI_CSI2_DT_YUV422_8 0x1e |
#include <video.h>
YUV 4:2:2 format with 8 bits per component.
#include <video.h>
Callback API to set or get a video control value.
See video_driver_set_ctrl() and video_driver_get_volatile_ctrl() for argument description.
| typedef int(* video_api_dequeue_t) (const struct device *dev, struct video_buffer **buf, k_timeout_t timeout) |
#include <video.h>
Callback API to dequeue a buffer from the driver outgoing queue.
See video_driver_dequeue() for argument description.
| typedef int(* video_api_enqueue_t) (const struct device *dev, struct video_buffer *buf) |
#include <video.h>
Callback API to enqueue a buffer in the driver incoming queue.
See video_driver_enqueue() for argument description.
| typedef int(* video_api_enum_frmival_t) (const struct device *dev, struct video_frmival_enum *fie) |
#include <video.h>
Callback API to enumerate supported frame intervals for a format.
See video_driver_enum_frmival() for argument description.
#include <video.h>
Callback API to flush endpoint buffers.
See video_driver_flush() for argument description.
| typedef int(* video_api_format_t) (const struct device *dev, struct video_format *fmt) |
#include <video.h>
@def_driverbackendgroup{Video,video_interface}
Callback API to set or get video format. See video_driver_set_format() and video_driver_get_format() for argument description.
| typedef int(* video_api_frmival_t) (const struct device *dev, struct video_frmival *frmival) |
#include <video.h>
Callback API to set or get video frame interval.
See video_driver_set_frmival() and video_driver_get_frmival() for argument description.
| typedef int(* video_api_get_caps_t) (const struct device *dev, struct video_caps *caps) |
#include <video.h>
Callback API to get capabilities of a video endpoint.
See video_get_caps() for argument description.
| typedef int(* video_api_selection_t) (const struct device *dev, struct video_selection *sel) |
#include <video.h>
Callback API to set or get video selection (crop/compose).
See video_driver_set_selection() and video_driver_get_selection() for argument description.
| typedef int(* video_api_set_signal_t) (const struct device *dev, struct k_poll_signal *sig) |
#include <video.h>
Callback API to register or unregister poll signal for buffer events.
See video_set_signal() for argument description.
| typedef int(* video_api_set_stream_t) (const struct device *dev, bool enable, enum video_buf_type type) |
#include <video.h>
Callback API to control stream status.
See video_driver_set_stream() for argument description.
| typedef int(* video_api_transform_cap_t) (const struct device *const dev, const struct video_format_cap *const cap, struct video_format_cap *const res_cap, enum video_buf_type type, uint16_t ind) |
#include <video.h>
Callback API to transform a format capability across m2m device endpoints.
See video_transform_cap() for argument description.
|
inlinestatic |
#include <video.h>
Dequeue a video buffer from a driver.
Dequeue a filled (capturing) or displayed (output) buffer from the driver’s endpoint outgoing queue.
| dev | Pointer to the device structure for the driver instance. |
| vbuf | Pointer a video buffer pointer. |
| timeout | Timeout |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Pass a video buffer to a driver.
Enqueue an empty (capturing) or filled (output) video buffer in the driver’s endpoint incoming queue.
| dev | Pointer to the device structure for the driver instance. |
| vbuf | Pointer to the video buffer. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
List video frame intervals.
List all supported video frame intervals of a given format.
Callers should fill the pixelformat, width and height fields of video_frmival_enum first to form a query. Then, the index field is used to iterate through the supported frame intervals list.
| dev | Pointer to the device structure for the driver instance. |
| fie | Pointer to a video frame interval enumeration struct. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
#include <video.h>
Flush endpoint buffers from a driver.
A call to flush finishes when all endpoint buffers have been moved from incoming queue to outgoing queue. Either because canceled or fully processed through the video function.
| dev | Pointer to the device structure for the driver instance. |
| cancel | If true, cancel buffer processing instead of waiting for completion. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Get the capabilities of a video driver endpoint.
| dev | Pointer to the device structure for the driver instance. |
| caps | Pointer to the video_caps struct to fill. |
| 0 | on success |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Get video format of a driver.
Get video device current video format.
| dev | Pointer to the device structure for the driver instance. |
| fmt | Pointer to video format struct. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Get video frame interval of a driver.
Get current frame interval of the video device.
| dev | Pointer to the device structure for the driver instance. |
| frmival | Pointer to a video frame interval struct. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Get video selection (crop/compose).
Retrieve the current settings related to the crop and compose of the video device. This can also be used to read the native size of the input stream of the video device. This function can be used to read crop / compose capabilities of the device prior to performing configuration via the video_set_selection api.
| dev | Pointer to the device structure for the driver instance. |
| sel | Pointer to a video selection structure, type and target set by the caller |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
| -ENOTSUP | Format is not supported. |
#include <video.h>
Get a volatile video control value of a driver.
Update the control value of cid by requesting it from the hardware. After this, the matching ctrl->val contains the updated value.
| dev | Pointer to the device structure. |
| cid | Id of the control to set/get its value. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
#include <video.h>
Set a video control value of a driver.
Apply a video control value of cid to a device. The value is taken from the matching ctrl->val.
| dev | Pointer to the device structure. |
| cid | Id of the control to set/get its value. |
| 0 | If successful |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Set video format of a driver.
Configure video device with a specific format.
| dev | Pointer to the device structure for the driver instance. |
| fmt | Pointer to a video format struct. |
| 0 | on success. |
| -ENOTSUP | Format is not supported. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Apply a video frame interval to a driver.
Drivers must not return an error solely because the requested interval doesn’t match the device capabilities. They must instead modify the interval to match what the hardware can provide.
| dev | Pointer to the device structure for the driver instance. |
| frmival | Pointer to a video frame interval struct. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Set video selection (crop/compose).
Configure the optional crop and compose feature of a video device. Crop is first applied on the input frame, and the result of that crop is applied to the compose. The result of the compose (width/height) is equal to the format width/height given to the video_set_format function.
Some targets are inter-dependents. For instance, setting a VIDEO_SEL_TGT_CROP will reset VIDEO_SEL_TGT_COMPOSE to the same size.
| dev | Pointer to the device structure for the driver instance. |
| sel | Pointer to a video selection structure |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Register/Unregister k_poll signal for a video endpoint.
Register a poll signal to the endpoint, which will be signaled on frame completion (done, aborted, error). Registering a NULL poll signal unregisters any previously registered signal.
| dev | Pointer to the device structure for the driver instance. |
| sig | Pointer to k_poll_signal |
| 0 | on success |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Start or stop the video driver function.
Start (enable == true) or stop (enable == false) streaming on the video device.
| dev | Pointer to the device structure. |
| enable | If true, start streaming, otherwise stop streaming. |
| type | The type of the buffers stream to start or stop. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
|
inlinestatic |
#include <video.h>
Transform a video format capability from one end to the other end of a m2m video device.
See video_transform_cap for detailed description and usage.
| dev | Pointer to the device structure. |
| cap | Pointer to the source video format capability structure. |
| res_cap | Pointer to the resulting video format capability structure, filled by the driver. |
| type | The video_buf_type of the resulting transformed cap. |
| ind | Index of the resulting transformed cap. |
| 0 | on success. |
| -ENOSYS | API is not implemented. |
| -ENOTSUP | The transformation is not supported. |
| struct video_device * video_find_vdev | ( | const struct device * | dev | ) |
#include <video.h>
Find the video_device associated with a video device.
| dev | Device that will be looked up in the global list of video devices. |
| NULL | if not found. |
#include <video.h>
Map pixel formats to their MIPI data type equivalent.
Only the formats that were an exact match are mapped to equivalent MIPI data types. A driver might want to handle the non-standard types before calling this function.
Mind that while most receivers store VIDEO_MIPI_CSI2_DT_YUV422_8 as YUYV, it is effectively the UYVY format being sent over MIPI lanes.
| pixfmt | Pixel format to convert |
| the | matching MIPI data type if found |
| VIDEO_MIPI_CSI2_DT_NULL | when the format has no known MIPI data type equivalent |