1.\" $NetBSD: video.9,v 1.5 2009/03/12 12:37:18 joerg Exp $ 2.\" 3.\" Copyright (c) 2008 Patrick Mahoney 4.\" All rights reserved. 5.\" 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 17.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 18.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 20.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26.\" POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd July 24, 2008 29.Dt VIDEO 9 30.Os 31.Sh NAME 32.Nm video 33.Nd interface between low and high level video drivers 34.Sh SYNOPSIS 35.In dev/video_if.h 36.Ft device_t 37.Fn video_attach_mi "const struct video_hw_if *hw_if" "device_t hw_dev" 38.Ft void 39.Fn video_submit_payload "device_t vl_dev" "const struct video_payload *payload" 40.Sh DESCRIPTION 41The video device driver is divided into a high level, machine 42independent layer, and a low level hardware dependent layer. 43The interface between these is the 44.Fa video_hw_if 45structure function pointers called by the video layer, and video layer 46functions called by the hardware driver. 47.Pp 48The high level video driver attaches to the low level driver 49when the latter calls 50.Fa video_attach_mi . 51The 52.Fa video_hw_if 53struct is as shown below. 54.Fa dev 55is the device struct for the hardware device. 56Return value is the video layer device. 57.Bd -literal 58struct video_hw_if { 59 int (*open)(void *, int); /* open hardware */ 60 void (*close)(void *); /* close hardware */ 61 62 const char * (*get_devname)(void *); 63 64 int (*enum_format)(void *, uint32_t, struct video_format *); 65 int (*get_format)(void *, struct video_format *); 66 int (*set_format)(void *, struct video_format *); 67 int (*try_format)(void *, struct video_format *); 68 69 int (*start_transfer)(void *); 70 int (*stop_transfer)(void *); 71 72 int (*control_iter_init)(void *, struct video_control_iter *); 73 int (*control_iter_next)(void *, struct video_control_iter *); 74 int (*get_control_desc_group)(void *, 75 struct video_control_desc_group *); 76 int (*get_control_group)(void *, struct video_control_group *); 77 int (*set_control_group)(void *, const struct video_control_group *); 78}; 79.Ed 80.Pp 81The upper layer of the video driver allocates buffers for video 82samples. 83The hardware driver submits data to the video layer with 84.Fa video_submit_payload . 85.Fa vl_dev 86is the video layer device returned by 87.Fa video_attach_mi . 88.Bd -literal 89struct video_payload { 90 const uint8_t *data; 91 size_t size; 92 int frameno; 93 bool end_of_frame; 94}; 95.Ed 96.Bl -tag -width indent 97.It Fa data 98Pointer to the video data for this payload. 99This may only be a 100portion of the data in one video sample or frame. 101.It Fa size 102Size in bytes of the video data in this payload 103.It Fa frameno 104Frame number to which this payload belongs. 105The hardware driver must toggle the frame number between 0 and 1 106so the video layer can detect sample or frame boundaries. 107.It Fa end_of_frame 108Optional end of frame marker. 109If the hardware layer sets this, the 110video layer can immediately pass the completed sample or frame to 111userspace rather than waiting for the next payload to toggle 112.Fa frameno . 113.El 114.Sh HARDWARE-LAYER FUNCTIONS 115The fields of 116.Va video_hw_if 117are described in some more detail below. 118Some fields are optional and can be set to 119.Dv NULL 120if not needed. 121.Bl -tag -width indent 122.It Dv int open(void *hdl, int flags) 123optional, is called when the video device is opened. 124It should initialize the hardware for I/O. 125Every successful call to 126.Va open 127is matched by a call to 128.Va close . 129Return 0 on success, otherwise an error code. 130.It Dv void close(void *hdl) 131optional, is called when the audio device is closed. 132.It Dv const char * get_devname(void *hdl) 133mandatory, returns a NUL-terminated string naming the device, e.g. a 134vendor and product model name. 135.It Dv int enum_format(void *hdl, uint32_t index, struct video_format *format); 136mandatory, called with an 137.Va index 138from 0 to 139.Va max_index \- 1 . 140Fills 141.Va format 142with the format description at that index. 143Returns 0 on success, otherwise an error code. 144.It Dv int get_format(void *hdl, struct video_format *format) 145mandatory, fills 146.Va format 147with the current video format. 148There should be a default format so 149this function works before and streaming has begun. 150Returns 0 on success, otherwise an error code. 151.It Dv int set_format(void *hdl, struct video_format *format) 152mandatory, sets the format of the video stream based on 153.Va format . 154Fills 155.Va format 156with the actual format used which may not be the same as requested. 157Returns 0 on success, otherwise an error code. 158.It Dv int try_format(void *hdl, struct video_format *format) 159optional, like 160.Va set_format 161but does not actually change the stream format, just checks what is 162available. 163Returns 0 on success, otherwise an error code. 164.It Dv int start_transfer(void *hdl) 165mandatory, starts the capture of video frames. 166Incoming video data 167must be submitted to the video layer with repeated calls to 168.Fn video_submit_payload . 169.It Dv int stop_transfer(void *hdl) 170.It Dv int control_iter_init(void *hdl, struct video_control_iter *) 171Does nothing at this time. 172.It Dv int control_iter_next(void *hdl, struct video_control_iter *) 173Does nothing at this time. 174.It Dv int get_control_group(void *hdl, struct video_control_group *) 175.It Dv int set_control_group(void *hdl, struct video_control_group *) 176.El 177.Sh SEE ALSO 178.Xr video 4 179.Sh AUTHORS 180.An Patrick Mahoney Aq pat@polycrystal.org 181.Sh BUGS 182Incomplete. 183Only supports a single video capture stream. 184Does not support output streams. 185Format handling may change in the future. 186Control handling may change. 187Current design requires copying all incoming video data. 188