Video Driver APIs, for use by the Video Subsystem. More...

Topics
	Video Controls
	Types used to access drivers video controls.
	Video Driver Backend API
	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.

Data Structures
struct	video_device
	Storage type for a wrapper type around a video device. 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).

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.

Detailed Description

Video Driver APIs, for use by the Video Subsystem.

Since: 2.1

Version: 1.3.0

Macro Definition Documentation

◆ VIDEO_MIPI_CSI2_DT_BLANKING

#define VIDEO_MIPI_CSI2_DT_BLANKING 0x11

#include <zephyr/drivers/video.h>

Blanking data - horizontal/vertical blanking information.

◆ VIDEO_MIPI_CSI2_DT_EMBEDDED_8

#define VIDEO_MIPI_CSI2_DT_EMBEDDED_8 0x12

#include <zephyr/drivers/video.h>

Embedded 8-bit data - sensor metadata or configuration data.

◆ VIDEO_MIPI_CSI2_DT_NULL

#define VIDEO_MIPI_CSI2_DT_NULL 0x10

#include <zephyr/drivers/video.h>

NULL data type - used for padding or synchronization.

◆ VIDEO_MIPI_CSI2_DT_RAW10

#define VIDEO_MIPI_CSI2_DT_RAW10 0x2b

#include <zephyr/drivers/video.h>

Raw sensor data with 10 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RAW12

#define VIDEO_MIPI_CSI2_DT_RAW12 0x2c

#include <zephyr/drivers/video.h>

Raw sensor data with 12 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RAW14

#define VIDEO_MIPI_CSI2_DT_RAW14 0x2d

#include <zephyr/drivers/video.h>

Raw sensor data with 14 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RAW6

#define VIDEO_MIPI_CSI2_DT_RAW6 0x28

#include <zephyr/drivers/video.h>

Raw sensor data with 6 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RAW7

#define VIDEO_MIPI_CSI2_DT_RAW7 0x29

#include <zephyr/drivers/video.h>

Raw sensor data with 7 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RAW8

#define VIDEO_MIPI_CSI2_DT_RAW8 0x2a

#include <zephyr/drivers/video.h>

Raw sensor data with 8 bits per pixel.

◆ VIDEO_MIPI_CSI2_DT_RGB444

#define VIDEO_MIPI_CSI2_DT_RGB444 0x20

#include <zephyr/drivers/video.h>

RGB format with 4 bits per color component.

◆ VIDEO_MIPI_CSI2_DT_RGB555

#define VIDEO_MIPI_CSI2_DT_RGB555 0x21

#include <zephyr/drivers/video.h>

RGB format with 5 bits per color component.

◆ VIDEO_MIPI_CSI2_DT_RGB565

#define VIDEO_MIPI_CSI2_DT_RGB565 0x22

#include <zephyr/drivers/video.h>

RGB format with 5-6-5 bits per R-G-B components.

◆ VIDEO_MIPI_CSI2_DT_RGB666

#define VIDEO_MIPI_CSI2_DT_RGB666 0x23

#include <zephyr/drivers/video.h>

RGB format with 6 bits per color component.

◆ VIDEO_MIPI_CSI2_DT_RGB888

#define VIDEO_MIPI_CSI2_DT_RGB888 0x24

#include <zephyr/drivers/video.h>

RGB format with 8 bits per color component.

◆ VIDEO_MIPI_CSI2_DT_USER

#define VIDEO_MIPI_CSI2_DT_USER ( n )

#include <zephyr/drivers/video.h>

Value:

(0x30 + (n))

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.

Note: Parameter n must be in range 0-7 to generate valid user-defined data types

Parameters

n	User-defined type index (0-7)

Returns: Data type value in user-defined range (0x30-0x37)

◆ VIDEO_MIPI_CSI2_DT_YUV420_10

#define VIDEO_MIPI_CSI2_DT_YUV420_10 0x19

#include <zephyr/drivers/video.h>

YUV 4:2:0 format with 10 bits per component.

◆ VIDEO_MIPI_CSI2_DT_YUV420_8

#define VIDEO_MIPI_CSI2_DT_YUV420_8 0x18

#include <zephyr/drivers/video.h>

YUV 4:2:0 format with 8 bits per component.

◆ VIDEO_MIPI_CSI2_DT_YUV420_CSPS_10

#define VIDEO_MIPI_CSI2_DT_YUV420_CSPS_10 0x1d

#include <zephyr/drivers/video.h>

YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 10-bit format.

◆ VIDEO_MIPI_CSI2_DT_YUV420_CSPS_8

#define VIDEO_MIPI_CSI2_DT_YUV420_CSPS_8 0x1c

#include <zephyr/drivers/video.h>

YUV 4:2:0 CSPS (Chroma Shifted Pixel Sampling) 8-bit format.

◆ VIDEO_MIPI_CSI2_DT_YUV422_10

#define VIDEO_MIPI_CSI2_DT_YUV422_10 0x1f

#include <zephyr/drivers/video.h>

YUV 4:2:2 format with 10 bits per component.

◆ VIDEO_MIPI_CSI2_DT_YUV422_8

#define VIDEO_MIPI_CSI2_DT_YUV422_8 0x1e

#include <zephyr/drivers/video.h>

YUV 4:2:2 format with 8 bits per component.

Function Documentation

◆ video_driver_dequeue()

int video_driver_dequeue	(	const struct device *	dev,
		struct video_buffer **	vbuf,
		k_timeout_t	timeout )

inlinestatic

#include <zephyr/drivers/video.h>

Dequeue a video buffer from a driver.

Dequeue a filled (capturing) or displayed (output) buffer from the driver’s endpoint outgoing queue.

Parameters

dev	Pointer to the device structure for the driver instance.
vbuf	Pointer a video buffer pointer.
timeout	Timeout

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_enqueue()

int video_driver_enqueue	(	const struct device *	dev,
		struct video_buffer *	vbuf )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
vbuf	Pointer to the video buffer.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_enum_frmival()

int video_driver_enum_frmival	(	const struct device *	dev,
		struct video_frmival_enum *	fie )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
fie	Pointer to a video frame interval enumeration struct.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_flush()

int video_driver_flush	(	const struct device *	dev,
		bool	cancel )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
cancel	If true, cancel buffer processing instead of waiting for completion.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_get_caps()

int video_driver_get_caps	(	const struct device *	dev,
		struct video_caps *	caps )

inlinestatic

#include <zephyr/drivers/video.h>

Get the capabilities of a video driver endpoint.

Parameters

dev	Pointer to the device structure for the driver instance.
caps	Pointer to the video_caps struct to fill.

Return values

0	on success
-ENOSYS	API is not implemented.

◆ video_driver_get_format()

int video_driver_get_format	(	const struct device *	dev,
		struct video_format *	fmt )

inlinestatic

#include <zephyr/drivers/video.h>

Get video format of a driver.

Get video device current video format.

Parameters

dev	Pointer to the device structure for the driver instance.
fmt	Pointer to video format struct.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_get_frmival()

int video_driver_get_frmival	(	const struct device *	dev,
		struct video_frmival *	frmival )

inlinestatic

#include <zephyr/drivers/video.h>

Get video frame interval of a driver.

Get current frame interval of the video device.

Parameters

dev	Pointer to the device structure for the driver instance.
frmival	Pointer to a video frame interval struct.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_get_selection()

int video_driver_get_selection	(	const struct device *	dev,
		struct video_selection *	sel )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
sel	Pointer to a video selection structure, `type` and `target` set by the caller

Return values

0	on success.
-ENOSYS	API is not implemented.
-ENOTSUP	Format is not supported.

◆ video_driver_get_volatile_ctrl()

int video_driver_get_volatile_ctrl	(	const struct device *	dev,
		uint32_t	cid )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure.
cid	Id of the control to set/get its value.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_set_ctrl()

int video_driver_set_ctrl	(	const struct device *	dev,
		uint32_t	cid )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure.
cid	Id of the control to set/get its value.

Return values

0	If successful
-ENOSYS	API is not implemented.

◆ video_driver_set_format()

int video_driver_set_format	(	const struct device *	dev,
		struct video_format *	fmt )

inlinestatic

#include <zephyr/drivers/video.h>

Set video format of a driver.

Configure video device with a specific format.

Parameters

dev	Pointer to the device structure for the driver instance.
fmt	Pointer to a video format struct.

Return values

0	on success.
-ENOTSUP	Format is not supported.
-ENOSYS	API is not implemented.

◆ video_driver_set_frmival()

int video_driver_set_frmival	(	const struct device *	dev,
		struct video_frmival *	frmival )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
frmival	Pointer to a video frame interval struct.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_set_selection()

int video_driver_set_selection	(	const struct device *	dev,
		struct video_selection *	sel )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
sel	Pointer to a video selection structure

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_set_signal()

int video_driver_set_signal	(	const struct device *	dev,
		struct k_poll_signal *	sig )

inlinestatic

#include <zephyr/drivers/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.

Parameters

dev	Pointer to the device structure for the driver instance.
sig	Pointer to k_poll_signal

Return values

0	on success
-ENOSYS	API is not implemented.

◆ video_driver_set_stream()

int video_driver_set_stream	(	const struct device *	dev,
		bool	enable,
		enum video_buf_type	type )

inlinestatic

#include <zephyr/drivers/video.h>

Start or stop the video driver function.

Start (enable == true) or stop (enable == false) streaming on the video device.

Parameters

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.

Return values

0	on success.
-ENOSYS	API is not implemented.

◆ video_driver_transform_cap()

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 )

inlinestatic

#include <zephyr/drivers/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.

Parameters

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.

Return values

0	on success.
-ENOSYS	API is not implemented.
-ENOTSUP	The transformation is not supported.

◆ video_find_vdev()

struct video_device * video_find_vdev ( const struct device * dev )

#include <zephyr/drivers/video.h>

Find the video_device associated with a video device.

Parameters

dev	Device that will be looked up in the global list of video devices.

Returns: Pointer to the video_device if found.

Return values

NULL	if not found.

◆ video_mipi_data_type()

uint8_t video_mipi_data_type ( uint32_t pixfmt )

inlinestatic

#include <zephyr/drivers/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.

Parameters

pixfmt Pixel format to convert

Return values

the	matching MIPI data type if found
VIDEO_MIPI_CSI2_DT_NULL	when the format has no known MIPI data type equivalent

Topics

Files

Data Structures

Functions

MIPI CSI-2 Data Types

Detailed Description

Macro Definition Documentation

◆ VIDEO_MIPI_CSI2_DT_BLANKING

◆ VIDEO_MIPI_CSI2_DT_EMBEDDED_8

◆ VIDEO_MIPI_CSI2_DT_NULL

◆ VIDEO_MIPI_CSI2_DT_RAW10

◆ VIDEO_MIPI_CSI2_DT_RAW12

◆ VIDEO_MIPI_CSI2_DT_RAW14

◆ VIDEO_MIPI_CSI2_DT_RAW6

◆ VIDEO_MIPI_CSI2_DT_RAW7

◆ VIDEO_MIPI_CSI2_DT_RAW8

◆ VIDEO_MIPI_CSI2_DT_RGB444

◆ VIDEO_MIPI_CSI2_DT_RGB555

◆ VIDEO_MIPI_CSI2_DT_RGB565

◆ VIDEO_MIPI_CSI2_DT_RGB666

◆ VIDEO_MIPI_CSI2_DT_RGB888

◆ VIDEO_MIPI_CSI2_DT_USER

◆ VIDEO_MIPI_CSI2_DT_YUV420_10

◆ VIDEO_MIPI_CSI2_DT_YUV420_8

◆ VIDEO_MIPI_CSI2_DT_YUV420_CSPS_10

◆ VIDEO_MIPI_CSI2_DT_YUV420_CSPS_8

◆ VIDEO_MIPI_CSI2_DT_YUV422_10

◆ VIDEO_MIPI_CSI2_DT_YUV422_8

Function Documentation

◆ video_driver_dequeue()

◆ video_driver_enqueue()

◆ video_driver_enum_frmival()

◆ video_driver_flush()

◆ video_driver_get_caps()

◆ video_driver_get_format()

◆ video_driver_get_frmival()

◆ video_driver_get_selection()

◆ video_driver_get_volatile_ctrl()

◆ video_driver_set_ctrl()

◆ video_driver_set_format()

◆ video_driver_set_frmival()

◆ video_driver_set_selection()

◆ video_driver_set_signal()

◆ video_driver_set_stream()

◆ video_driver_transform_cap()

◆ video_find_vdev()

◆ video_mipi_data_type()