NAME
video —
interface between low and high
level video drivers
SYNOPSIS
#include <dev/video_if.h>
device_t
video_attach_mi(
const
struct video_hw_if *hw_if,
device_t hw_dev);
void
video_submit_payload(
device_t
vl_dev,
const struct
video_payload *payload);
DESCRIPTION
The video device driver is divided into a high level, machine independent layer,
and a low level hardware dependent layer. The interface between these is the
video_hw_if structure function pointers called by the
video layer, and video layer functions called by the hardware driver.
The high level video driver attaches to the low level driver when the latter
calls
video_attach_mi. The
video_hw_if struct is as shown below.
dev is the device struct for the hardware device. Return
value is the video layer device.
struct video_hw_if {
int (*open)(void *, int); /* open hardware */
void (*close)(void *); /* close hardware */
const char * (*get_devname)(void *);
int (*enum_format)(void *, uint32_t, struct video_format *);
int (*get_format)(void *, struct video_format *);
int (*set_format)(void *, struct video_format *);
int (*try_format)(void *, struct video_format *);
int (*start_transfer)(void *);
int (*stop_transfer)(void *);
int (*control_iter_init)(void *, struct video_control_iter *);
int (*control_iter_next)(void *, struct video_control_iter *);
int (*get_control_desc_group)(void *,
struct video_control_desc_group *);
int (*get_control_group)(void *, struct video_control_group *);
int (*set_control_group)(void *, const struct video_control_group *);
};
The upper layer of the video driver allocates buffers for video samples. The
hardware driver submits data to the video layer with
video_submit_payload.
vl_dev is
the video layer device returned by
video_attach_mi.
struct video_payload {
const uint8_t *data;
size_t size;
int frameno;
bool end_of_frame;
};
-
-
- data
- Pointer to the video data for this payload. This may only
be a portion of the data in one video sample or frame.
-
-
- size
- Size in bytes of the video data in this payload
-
-
- frameno
- Frame number to which this payload belongs. The hardware
driver must toggle the frame number between 0 and 1 so the video layer can
detect sample or frame boundaries.
-
-
- end_of_frame
- Optional end of frame marker. If the hardware layer sets
this, the video layer can immediately pass the completed sample or frame
to userspace rather than waiting for the next payload to toggle
frameno.
HARDWARE-LAYER FUNCTIONS
The fields of
video_hw_if are described in some more
detail below. Some fields are optional and can be set to
NULL
if not needed.
-
-
int
open(void *hdl, int flags)
- optional, is called when the video device is opened. It
should initialize the hardware for I/O. Every successful call to
open is matched by a call to
close. Return 0 on success, otherwise an error
code.
-
-
void
close(void *hdl)
- optional, is called when the audio device is closed.
-
-
const char *
get_devname(void *hdl)
- mandatory, returns a NUL-terminated string naming the
device, e.g. a vendor and product model name.
-
-
int
enum_format(void *hdl, uint32_t index, struct video_format
*format);
- mandatory, called with an index from
0 to max_index - 1. Fills
format with the format description at that index.
Returns 0 on success, otherwise an error code.
-
-
int
get_format(void *hdl, struct video_format *format)
- mandatory, fills format with the
current video format. There should be a default format so this function
works before and streaming has begun. Returns 0 on success, otherwise an
error code.
-
-
int
set_format(void *hdl, struct video_format *format)
- mandatory, sets the format of the video stream based on
format. Fills format with the
actual format used which may not be the same as requested. Returns 0 on
success, otherwise an error code.
-
-
int
try_format(void *hdl, struct video_format *format)
- optional, like set_format but does
not actually change the stream format, just checks what is available.
Returns 0 on success, otherwise an error code.
-
-
int
start_transfer(void *hdl)
- mandatory, starts the capture of video frames. Incoming
video data must be submitted to the video layer with repeated calls to
video_submit_payload().
-
-
int
stop_transfer(void *hdl)
-
int
control_iter_init(void *hdl, struct video_control_iter *)
- Does nothing at this time.
-
-
int
control_iter_next(void *hdl, struct video_control_iter *)
- Does nothing at this time.
-
-
int
get_control_group(void *hdl, struct video_control_group *)
-
int
set_control_group(void *hdl, struct video_control_group *)
-
SEE ALSO
video(4)
AUTHORS
Patrick Mahoney
<
pat@polycrystal.org>
BUGS
Incomplete. Only supports a single video capture stream. Does not support output
streams. Format handling may change in the future. Control handling may
change. Current design requires copying all incoming video data.