1.\" $NetBSD: video.4,v 1.11 2023/05/09 22:00:00 khorben 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. 47.Pp 48The device file for video operation is 49.Pa /dev/video . 50.Sh READING VIDEO SAMPLES 51Video data is separated into logical video samples which will 52typically be one complete video frame. 53With compressed formats, a video sample may be one logical chunk 54and not one complete frame depending on the compression format. 55Video samples may be read from 56.Pa /dev/video 57in one of several different modes. 58.Pp 59In read mode, calls to 60.Xr read 2 61will return at most the data of one video sample. 62If the entire sample is not read, then subsequent reads will return 63at most the remaining data in that video sample. 64.Pp 65Video samples may be mapped into memory with 66.Xr mmap 2 . 67The driver allocates internal buffers for a number of video samples 68which are mapped into memory. 69Initiating this mode requires several 70.Xr ioctl 2 71commands: 72.Dv VIDIOC_REQBUFS 73to request the driver reserve buffers, 74.Dv VIDIOC_QUERYBUF 75to query the details of each buffer, 76.Xr mmap 2 77to map each buffer into memory, 78.Dv VIDIOC_QBUF 79to queue the buffers for receiving video data, 80.Dv VIDIOC_STREAMON 81to begin streaming of video data, and 82.Dv VIDIOC_DQBUF 83to remove a filled buffer from the queue. 84At this point the video data from the dequeued buffer is valid. 85.Sh DEVICE CAPABILITIES 86.Bl -tag -width indent 87.It Dv VIDIOC_QUERYCAP (struct v4l2_capability) 88This command queries the capabilities of the device. 89The first three fields are informational NULL terminated strings 90filled by the driver: 91.Va driver 92describes the driver used by this device, 93.Va card 94describes the video capture card or camera, and 95.Va bus_info 96represents the bus to which the hardware device is attached. 97.Pp 98The 99.Va capabilities 100field contains a number of flags indicating various features supported 101by the driver or hardware: 102.Pp 103.Bl -tag -width indent 104.It Dv V4L2_CAP_VIDEO_CAPTURE 105support video capturing 106.It Dv V4L2_CAP_READWRITE 107supports the 108.Xr read 2 109and/or 110.Xr write 2 111mode 112.It Dv V4L2_CAP_STREAMING 113supports 114.Xr mmap 2 115mode 116.El 117.Bd -literal 118struct v4l2_capability { 119 uint8_t driver[16]; 120 uint8_t card[32]; 121 uint8_t bus_info[32]; 122 uint32_t version; 123 uint32_t capabilities; 124 uint32_t reserved[4]; 125}; 126.Ed 127.El 128.Sh STREAMING INTERFACE 129.Bl -tag -width indent 130.It Dv VIDIOC_REQBUFS (struct v4l2_requestbuffers) 131This command requests that the driver reserve space for 132.Va count 133samples. 134.Va type 135must be set to 136.Dv V4L2_BUF_TYPE_VIDEO_CAPTURE 137and 138.Va memory 139to 140.Dv V4L2_MEMORY_MMAP . 141The returned 142.Va count 143represents the actual number of samples reserved which may be more 144or fewer than requested. 145.Bd -literal 146struct v4l2_requestbuffers { 147 uint32_t count; 148 enum v4l2_buf_type type; 149 enum v4l2_memory memory; 150 uint32_t reserved[2]; 151}; 152.Ed 153.It Dv VIDIOC_QUERYBUF (struct v4l2_buffer) 154This command should be called for each buffer in 155.Va count 156above. 157The fields 158.Va index , 159.Va type , 160and 161.Va memory 162must be set to a valid index from 0 to 163.Va count-1 , 164and the same type and memory as used in 165.Dv VIDIOC_QUERYBUF . 166The driver returns 167.Va m.offset 168and 169.Va length . 170.Bd -literal 171struct v4l2_buffer { 172 uint32_t index; 173 enum v4l2_buf_type type; 174 uint32_t bytesused; 175 uint32_t flags; 176 enum v4l2_field field; 177 struct timeval timestamp; 178 struct v4l2_timecode timecode; 179 uint32_t sequence; 180 enum v4l2_memory memory; 181 union { 182 uint32_t offset; 183 unsigned long userptr; 184 } m; 185 uint32_t length; 186 uint32_t input; 187 uint32_t reserved; 188}; 189.Ed 190.It Xr mmap 2 191Each buffer must be mapped with a call to 192.Xr mmap 2 , 193passing the 194.Va length 195and 196.Va m.offset 197values obtained above. 198The prot 199.Dv PROT_READ|PROT_WRITE 200and flags 201.Dv MAP_SHARED 202are recommended. 203.It Dv VIDIOC_QBUF (struct v4l2_buffer) 204This command indicates to the driver that the buffer is ready to 205receive a video sample. 206The following fields must be set: 207.Va index , 208set to a valid buffer index from 0 to 209.Va count 210\- 1; 211.Va type , 212set to the same type used above; and 213.Va memory , 214set to the same memory used above. 215Each buffer should be queued with this command. 216Order is not important. 217.It Dv VIDIOC_STREAMON (int) 218This command starts streaming. 219Queued buffers will be filled with data. 220.Xr select 2 221will indicate that a buffer is done and available for reading. 222.It Dv VIDIOC_DQBUF (struct v4l2_buffer) 223This command dequeues an available buffer from the driver. 224If no buffer is available, it blocks until one is, unless 225.Dv O_NONBLOCK 226was specified to 227.Xr open 2 , 228in which case it returns 229.Er EAGAIN . 230.Xr select 2 , 231or 232.Xr poll 2 233prior to initiating any other mode will begin streaming of video for 234reading with 235.Xr read 2 . 236In this streaming mode 237.Xr select 2 238or 239.Xr poll 2 240indicate the availability of a video frame. 241Calls to 242.Xr read 2 243will return at most the video data of one video sample. 244If the entire sample is not read, then subsequent reads will return 245at most the remaining data in that video sample. 246.El 247.Sh FILES 248.Bl -tag -width /dev/video -compact 249.It Pa /dev/video 250.El 251.Sh SEE ALSO 252.Xr auvitek 4 , 253.Xr pseye 4 , 254.Xr uvideo 4 , 255.Xr video 9 256.Pp 257.Lk http://v4l2spec.bytesex.org/ "V4L2 API Specification" 258.Sh HISTORY 259The 260.Nm 261device driver first appeared in 262.Nx 5.0 . 263.Sh AUTHORS 264.An Patrick Mahoney Aq Mt pat@polycrystal.org 265.Sh BUGS 266Does not support the complete V4L2 API. 267Only supports the capture interface. 268Does not support writing, overlay, VBI, tuner, audio, radio, or 269asyncio. 270