368 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Video device' s internal representation4=======================================5 6The actual device nodes in the ``/dev`` directory are created using the7:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be8allocated dynamically or embedded in a larger struct.9 10To allocate it dynamically use :c:func:`video_device_alloc`:11 12.. code-block:: c13 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:: c25 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 user31of the video device exits.32 33The default :c:func:`video_device_release` callback currently34just calls ``kfree`` to free the allocated memory.35 36There is also a :c:func:`video_device_release_empty` function that does37nothing (is empty) and should be used if the struct is embedded and there38is 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 capture48 devices (``VFL_DIR_RX`` has value 0, so this is normally already the49 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 might56 become compulsory in the future!), then set this to your57 :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and58 :c:type:`video_device`->vfl_dir fields are used to disable ops that do not59 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 to61 provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and62 video nodes.63 64- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the65 locking in the driver. Otherwise you give it a pointer to a struct66 ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl67 file operation is called this lock will be taken by the core and released68 afterwards. See the next section for more details.69 70- :c:type:`video_device`->queue: a pointer to the struct vb2_queue71 associated with this device node.72 If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock73 is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,74 ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and75 ``STREAMOFF``) instead of the lock above.76 That way the :ref:`vb2 <vb2_framework>` queuing framework does not have77 to wait for other ioctls. This queue pointer is also used by the78 :ref:`vb2 <vb2_framework>` helper functions to check for79 queuing ownership (i.e. is the filehandle calling it allowed to do the80 operation).81 82- :c:type:`video_device`->prio: keeps track of the priorities. Used to83 implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.84 If left to ``NULL``, then it will use the struct v4l2_prio_state85 in :c:type:`v4l2_device`. If you want to have a separate priority state per86 (group of) device node(s), then you can point it to your own struct87 :c:type:`v4l2_prio_state`.88 89- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was90 registered with ``NULL`` as the parent ``device`` struct. This only happens91 in cases where one hardware device has multiple PCI devices that all share92 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 device96 (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI97 devices at the same time it is setup without a parent device. But when the98 struct video_device is initialized you **do** know which parent99 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 set102:c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your103:c:type:`v4l2_file_operations` struct.104 105In some cases you want to tell the core that a function you had specified in106your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by107calling 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 is113being 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 never118used.119 120If integration with the media framework is needed, you must initialize the121:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct122(entity field) by calling :c:func:`media_entity_pads_init`:123 124.. code-block:: c125 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 to132manually set the struct media_entity type and name fields.133 134A reference to the entity will be automatically acquired/released when the135video device is opened/closed.136 137ioctls and locking138------------------139 140The V4L core provides optional locking services. The main service is the141lock field in struct video_device, which is a pointer to a mutex.142If you set this pointer, then that will be used by unlocked_ioctl to143serialize all ioctls.144 145If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there146is a second lock that you can set: :c:type:`video_device`->queue->lock. If147set, then this lock will be used instead of :c:type:`video_device`->lock148to serialize all queuing ioctls (see the previous section149for the full list of those ioctls).150 151The advantage of using a different lock for the queuing ioctls is that for some152drivers (particularly USB drivers) certain commands such as setting controls153can take a long time, so you want to use a separate lock for the buffer queuing154ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy155changing the e.g. exposure of the webcam.156 157Of course, you can always do all the locking yourself by leaving both lock158pointers at ``NULL``.159 160In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the161``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.162If you use the ``queue->lock`` pointer, then you can use the helper functions163:c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`.164 165The implementation of a hotplug disconnect should also take the lock from166:c:type:`video_device` before calling v4l2_device_disconnect. If you are also167using :c:type:`video_device`->queue->lock, then you have to first lock168:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.169That way you can be sure no ioctl is running when you call170:c:func:`v4l2_device_disconnect`.171 172Video device registration173-------------------------174 175Next you register the video device with :c:func:`video_register_device`.176This will create the character device for you.177 178.. code-block:: c179 180 err = video_register_device(vdev, VFL_TYPE_VIDEO, -1);181 if (err) {182 video_device_release(vdev); /* or kfree(my_vdev); */183 return err;184 }185 186If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,187the video device entity will be automatically registered with the media188device.189 190Which device is registered depends on the type argument. The following191types exist:192 193========================== ==================== ==============================194:c:type:`vfl_devnode_type` Device name Usage195========================== ==================== ==============================196``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices197``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e.198 closed captions, teletext)199``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners200``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices201``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio202 (SDR) tuners203``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors204========================== ==================== ==============================205 206The last argument gives you a certain amount of control over the device207node number used (i.e. the X in ``videoX``). Normally you will pass -1208to let the v4l2 framework pick the first free number. But sometimes users209want to select a specific node number. It is common that drivers allow210the user to select a specific device node number through a driver module211option. That number is then passed to this function and video_register_device212will attempt to select that device node number. If that number was already213in use, then the next free device node number will be selected and it214will send a warning to the kernel log.215 216Another use-case is if a driver creates many devices. In that case it can217be useful to place different video devices in separate ranges. For example,218video capture devices start at 0, video output devices start at 16.219So you can use the last argument to specify a minimum device node number220and the v4l2 framework will try to pick the first free number that is equal221or higher to what you passed. If that fails, then it will just pick the222first free number.223 224Since in this case you do not care about a warning about not being able225to select the specified device node number, you can call the function226:c:func:`video_register_device_no_warn` instead.227 228Whenever a device node is created some attributes are also created for you.229If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.230``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The231'name' attribute is the 'name' field of the video_device struct. The232'dev_debug' attribute can be used to enable core debugging. See the next233section for more detailed information on this.234 235The 'index' attribute is the index of the device node: for each call to236:c:func:`video_register_device()` the index is just increased by 1. The237first video device node you register always starts with index 0.238 239Users can setup udev rules that utilize the index attribute to make fancy240device names (e.g. '``mpegX``' for MPEG video capture device nodes).241 242After the device was successfully registered, then you can use these fields:243 244- :c:type:`video_device`->vfl_type: the device type passed to245 :c:func:`video_register_device`.246- :c:type:`video_device`->minor: the assigned device minor number.247- :c:type:`video_device`->num: the device node number (i.e. the X in248 ``videoX``).249- :c:type:`video_device`->index: the device index number.250 251If the registration failed, then you need to call252:c:func:`video_device_release` to free the allocated :c:type:`video_device`253struct, or free your own struct if the :c:type:`video_device` was embedded in254it. The ``vdev->release()`` callback will never be called if the registration255failed, nor should you ever attempt to unregister the device if the256registration failed.257 258video device debugging259----------------------260 261The 'dev_debug' attribute that is created for each video, vbi, radio or swradio262device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of263file operations.264 265It is a bitmask and the following bits can be set:266 267.. tabularcolumns:: |p{5ex}|L|268 269===== ================================================================270Mask Description271===== ================================================================2720x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are273 only logged if bit 0x08 is also set.2740x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF275 ioctls are276 only logged if bit 0x08 is also set.2770x04 Log the file operations open, release, read, write, mmap and278 get_unmapped_area. The read and write operations are only279 logged if bit 0x08 is also set.2800x08 Log the read and write file operations and the VIDIOC_QBUF and281 VIDIOC_DQBUF ioctls.2820x10 Log the poll file operation.2830x20 Log error and messages in the control operations.284===== ================================================================285 286Video device cleanup287--------------------288 289When the video device nodes have to be removed, either during the unload290of the driver or because the USB device was disconnected, then you should291unregister them with:292 293 :c:func:`video_unregister_device`294 (:c:type:`vdev <video_device>`);295 296This will remove the device nodes from sysfs (causing udev to remove them297from ``/dev``).298 299After :c:func:`video_unregister_device` returns no new opens can be done.300However, in the case of USB devices some application might still have one of301these device nodes open. So after the unregister all file operations (except302release, of course) will return an error as well.303 304When the last user of the video device node exits, then the ``vdev->release()``305callback is called and you can do the final cleanup there.306 307Don't forget to cleanup the media entity associated with the video device if308it has been initialized:309 310 :c:func:`media_entity_cleanup <media_entity_cleanup>`311 (&vdev->entity);312 313This can be done from the release callback.314 315 316helper functions317----------------318 319There are a few useful helper functions:320 321- file and :c:type:`video_device` private data322 323You can set/get driver private data in the video_device struct using:324 325 :c:func:`video_get_drvdata <video_get_drvdata>`326 (:c:type:`vdev <video_device>`);327 328 :c:func:`video_set_drvdata <video_set_drvdata>`329 (:c:type:`vdev <video_device>`);330 331Note that you can safely call :c:func:`video_set_drvdata` before calling332:c:func:`video_register_device`.333 334And this function:335 336 :c:func:`video_devdata <video_devdata>`337 (struct file \*file);338 339returns the video_device belonging to the file struct.340 341The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata`342with :c:func:`video_devdata`:343 344 :c:func:`video_drvdata <video_drvdata>`345 (struct file \*file);346 347You can go from a :c:type:`video_device` struct to the v4l2_device struct using:348 349.. code-block:: c350 351 struct v4l2_device *v4l2_dev = vdev->v4l2_dev;352 353- Device node name354 355The :c:type:`video_device` node kernel name can be retrieved using:356 357 :c:func:`video_device_node_name <video_device_node_name>`358 (:c:type:`vdev <video_device>`);359 360The name is used as a hint by userspace tools such as udev. The function361should be used where possible instead of accessing the video_device::num and362video_device::minor fields.363 364video_device functions and data structures365------------------------------------------366 367.. kernel-doc:: include/media/v4l2-dev.h368