1.\" $OpenBSD: video.4,v 1.17 2017/02/02 18:38:26 feinerer 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: February 2 2017 $ 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_frmivalenum { 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 union { 302 u_int32_t ycbcr_enc; 303 u_int32_t hsv_enc; 304 }; 305 u_int32_t quantization; 306 u_int32_t xfer_func; 307}; 308 309struct v4l2_window { 310 struct v4l2_rect w; 311 u_int32_t field; 312 u_int32_t chromakey; 313 struct v4l2_clip __user *clips; 314 u_int32_t clipcount; 315 void __user *bitmap; 316 u_int8_t global_alpha; 317}; 318 319struct v4l2_vbi_format { 320 u_int32_t sampling_rate; 321 u_int32_t offset; 322 u_int32_t samples_per_line; 323 u_int32_t sample_format; 324 int32_t start[2]; 325 u_int32_t count[2]; 326 u_int32_t flags; 327 u_int32_t reserved[2]; 328}; 329 330struct v4l2_sliced_vbi_format { 331 u_int16_t service_set; 332 u_int16_t service_lines[2][24]; 333 u_int32_t io_size; 334 u_int32_t reserved[2]; 335}; 336 337struct v4l2_fract { 338 u_int32_t numerator; 339 u_int32_t denominator; 340}; 341.Ed 342.Pp 343Command independent typedefs are: 344.Bd -literal 345typedef u_int64_t v4l2_std_id; 346.Ed 347.Sh READ 348Video data can be accessed via the 349.Xr read 2 350system call. 351The main iteration for userland applications occurs as follow: 352.Pp 353.Bl -enum -compact -offset indent 354.It 355Open /dev/video* via the 356.Xr open 2 357system call. 358.It 359Read video data from the device via the 360.Xr read 2 361system call. 362The video stream will be started automatically with the first 363read, which means there is no need to issue a 364.Dv VIDIOC_STREAMON 365command. 366The read will always return a consistent video frame, if no error occurs. 367.It 368Process video data and start over again with step 2. 369.It 370When finished stop the video stream via the 371.Xr close 2 372system call. 373.El 374.Pp 375The 376.Xr select 2 377and 378.Xr poll 2 379system calls are supported for this access type. 380They will signal when a frame is ready for reading without blocking. 381.Sh MMAP 382Video data can be accessed via the 383.Xr mmap 2 384system call. 385The main iteration for userland applications occurs as follow: 386.Pp 387.Bl -enum -compact -offset indent 388.It 389Open /dev/video* via the 390.Xr open 2 391system call. 392.It 393Request desired number of buffers via the 394.Dv VIDIOC_REQBUFS 395ioctl command. 396The maximum number of available buffers is normally limited by the hardware 397driver. 398.It 399Get the length and offset for the previously requested buffers via the 400.Dv VIDIOC_QUERYBUF 401ioctl command and map the buffers via the 402.Xr mmap 2 403system call. 404.It 405Initially queue the buffers via the 406.Dv VIDIOC_QBUF 407ioctl command. 408.It 409Start the video stream via the 410.Dv VIDIOC_STREAMON 411ioctl command. 412.It 413Dequeue one buffer via the 414.Dv VIDIOC_DQBUF 415ioctl command. 416If the queue is empty 417the ioctl will block until a buffer gets queued or an error occurs 418(e.g. a timeout). 419.It 420Process video data. 421.It 422Requeue the buffer via the 423.Dv VIDIOC_QBUF 424ioctl command and start over again with step 6. 425.It 426When finished stop the video stream via the 427.Dv VIDIOC_STREAMOFF 428ioctl command. 429.El 430.Pp 431The 432.Xr select 2 433and 434.Xr poll 2 435system calls are supported for this access type. 436They will signal when at least one frame is ready for dequeuing, 437allowing to call the 438.Dv VIDIOC_DQBUF 439ioctl command without blocking. 440.Sh FILES 441.Bl -tag -width /dev/video -compact 442.It Pa /dev/video 443.El 444.Sh SEE ALSO 445.Xr video 1 , 446.Xr ioctl 2 , 447.Xr uvideo 4 448.Sh HISTORY 449The 450.Nm 451driver first appeared in 452.Ox 4.4 . 453