July 24, 2008 VIDEO 9

### NAME

video - interface between low and high level video drivers

### SYNOPSIS

```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.