1.\" $OpenBSD: video.4,v 1.21 2025/01/15 20:34:50 kirill 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: January 15 2025 $ 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.Pp 44For security reasons video recording is blanked by default. 45To achieve this, the 46.Nm 47driver blanks image data received from the underlying video hardware driver. 48The superuser can change this behavior using the 49.Va kern.video.record 50.Xr sysctl 2 51variable: 52.Bd -literal -offset indent 53kern.video.record=0 # Recording is blanked (default) 54kern.video.record=1 # Recording is enabled 55.Ed 56.Sh IOCTLS 57The following 58.Xr ioctl 2 59commands are supported: 60.Bl -tag -width Ds 61.It Dv VIDIOC_QUERYCAP Fa "struct v4l2_capability *" 62Query device capabilities. 63.Bd -literal 64struct v4l2_capability { 65 u_int8_t driver[16]; 66 u_int8_t card[32]; 67 u_int8_t bus_info[32]; 68 u_int32_t version; 69 u_int32_t capabilities; 70 u_int32_t device_caps; 71 u_int32_t reserved[3]; 72}; 73.Ed 74.It Dv VIDIOC_ENUM_FMT Fa "struct v4l2_fmtdesc *" 75Enumerate image formats. 76.Bd -literal 77struct v4l2_fmtdesc { 78 u_int32_t index; 79 u_int32_t type; 80 u_int32_t flags; 81 u_int8_t description[32]; 82 u_int32_t pixelformat; 83 u_int32_t mbus_code; 84 u_int32_t reserved[3]; 85}; 86.Ed 87.It Dv VIDIOC_S_FMT Fa "struct v4l2_format *" 88Set the data format. 89.Bd -literal 90struct v4l2_format { 91 u_int32_t type; 92 union { 93 struct v4l2_pix_format pix; 94 struct v4l2_pix_format_mplane pix_mp; 95 struct v4l2_window win; 96 struct v4l2_vbi_format vbi; 97 struct v4l2_sliced_vbi_format sliced; 98 struct v4l2_sdr_format sdr; 99 struct v4l2_meta_format meta; 100 u_int8_t raw_data[200]; 101 } fmt; 102}; 103.Ed 104.It Dv VIDIOC_G_FMT Fa "struct v4l2_format *" 105Get the data format. 106.Pp 107Same structure as for 108.Dv VIDIOC_S_FMT . 109.It Dv VIDIOC_ENUMINPUT Fa "struct v4l2_input *" 110Enumerate video inputs. 111.Bd -literal 112struct v4l2_input { 113 u_int32_t index; 114 u_int8_t name[32]; 115 u_int32_t type; 116 u_int32_t audioset; 117 u_int32_t tuner; 118 v4l2_std_id std; 119 u_int32_t status; 120 u_int32_t capabilities; 121 u_int32_t reserved[3]; 122}; 123.Ed 124.It Dv VIDIOC_G_INPUT Fa "int *" 125Get the current video input. 126.It Dv VIDIOC_S_INPUT Fa "int *" 127Select the current video input. 128.It Dv VIDIOC_REQBUFS Fa "struct v4l2_requestbuffers *" 129Initiate memory mapping or user pointer I/O. 130.Bd -literal 131struct v4l2_requestbuffers { 132 u_int32_t count; 133 u_int32_t type; 134 u_int32_t memory; 135 u_int32_t capabilities; 136 u_Int32_t flags; 137 u_int32_t reserved[3]; 138}; 139.Ed 140.It Dv VIDIOC_QUERYBUF Fa "struct v4l2_buffer *" 141Query the status of a buffer. 142.Bd -literal 143struct v4l2_buffer { 144 u_int32_t index; 145 u_int32_t type; 146 u_int32_t bytesused; 147 u_int32_t flags; 148 u_int32_t field; 149 struct timeval timestamp; 150 struct v4l2_timecode timecode; 151 u_int32_t sequence; 152 u_int32_t memory; 153 union { 154 u_int32_t offset; 155 unsigned long userptr; 156 struct v4l2_plane *planes; 157 int32_t fd; 158 } m; 159 u_int32_t length; 160 u_int32_t reserved2; 161 union { 162 int32_t request_fd; 163 u_int32_t reserved; 164 } 165}; 166.Ed 167.It Dv VIDIOC_QBUF Fa "struct v4l2_buffer *" 168Add a buffer to the queue. 169.Pp 170Same structure as for 171.Dv VIDIOC_QUERYBUF . 172.It Dv VIDIOC_DQBUF Fa "struct v4l2_buffer *" 173Remove a buffer from the queue. 174.Pp 175Same structure as for 176.Dv VIDIOC_QUERYBUF . 177.It Dv VIDIOC_STREAMON Fa "int *" 178Start video stream. 179.It Dv VIDIOC_STREAMOFF Fa "int *" 180Stop video stream. 181.It Dv VIDIOC_TRY_FMT Fa "struct v4l2_format *" 182Try a data format. 183.Pp 184Same structure as for 185.Dv VIDIOC_S_FMT . 186.It Dv VIDIOC_ENUM_FRAMEINTERVALS Fa "struct v4l2_frmivalenum *" 187Enumerate frame intervals. 188.Bd -literal 189struct v4l2_frmivalenum { 190 u_int32_t index; 191 u_int32_t pixel_format; 192 u_int32_t width; 193 u_int32_t height; 194 u_int32_t type; 195 union { 196 struct v4l2_fract discrete; 197 struct v4l2_frmival_stepwise stepwise; 198 }; 199 u_int32_t reserved[2]; 200}; 201 202struct v4l2_frmival_stepwise { 203 struct v4l2_fract min; 204 struct v4l2_fract max; 205 struct v4l2_fract step; 206}; 207.Ed 208.It Dv VIDIOC_S_PARM Fa "struct v4l2_streamparm *" 209Set streaming parameters. 210.Bd -literal 211struct v4l2_streamparm { 212 u_int32_t type; 213 union { 214 struct v4l2_captureparm capture; 215 struct v4l2_outputparm output; 216 u_int8_t raw_data[200]; 217 } parm; 218}; 219 220struct v4l2_captureparm { 221 u_int32_t capability; 222 u_int32_t capturemode; 223 struct v4l2_fract timeperframe; 224 u_int32_t extendedmode; 225 u_int32_t readbuffers; 226 u_int32_t reserved[4]; 227}; 228 229struct v4l2_outputparm { 230 u_int32_t capability; 231 u_int32_t outputmode; 232 struct v4l2_fract timeperframe; 233 u_int32_t extendedmode; 234 u_int32_t writebuffers; 235 u_int32_t reserved[4]; 236}; 237.Ed 238.It Dv VIDIOC_G_PARM Fa "struct v4l2_streamparm *" 239Get the streaming parameters. 240.Pp 241Same structures as for 242.Dv VIDIOC_S_PARM . 243.It Dv VIDIOC_QUERYCTRL Fa "struct v4l2_queryctrl *" 244Enumerate control items. 245.Bd -literal 246struct v4l2_queryctrl { 247 u_int32_t id; 248 u_int32_t type; 249 u_int8_t name[32]; 250 int32_t minimum; 251 int32_t maximum; 252 int32_t step; 253 int32_t default_value; 254 u_int32_t flags; 255 u_int32_t reserved[2]; 256}; 257.Ed 258.El 259.Pp 260Command independent enumerations are: 261.Bd -literal 262enum v4l2_buf_type { 263 V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, 264 V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, 265 V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, 266 V4L2_BUF_TYPE_VBI_CAPTURE = 4, 267 V4L2_BUF_TYPE_VBI_OUTPUT = 5, 268 V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, 269 V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, 270 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, 271 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE = 9, 272 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE = 10, 273 V4L2_BUF_TYPE_SDR_CAPTURE = 11, 274 V4L2_BUF_TYPE_SDR_OUTPUT = 12, 275 V4L2_BUF_TYPE_META_CAPTURE = 13, 276 V4L2_BUF_TYPE_META_OUTPUT = 14, 277 /* Deprecated, do not use */ 278 V4L2_BUF_TYPE_PRIVATE = 0x80, 279}; 280 281enum v4l2_memory { 282 V4L2_MEMORY_MMAP = 1, 283 V4L2_MEMORY_USERPTR = 2, 284 V4L2_MEMORY_OVERLAY = 3, 285 V4L2_MEMORY_DMABUF = 4, 286}; 287 288enum v4l2_ctrl_type { 289 V4L2_CTRL_TYPE_INTEGER = 1, 290 V4L2_CTRL_TYPE_BOOLEAN = 2, 291 V4L2_CTRL_TYPE_MENU = 3, 292 V4L2_CTRL_TYPE_BUTTON = 4, 293 V4L2_CTRL_TYPE_INTEGER64 = 5, 294 V4L2_CTRL_TYPE_CTRL_CLASS = 6, 295 V4L2_CTRL_TYPE_STRING = 7, 296 V4L2_CTRL_TYPE_BITMASK = 8, 297 V4L2_CTRL_TYPE_INTEGER_MENU = 9, 298 V4L2_CTRL_COMPOUND_TYPES = 0x0100, 299 V4L2_CTRL_TYPE_U8 = 0x0100, 300 V4L2_CTRL_TYPE_U16 = 0x0101, 301 V4L2_CTRL_TYPE_U32 = 0x0102, 302 V4L2_CTRL_TYPE_AREA = 0x0106, 303 304 /* Compound types are >= 0x0100 */ 305 V4L2_CTRL_TYPE_HDR10_CLL_INFO = 0x0110, 306 V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY = 0x0111, 307 308 V4L2_CTRL_TYPE_H264_SPS = 0x0200, 309 V4L2_CTRL_TYPE_H264_PPS = 0x0201, 310 V4L2_CTRL_TYPE_H264_SCALING_MATRIX = 0x0202, 311 V4L2_CTRL_TYPE_H264_SLICE_PARAMS = 0x0203, 312 V4L2_CTRL_TYPE_H264_DECODE_PARAMS = 0x0204, 313 V4L2_CTRL_TYPE_H264_PRED_WEIGHTS = 0x0205, 314 315 V4L2_CTRL_TYPE_FWHT_PARAMS = 0x0220, 316 317 V4L2_CTRL_TYPE_VP8_FRAME = 0x0240, 318 319 V4L2_CTRL_TYPE_MPEG2_QUANTISATION = 0x0250, 320 V4L2_CTRL_TYPE_MPEG2_SEQUENCE = 0x0251, 321 V4L2_CTRL_TYPE_MPEG2_PICTURE = 0x0252, 322 323 V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR = 0x0260, 324 V4L2_CTRL_TYPE_VP9_FRAME = 0x0261, 325 326 V4L2_CTRL_TYPE_HEVC_SPS = 0x0270, 327 V4L2_CTRL_TYPE_HEVC_PPS = 0x0271, 328 V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS = 0x0272, 329 V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX = 0x0273, 330 V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS = 0x0274, 331 332 V4L2_CTRL_TYPE_AV1_SEQUENCE = 0x280, 333 V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY = 0x281, 334 V4L2_CTRL_TYPE_AV1_FRAME = 0x282, 335 V4L2_CTRL_TYPE_AV1_FILM_GRAIN = 0x283, 336}; 337 338enum v4l2_frmivaltypes { 339 V4L2_FRMIVAL_TYPE_DISCRETE = 1, 340 V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, 341 V4L2_FRMIVAL_TYPE_STEPWISE = 3, 342}; 343.Ed 344.Pp 345Command independent structures are: 346.Bd -literal 347struct v4l2_pix_format { 348 u_int32_t width; 349 u_int32_t height; 350 u_int32_t pixelformat; 351 u_int32_t field; 352 u_int32_t bytesperline; 353 u_int32_t sizeimage; 354 u_int32_t colorspace; 355 u_int32_t priv; 356 u_int32_t flags; 357 union { 358 u_int32_t ycbcr_enc; 359 u_int32_t hsv_enc; 360 }; 361 u_int32_t quantization; 362 u_int32_t xfer_func; 363}; 364 365struct v4l2_window { 366 struct v4l2_rect w; 367 u_int32_t field; 368 u_int32_t chromakey; 369 struct v4l2_clip *clips; 370 u_int32_t clipcount; 371 void __user *bitmap; 372 u_int8_t global_alpha; 373}; 374 375struct v4l2_vbi_format { 376 u_int32_t sampling_rate; 377 u_int32_t offset; 378 u_int32_t samples_per_line; 379 u_int32_t sample_format; 380 int32_t start[2]; 381 u_int32_t count[2]; 382 u_int32_t flags; 383 u_int32_t reserved[2]; 384}; 385 386struct v4l2_sliced_vbi_format { 387 u_int16_t service_set; 388 u_int16_t service_lines[2][24]; 389 u_int32_t io_size; 390 u_int32_t reserved[2]; 391}; 392 393struct v4l2_fract { 394 u_int32_t numerator; 395 u_int32_t denominator; 396}; 397.Ed 398.Pp 399Command independent typedefs are: 400.Bd -literal 401typedef u_int64_t v4l2_std_id; 402.Ed 403.Sh READ 404Video data can be accessed via the 405.Xr read 2 406system call. 407The main iteration for userland applications occurs as follow: 408.Pp 409.Bl -enum -compact -offset indent 410.It 411Open /dev/video* via the 412.Xr open 2 413system call. 414.It 415Read video data from the device via the 416.Xr read 2 417system call. 418The video stream will be started automatically with the first 419read, which means there is no need to issue a 420.Dv VIDIOC_STREAMON 421command. 422The read will always return a consistent video frame, if no error occurs. 423.It 424Process video data and start over again with step 2. 425.It 426When finished, stop the video stream via the 427.Xr close 2 428system call. 429.El 430.Pp 431The 432.Xr select 2 , 433.Xr poll 2 434and 435.Xr kqueue 2 436system calls are supported for this access type. 437They will signal when a frame is ready for reading without blocking. 438.Sh MMAP 439Video data can be accessed via the 440.Xr mmap 2 441system call. 442The main iteration for userland applications occurs as follow: 443.Pp 444.Bl -enum -compact -offset indent 445.It 446Open /dev/video* via the 447.Xr open 2 448system call. 449.It 450Request desired number of buffers via the 451.Dv VIDIOC_REQBUFS 452ioctl command. 453The maximum number of available buffers is normally limited by the hardware 454driver. 455.It 456Get the length and offset for the previously requested buffers via the 457.Dv VIDIOC_QUERYBUF 458ioctl command and map the buffers via the 459.Xr mmap 2 460system call. 461.It 462Initially queue the buffers via the 463.Dv VIDIOC_QBUF 464ioctl command. 465.It 466Start the video stream via the 467.Dv VIDIOC_STREAMON 468ioctl command. 469.It 470Dequeue one buffer via the 471.Dv VIDIOC_DQBUF 472ioctl command. 473If the queue is empty, 474the ioctl will block until a buffer gets queued or an error occurs 475(e.g. a timeout). 476.It 477Process video data. 478.It 479Requeue the buffer via the 480.Dv VIDIOC_QBUF 481ioctl command and start over again with step 6. 482.It 483When finished, stop the video stream via the 484.Dv VIDIOC_STREAMOFF 485ioctl command. 486.El 487.Pp 488The 489.Xr select 2 , 490.Xr poll 2 491and 492.Xr kqueue 2 493system calls are supported for this access type. 494They will signal when at least one frame is ready for dequeuing, 495allowing to call the 496.Dv VIDIOC_DQBUF 497ioctl command without blocking. 498.Sh FILES 499.Bl -tag -width /dev/video -compact 500.It Pa /dev/video 501.El 502.Sh SEE ALSO 503.Xr video 1 , 504.Xr ioctl 2 , 505.Xr uvideo 4 506.Sh HISTORY 507The 508.Nm 509driver first appeared in 510.Ox 4.4 . 511