1.\" $OpenBSD: video.4,v 1.16 2016/05/30 17:59:11 mglocker Exp $ 2.\" 3.\" Copyright (c) 2008 Marcus Glocker <mglocker@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 30 2016 $ 18.Dt VIDEO 4 19.Os 20.Sh NAME 21.Nm video 22.Nd device-independent video driver layer 23.Sh SYNOPSIS 24.Cd "video* at uvideo?" 25.Pp 26.In sys/types.h 27.In sys/ioctl.h 28.In sys/videoio.h 29.Sh DESCRIPTION 30The 31.Nm 32driver provides support for various video devices. 33It provides a uniform programming interface layer 34above different underlying video hardware drivers. 35The 36.Nm 37driver uses the V4L2 (Video for Linux Two) API which is widely used by video 38applications. 39Therefore this document mainly describes the V4L2 API parts 40which are supported by the 41.Nm 42driver. 43.Sh IOCTLS 44The following 45.Xr ioctl 2 46commands are supported: 47.Bl -tag -width Ds 48.It Dv VIDIOC_QUERYCAP Fa "struct v4l2_capability *" 49Query device capabilities. 50.Bd -literal 51struct v4l2_capability { 52 u_int8_t driver[16]; 53 u_int8_t card[32]; 54 u_int8_t bus_info[32]; 55 u_int32_t version; 56 u_int32_t capabilities; 57 u_int32_t device_caps; 58 u_int32_t reserved[3]; 59}; 60.Ed 61.It Dv VIDIOC_ENUM_FMT Fa "struct v4l2_fmtdesc *" 62Enumerate image formats. 63.Bd -literal 64struct v4l2_fmtdesc { 65 u_int32_t index; 66 u_int32_t type; 67 u_int32_t flags; 68 u_int8_t description[32]; 69 u_int32_t pixelformat; 70 u_int32_t reserved[4]; 71}; 72.Ed 73.It Dv VIDIOC_S_FMT Fa "struct v4l2_format *" 74Set the data format. 75.Bd -literal 76struct v4l2_format { 77 u_int32_t type; 78 union { 79 struct v4l2_pix_format pix; 80 struct v4l2_pix_format_mplane pix_mp; 81 struct v4l2_window win; 82 struct v4l2_vbi_format vbi; 83 struct v4l2_sliced_vbi_format sliced; 84 struct v4l2_sdr_format sdr; 85 u_int8_t raw_data[200]; 86 } fmt; 87}; 88.Ed 89.It Dv VIDIOC_G_FMT Fa "struct v4l2_format *" 90Get the data format. 91.Pp 92Same structure as for 93.Dv VIDIOC_S_FMT . 94.It Dv VIDIOC_ENUMINPUT Fa "struct v4l2_input *" 95Enumerate video inputs. 96.Bd -literal 97struct v4l2_input { 98 u_int32_t index; 99 u_int8_t name[32]; 100 u_int32_t type; 101 u_int32_t audioset; 102 u_int32_t tuner; 103 v4l2_std_id std; 104 u_int32_t status; 105 u_int32_t capabilities; 106 u_int32_t reserved[3]; 107}; 108.Ed 109.It Dv VIDIOC_G_INPUT Fa "int *" 110Get the current video input. 111.It Dv VIDIOC_S_INPUT Fa "int *" 112Select the current video input. 113.It Dv VIDIOC_REQBUFS Fa "struct v4l2_requestbuffers *" 114Initiate memory mapping or user pointer I/O. 115.Bd -literal 116struct v4l2_requestbuffers { 117 u_int32_t count; 118 u_int32_t type; 119 u_int32_t memory; 120 u_int32_t reserved[2]; 121}; 122.Ed 123.It Dv VIDIOC_QUERYBUF Fa "struct v4l2_buffer *" 124Query the status of a buffer. 125.Bd -literal 126struct v4l2_buffer { 127 u_int32_t index; 128 u_int32_t type; 129 u_int32_t bytesused; 130 u_int32_t flags; 131 u_int32_t field; 132 struct timeval timestamp; 133 struct v4l2_timecode timecode; 134 u_int32_t sequence; 135 u_int32_t memory; 136 union { 137 u_int32_t offset; 138 unsigned long userptr; 139 struct v4l2_plane *planes; 140 int32_t fd; 141 } m; 142 u_int32_t length; 143 u_int32_t reserved2; 144 u_int32_t reserved; 145}; 146.Ed 147.It Dv VIDIOC_QBUF Fa "struct v4l2_buffer *" 148Add a buffer to the queue. 149.Pp 150Same structure as for 151.Dv VIDIOC_QUERYBUF . 152.It Dv VIDIOC_DQBUF Fa "struct v4l2_buffer *" 153Remove a buffer from the queue. 154.Pp 155Same structure as for 156.Dv VIDIOC_QUERYBUF . 157.It Dv VIDIOC_STREAMON Fa "int *" 158Start video stream. 159.It Dv VIDIOC_STREAMOFF Fa "int *" 160Stop video stream. 161.It Dv VIDIOC_TRY_FMT Fa "struct v4l2_format *" 162Try a data format. 163.Pp 164Same structure as for 165.Dv VIDIOC_S_FMT . 166.It Dv VIDIOC_ENUM_FRAMEINTERVALS Fa "struct v4l2_frmivalenum *" 167Enumerate frame intervals. 168.Bd -literal 169struct v4l2_frmivalemun { 170 u_int32_t index; 171 u_int32_t pixel_format; 172 u_int32_t width; 173 u_int32_t height; 174 u_int32_t type; 175 union { 176 struct v4l2_fract discrete; 177 struct v4l2_frmival_stepwise stepwise; 178 }; 179 u_int32_t reserved[2]; 180}; 181 182struct v4l2_frmival_stepwise { 183 struct v4l2_fract min; 184 struct v4l2_fract max; 185 struct v4l2_fract step; 186}; 187.Ed 188.It Dv VIDIOC_S_PARM Fa "struct v4l2_streamparm *" 189Set streaming parameters. 190.Bd -literal 191struct v4l2_streamparm { 192 u_int32_t type; 193 union { 194 struct v4l2_captureparm capture; 195 struct v4l2_outputparm output; 196 u_int8_t raw_data[200]; 197 } parm; 198}; 199 200struct v4l2_captureparm { 201 u_int32_t capability; 202 u_int32_t capturemode; 203 struct v4l2_fract timeperframe; 204 u_int32_t extendedmode; 205 u_int32_t readbuffers; 206 u_int32_t reserved[4]; 207}; 208 209struct v4l2_outputparm { 210 u_int32_t capability; 211 u_int32_t outputmode; 212 struct v4l2_fract timeperframe; 213 u_int32_t extendedmode; 214 u_int32_t writebuffers; 215 u_int32_t reserved[4]; 216}; 217.Ed 218.It Dv VIDIOC_G_PARM Fa "struct v4l2_streamparm *" 219Get the streaming parameters. 220.Pp 221Same structures as for 222.Dv VIDIOC_S_PARM . 223.It Dv VIDIOC_QUERYCTRL Fa "struct v4l2_queryctrl *" 224Enumerate control items. 225.Bd -literal 226struct v4l2_queryctrl { 227 u_int32_t id; 228 u_int32_t type; 229 u_int8_t name[32]; 230 int32_t minimum; 231 int32_t maximum; 232 int32_t step; 233 int32_t default_value; 234 u_int32_t flags; 235 u_int32_t reserved[2]; 236}; 237.Ed 238.El 239.Pp 240Command independent enumerations are: 241.Bd -literal 242enum v4l2_buf_type { 243 V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, 244 V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, 245 V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, 246 V4L2_BUF_TYPE_VBI_CAPTURE = 4, 247 V4L2_BUF_TYPE_VBI_OUTPUT = 5, 248 V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, 249 V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, 250 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, 251 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE = 9, 252 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE = 10, 253 V4L2_BUF_TYPE_SDR_CAPTURE = 11, 254 V4L2_BUF_TYPE_SDR_OUTPUT = 12, 255 V4L2_BUF_TYPE_PRIVATE = 0x80, 256}; 257 258enum v4l2_memory { 259 V4L2_MEMORY_MMAP = 1, 260 V4L2_MEMORY_USERPTR = 2, 261 V4L2_MEMORY_OVERLAY = 3, 262 V4L2_MEMORY_DMABUF = 4, 263}; 264 265enum v4l2_ctrl_type { 266 V4L2_CTRL_TYPE_INTEGER = 1, 267 V4L2_CTRL_TYPE_BOOLEAN = 2, 268 V4L2_CTRL_TYPE_MENU = 3, 269 V4L2_CTRL_TYPE_BUTTON = 4, 270 V4L2_CTRL_TYPE_INTEGER64 = 5, 271 V4L2_CTRL_TYPE_CTRL_CLASS = 6, 272 V4L2_CTRL_TYPE_STRING = 7, 273 V4L2_CTRL_TYPE_BITMASK = 8, 274 V4L2_CTRL_TYPE_INTEGER_MENU = 9, 275 V4L2_CTRL_COMPOUND_TYPES = 0x0100, 276 V4L2_CTRL_TYPE_U8 = 0x0100, 277 V4L2_CTRL_TYPE_U16 = 0x0101, 278 V4L2_CTRL_TYPE_U32 = 0x0102, 279}; 280 281enum v4l2_frmivaltypes { 282 V4L2_FRMIVAL_TYPE_DISCRETE = 1, 283 V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, 284 V4L2_FRMIVAL_TYPE_STEPWISE = 3, 285}; 286.Ed 287.Pp 288Command independent structures are: 289.Bd -literal 290struct v4l2_pix_format { 291 u_int32_t width; 292 u_int32_t height; 293 u_int32_t pixelformat; 294 u_int32_t field; 295 u_int32_t bytesperline; 296 u_int32_t sizeimage; 297 u_int32_t colorspace; 298 u_int32_t priv; 299 u_int32_t flags; 300 u_int32_t ycbcr_enc; 301 u_int32_t quantization; 302 u_int32_t xfer_func; 303}; 304 305struct v4l2_window { 306 struct v4l2_rect w; 307 u_int32_t field; 308 u_int32_t chromakey; 309 struct v4l2_clip __user *clips; 310 u_int32_t clipcount; 311 void __user *bitmap; 312 u_int8_t global_alpha; 313}; 314 315struct v4l2_vbi_format { 316 u_int32_t sampling_rate; 317 u_int32_t offset; 318 u_int32_t samples_per_line; 319 u_int32_t sample_format; 320 int32_t start[2]; 321 u_int32_t count[2]; 322 u_int32_t flags; 323 u_int32_t reserved[2]; 324}; 325 326struct v4l2_sliced_vbi_format { 327 u_int16_t service_set; 328 u_int16_t service_lines[2][24]; 329 u_int32_t io_size; 330 u_int32_t reserved[2]; 331}; 332 333struct v4l2_fract { 334 u_int32_t numerator; 335 u_int32_t denominator; 336}; 337.Ed 338.Pp 339Command independent typedefs are: 340.Bd -literal 341typedef u_int64_t v4l2_std_id; 342.Ed 343.Sh READ 344Video data can be accessed via the 345.Xr read 2 346system call. 347The main iteration for userland applications occurs as follow: 348.Pp 349.Bl -enum -compact -offset indent 350.It 351Open /dev/video* via the 352.Xr open 2 353system call. 354.It 355Read video data from the device via the 356.Xr read 2 357system call. 358The video stream will be started automatically with the first 359read, which means there is no need to issue a 360.Dv VIDIOC_STREAMON 361command. 362The read will always return a consistent video frame, if no error occurs. 363.It 364Process video data and start over again with step 2. 365.It 366When finished stop the video stream via the 367.Xr close 2 368system call. 369.El 370.Pp 371The 372.Xr select 2 373and 374.Xr poll 2 375system calls are supported for this access type. 376They will signal when a frame is ready for reading without blocking. 377.Sh MMAP 378Video data can be accessed via the 379.Xr mmap 2 380system call. 381The main iteration for userland applications occurs as follow: 382.Pp 383.Bl -enum -compact -offset indent 384.It 385Open /dev/video* via the 386.Xr open 2 387system call. 388.It 389Request desired number of buffers via the 390.Dv VIDIOC_REQBUFS 391ioctl command. 392The maximum number of available buffers is normally limited by the hardware 393driver. 394.It 395Get the length and offset for the previously requested buffers via the 396.Dv VIDIOC_QUERYBUF 397ioctl command and map the buffers via the 398.Xr mmap 2 399system call. 400.It 401Initially queue the buffers via the 402.Dv VIDIOC_QBUF 403ioctl command. 404.It 405Start the video stream via the 406.Dv VIDIOC_STREAMON 407ioctl command. 408.It 409Dequeue one buffer via the 410.Dv VIDIOC_DQBUF 411ioctl command. 412If the queue is empty 413the ioctl will block until a buffer gets queued or an error occurs 414(e.g. a timeout). 415.It 416Process video data. 417.It 418Requeue the buffer via the 419.Dv VIDIOC_QBUF 420ioctl command and start over again with step 6. 421.It 422When finished stop the video stream via the 423.Dv VIDIOC_STREAMOFF 424ioctl command. 425.El 426.Pp 427The 428.Xr select 2 429and 430.Xr poll 2 431system calls are supported for this access type. 432They will signal when at least one frame is ready for dequeuing, 433allowing to call the 434.Dv VIDIOC_DQBUF 435ioctl command without blocking. 436.Sh FILES 437.Bl -tag -width /dev/video -compact 438.It Pa /dev/video 439.El 440.Sh SEE ALSO 441.Xr video 1 , 442.Xr ioctl 2 , 443.Xr uvideo 4 444.Sh HISTORY 445The 446.Nm 447driver first appeared in 448.Ox 4.4 . 449