1.. SPDX-License-Identifier: GPL-2.0 2 3Video device' s internal representation 4======================================= 5 6The actual device nodes in the ``/dev`` directory are created using the 7:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be 8allocated dynamically or embedded in a larger struct. 9 10To allocate it dynamically use :c:func:`video_device_alloc`: 11 12.. code-block:: c 13 14 struct video_device *vdev = video_device_alloc(); 15 16 if (vdev == NULL) 17 return -ENOMEM; 18 19 vdev->release = video_device_release; 20 21If you embed it in a larger struct, then you must set the ``release()`` 22callback to your own function: 23 24.. code-block:: c 25 26 struct video_device *vdev = &my_vdev->vdev; 27 28 vdev->release = my_vdev_release; 29 30The ``release()`` callback must be set and it is called when the last user 31of the video device exits. 32 33The default :c:func:`video_device_release` callback currently 34just calls ``kfree`` to free the allocated memory. 35 36There is also a :c:func:`video_device_release_empty` function that does 37nothing (is empty) and should be used if the struct is embedded and there 38is nothing to do when it is released. 39 40You should also set these fields of :c:type:`video_device`: 41 42- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device` 43 parent device. 44 45- :c:type:`video_device`->name: set to something descriptive and unique. 46 47- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture 48 devices (``VFL_DIR_RX`` has value 0, so this is normally already the 49 default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices. 50 51- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations` 52 struct. 53 54- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops` 55 to simplify ioctl maintenance (highly recommended to use this and it might 56 become compulsory in the future!), then set this to your 57 :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and 58 :c:type:`video_device`->vfl_dir fields are used to disable ops that do not 59 match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes, 60 and output ops are disabled for a capture device. This makes it possible to 61 provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and 62 video nodes. 63 64- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the 65 locking in the driver. Otherwise you give it a pointer to a struct 66 ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl 67 file operation is called this lock will be taken by the core and released 68 afterwards. See the next section for more details. 69 70- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue` 71 associated with this device node. 72 If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock 73 is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``, 74 ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and 75 ``STREAMOFF``) instead of the lock above. 76 That way the :ref:`vb2 <vb2_framework>` queuing framework does not have 77 to wait for other ioctls. This queue pointer is also used by the 78 :ref:`vb2 <vb2_framework>` helper functions to check for 79 queuing ownership (i.e. is the filehandle calling it allowed to do the 80 operation). 81 82- :c:type:`video_device`->prio: keeps track of the priorities. Used to 83 implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. 84 If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state` 85 in :c:type:`v4l2_device`. If you want to have a separate priority state per 86 (group of) device node(s), then you can point it to your own struct 87 :c:type:`v4l2_prio_state`. 88 89- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was 90 registered with ``NULL`` as the parent ``device`` struct. This only happens 91 in cases where one hardware device has multiple PCI devices that all share 92 the same :c:type:`v4l2_device` core. 93 94 The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct, 95 but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device 96 (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI 97 devices at the same time it is setup without a parent device. But when the 98 struct :c:type:`video_device` is initialized you **do** know which parent 99 PCI device to use and so you set ``dev_device`` to the correct PCI device. 100 101If you use :c:type:`v4l2_ioctl_ops`, then you should set 102:c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your 103:c:type:`v4l2_file_operations` struct. 104 105In some cases you want to tell the core that a function you had specified in 106your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by 107calling this function before :c:func:`video_register_device` is called: 108 109 :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>` 110 (:c:type:`vdev <video_device>`, cmd). 111 112This tends to be needed if based on external factors (e.g. which card is 113being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops` 114without having to make a new struct. 115 116The :c:type:`v4l2_file_operations` struct is a subset of file_operations. 117The main difference is that the inode argument is omitted since it is never 118used. 119 120If integration with the media framework is needed, you must initialize the 121:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct 122(entity field) by calling :c:func:`media_entity_pads_init`: 123 124.. code-block:: c 125 126 struct media_pad *pad = &my_vdev->pad; 127 int err; 128 129 err = media_entity_pads_init(&vdev->entity, 1, pad); 130 131The pads array must have been previously initialized. There is no need to 132manually set the struct media_entity type and name fields. 133 134A reference to the entity will be automatically acquired/released when the 135video device is opened/closed. 136 137ioctls and locking 138------------------ 139 140The V4L core provides optional locking services. The main service is the 141lock field in struct :c:type:`video_device`, which is a pointer to a mutex. 142If you set this pointer, then that will be used by unlocked_ioctl to 143serialize all ioctls. 144 145If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there 146is a second lock that you can set: :c:type:`video_device`->queue->lock. If 147set, then this lock will be used instead of :c:type:`video_device`->lock 148to serialize all queuing ioctls (see the previous section 149for the full list of those ioctls). 150 151The advantage of using a different lock for the queuing ioctls is that for some 152drivers (particularly USB drivers) certain commands such as setting controls 153can take a long time, so you want to use a separate lock for the buffer queuing 154ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy 155changing the e.g. exposure of the webcam. 156 157Of course, you can always do all the locking yourself by leaving both lock 158pointers at ``NULL``. 159 160If you use the old :ref:`videobuf framework <vb_framework>` then you must 161pass the :c:type:`video_device`->lock to the videobuf queue initialize 162function: if videobuf has to wait for a frame to arrive, then it will 163temporarily unlock the lock and relock it afterwards. If your driver also 164waits in the code, then you should do the same to allow other 165processes to access the device node while the first process is waiting for 166something. 167 168In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the 169``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable. 170If you use the ``queue->lock`` pointer, then you can use the helper functions 171:c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`. 172 173The implementation of a hotplug disconnect should also take the lock from 174:c:type:`video_device` before calling v4l2_device_disconnect. If you are also 175using :c:type:`video_device`->queue->lock, then you have to first lock 176:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock. 177That way you can be sure no ioctl is running when you call 178:c:func:`v4l2_device_disconnect`. 179 180Video device registration 181------------------------- 182 183Next you register the video device with :c:func:`video_register_device`. 184This will create the character device for you. 185 186.. code-block:: c 187 188 err = video_register_device(vdev, VFL_TYPE_VIDEO, -1); 189 if (err) { 190 video_device_release(vdev); /* or kfree(my_vdev); */ 191 return err; 192 } 193 194If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field, 195the video device entity will be automatically registered with the media 196device. 197 198Which device is registered depends on the type argument. The following 199types exist: 200 201========================== ==================== ============================== 202:c:type:`vfl_devnode_type` Device name Usage 203========================== ==================== ============================== 204``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices 205``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. 206 closed captions, teletext) 207``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners 208``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices 209``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio 210 (SDR) tuners 211``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors 212========================== ==================== ============================== 213 214The last argument gives you a certain amount of control over the device 215device node number used (i.e. the X in ``videoX``). Normally you will pass -1 216to let the v4l2 framework pick the first free number. But sometimes users 217want to select a specific node number. It is common that drivers allow 218the user to select a specific device node number through a driver module 219option. That number is then passed to this function and video_register_device 220will attempt to select that device node number. If that number was already 221in use, then the next free device node number will be selected and it 222will send a warning to the kernel log. 223 224Another use-case is if a driver creates many devices. In that case it can 225be useful to place different video devices in separate ranges. For example, 226video capture devices start at 0, video output devices start at 16. 227So you can use the last argument to specify a minimum device node number 228and the v4l2 framework will try to pick the first free number that is equal 229or higher to what you passed. If that fails, then it will just pick the 230first free number. 231 232Since in this case you do not care about a warning about not being able 233to select the specified device node number, you can call the function 234:c:func:`video_register_device_no_warn` instead. 235 236Whenever a device node is created some attributes are also created for you. 237If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g. 238``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The 239'name' attribute is the 'name' field of the video_device struct. The 240'dev_debug' attribute can be used to enable core debugging. See the next 241section for more detailed information on this. 242 243The 'index' attribute is the index of the device node: for each call to 244:c:func:`video_register_device()` the index is just increased by 1. The 245first video device node you register always starts with index 0. 246 247Users can setup udev rules that utilize the index attribute to make fancy 248device names (e.g. '``mpegX``' for MPEG video capture device nodes). 249 250After the device was successfully registered, then you can use these fields: 251 252- :c:type:`video_device`->vfl_type: the device type passed to 253 :c:func:`video_register_device`. 254- :c:type:`video_device`->minor: the assigned device minor number. 255- :c:type:`video_device`->num: the device node number (i.e. the X in 256 ``videoX``). 257- :c:type:`video_device`->index: the device index number. 258 259If the registration failed, then you need to call 260:c:func:`video_device_release` to free the allocated :c:type:`video_device` 261struct, or free your own struct if the :c:type:`video_device` was embedded in 262it. The ``vdev->release()`` callback will never be called if the registration 263failed, nor should you ever attempt to unregister the device if the 264registration failed. 265 266video device debugging 267---------------------- 268 269The 'dev_debug' attribute that is created for each video, vbi, radio or swradio 270device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of 271file operations. 272 273It is a bitmask and the following bits can be set: 274 275.. tabularcolumns:: |p{5ex}|L| 276 277===== ================================================================ 278Mask Description 279===== ================================================================ 2800x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are 281 only logged if bit 0x08 is also set. 2820x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF 283 ioctls are 284 only logged if bit 0x08 is also set. 2850x04 Log the file operations open, release, read, write, mmap and 286 get_unmapped_area. The read and write operations are only 287 logged if bit 0x08 is also set. 2880x08 Log the read and write file operations and the VIDIOC_QBUF and 289 VIDIOC_DQBUF ioctls. 2900x10 Log the poll file operation. 2910x20 Log error and messages in the control operations. 292===== ================================================================ 293 294Video device cleanup 295-------------------- 296 297When the video device nodes have to be removed, either during the unload 298of the driver or because the USB device was disconnected, then you should 299unregister them with: 300 301 :c:func:`video_unregister_device` 302 (:c:type:`vdev <video_device>`); 303 304This will remove the device nodes from sysfs (causing udev to remove them 305from ``/dev``). 306 307After :c:func:`video_unregister_device` returns no new opens can be done. 308However, in the case of USB devices some application might still have one of 309these device nodes open. So after the unregister all file operations (except 310release, of course) will return an error as well. 311 312When the last user of the video device node exits, then the ``vdev->release()`` 313callback is called and you can do the final cleanup there. 314 315Don't forget to cleanup the media entity associated with the video device if 316it has been initialized: 317 318 :c:func:`media_entity_cleanup <media_entity_cleanup>` 319 (&vdev->entity); 320 321This can be done from the release callback. 322 323 324helper functions 325---------------- 326 327There are a few useful helper functions: 328 329- file and :c:type:`video_device` private data 330 331You can set/get driver private data in the video_device struct using: 332 333 :c:func:`video_get_drvdata <video_get_drvdata>` 334 (:c:type:`vdev <video_device>`); 335 336 :c:func:`video_set_drvdata <video_set_drvdata>` 337 (:c:type:`vdev <video_device>`); 338 339Note that you can safely call :c:func:`video_set_drvdata` before calling 340:c:func:`video_register_device`. 341 342And this function: 343 344 :c:func:`video_devdata <video_devdata>` 345 (struct file \*file); 346 347returns the video_device belonging to the file struct. 348 349The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata` 350with :c:func:`video_devdata`: 351 352 :c:func:`video_drvdata <video_drvdata>` 353 (struct file \*file); 354 355You can go from a :c:type:`video_device` struct to the v4l2_device struct using: 356 357.. code-block:: c 358 359 struct v4l2_device *v4l2_dev = vdev->v4l2_dev; 360 361- Device node name 362 363The :c:type:`video_device` node kernel name can be retrieved using: 364 365 :c:func:`video_device_node_name <video_device_node_name>` 366 (:c:type:`vdev <video_device>`); 367 368The name is used as a hint by userspace tools such as udev. The function 369should be used where possible instead of accessing the video_device::num and 370video_device::minor fields. 371 372video_device functions and data structures 373------------------------------------------ 374 375.. kernel-doc:: include/media/v4l2-dev.h 376