1.\" $NetBSD: video.4,v 1.7 2011/03/06 00:39:11 jmcneill Exp $ 2.\" 3.\" Copyright (c) 2008 Patrick Mahoney 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd March 5, 2011 28.Dt VIDEO 4 29.Os 30.Sh NAME 31.Nm video 32.Nd device-independent video driver layer 33.Sh SYNOPSIS 34.In sys/videoio.h 35.Sh DESCRIPTION 36The 37.Nm 38driver provides support for various video peripherals. 39It provides a uniform programming interface layer above different 40underlying video hardware drivers. 41The video layer provides a 42.Tn Video4Linux2 43compatible API. 44A number of 45.Xr ioctl 2 46commands are supported controlling the device. 47See 48.Pa http://v4l2spec.bytesex.org/ 49for the official V4L2 specification. 50.Pp 51The device file for video operation is 52.Pa /dev/video . 53.Sh READING VIDEO SAMPLES 54Video data is separated into logical video samples which will 55typically be one complete video frame. 56With compressed formats, a video sample may be one logical chunk 57and not one complete frame depending on the compression format. 58Video samples may be read from 59.Pa /dev/video 60in one of several different modes. 61.Pp 62In read mode, calls to 63.Xr read 2 64will return at most the data of one video sample. 65If the entire sample is not read, then subsequent reads will return 66at most the remaining data in that video sample. 67.Pp 68Video samples may be mapped into memory with 69.Xr mmap 2 . 70The driver allocates internal buffers for a number of video samples 71which are mapped into memory. 72Initiating this mode requires several 73.Xr ioctl 2 74commands: 75.Dv VIDIOC_REQBUFS 76to request the driver reserve buffers, 77.Dv VIDIOC_QUERYBUF 78to query the details of each buffer, 79.Xr mmap 2 80to map each buffer into memory, 81.Dv VIDIOC_QBUF 82to queue the buffers for receiving video data, 83.Dv VIDIOC_STREAMON 84to begin streaming of video data, and 85.Dv VIDIOC_DQBUF 86to remove a filled buffer from the queue. 87At this point the video data from the dequeued buffer is valid. 88.Sh DEVICE CAPABILITIES 89.Bl -tag -width indent 90.It Dv VIDIOC_QUERYCAP (struct v4l2_capability) 91This command queries the capabilities of the device. 92The first three fields are informational NULL terminated strings 93filled by the driver: 94.Va driver 95describes the driver used by this device, 96.Va card 97describes the video capture card or camera, and 98.Va buf_info 99represents the bus to which the hardware device is attached. 100.Pp 101The 102.Va capabilities 103field contains a number of flags indicating various features supported 104by the driver or hardware: 105.Pp 106.Bl -tag -width indent 107.It Dv V4L2_CAP_VIDEO_CAPTURE 108support video capturing 109.It Dv V4L2_CAP_READWRITE 110supports the 111.Xr read 2 112and/or 113.Xr write 2 114mode 115.It Dv V4L2_CAP_STREAMING 116supports 117.Xr mmap 2 118mode 119.El 120.Bd -literal 121struct v4l2_capability { 122 uint8_t driver[16]; 123 uint8_t card[32]; 124 uint8_t bus_info[32]; 125 uint32_t version; 126 uint32_t capabilities; 127 uint32_t reserved[4]; 128}; 129.Ed 130.El 131.Sh STREAMING INTERFACE 132.Bl -tag -width indent 133.It Dv VIDIOC_REQBUFS (struct v4l2_requestbuffers) 134This command requests that the driver reserve space for 135.Va count 136samples. 137.Va type 138must be set to 139.Dv V4L2_BUF_TYPE_VIDEO_CAPTURE 140and 141.Va memory 142to 143.Dv V4L2_MEMORY_MMAP . 144The returned 145.Va count 146represents the actual number of samples reserved which may be more 147or fewer than requested. 148.Bd -literal 149struct v4l2_requestbuffers { 150 uint32_t count; 151 enum v4l2_buf_type type; 152 enum v4l2_memory memory; 153 uint32_t reserved[2]; 154}; 155.Ed 156.It Dv VIDIOC_QUERYBUF (struct v4l2_buffer) 157This command should be called for each buffer in 158.Va count 159above. 160The fields 161.Va index , 162.Va type , 163and 164.Va memory 165must be set to a valid index from 0 to 166.Va count-1 , 167and the same type and memory as used in 168.Dv VIDIOC_QUERYBUF . 169The driver returns 170.Va m.offset 171and 172.Va length . 173.Bd -literal 174struct v4l2_buffer { 175 uint32_t index; 176 enum v4l2_buf_type type; 177 uint32_t bytesused; 178 uint32_t flags; 179 enum v4l2_field field; 180 struct timeval timestamp; 181 struct v4l2_timecode timecode; 182 uint32_t sequence; 183 enum v4l2_memory memory; 184 union { 185 uint32_t offset; 186 unsigned long userptr; 187 } m; 188 uint32_t length; 189 uint32_t input; 190 uint32_t reserved; 191}; 192.Ed 193.It Xr mmap 2 194Each buffer must be mapped with a call to 195.Xr mmap 2 , 196passing the 197.Va length 198and 199.Va m.offset 200values obtained above. 201The prot 202.Dv PROT_READ|PROT_WRITE 203and flags 204.Dv MAP_SHARED 205are recommended. 206.It Dv VIDIOC_QBUF (struct v4l2_buffer) 207This command indicates to the driver that the buffer is ready to 208receive a video sample. 209The following fields must be set: 210.Va index , 211set to a valid buffer index from 0 to 212.Va count 213\- 1; 214.Va type , 215set to the same type used above; and 216.Va memory , 217set to the same memory used above. 218Each buffer should be queued with this command. 219Order is not important. 220.It Dv VIDIOC_STREAMON (int) 221This command starts streaming. 222Queued buffers will be filled with data. 223.Xr select 2 224will indicate that a buffer is done and available for reading. 225.It Dv VIDIOC_DQBUF (struct v4l2_buffer) 226This command dequeues an available buffer from the driver. 227If no buffer is available, it blocks until one is, unless 228.Dv O_NONBLOCK 229was specified to 230.Xr open 2 , 231in which case it returns 232.Er EAGAIN . 233.Xr select 2 , 234or 235.Xr poll 2 236prior to initiating any other mode will begin streaming of video for 237reading with 238.Xr read 2 . 239In this streaming mode 240.Xr select 2 241or 242.Xr poll 2 243indicate the availability of a video frame. 244Calls to 245.Xr read 2 246will return at most the video data of one video sample. 247If the entire sample is not read, then subsequent reads will return 248at most the remaining data in that video sample. 249.El 250.Sh FILES 251.Bl -tag -width /dev/video -compact 252.It Pa /dev/video 253.El 254.Sh SEE ALSO 255.Xr auvitek 4 , 256.Xr pseye 4 , 257.Xr uvideo 4 , 258.Xr video 9 259.Sh HISTORY 260The 261.Nm 262device driver first appeared in 263.Nx 5.0 . 264.Sh AUTHORS 265.An Patrick Mahoney Aq pat@polycrystal.org 266.Sh BUGS 267Does not support the complete V4L2 API. 268Only supports the capture interface. 269Does not support writing, overlay, VBI, tuner, audio, radio, or 270asyncio. 271