| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
Video device' s internal representation |
| 4 |
======================================= |
| 5 |
|
| 6 |
The 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 |
| 8 |
allocated dynamically or embedded in a larger struct. |
| 9 |
|
| 10 |
To 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 |
|
| 21 |
If you embed it in a larger struct, then you must set the ``release()`` |
| 22 |
callback 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 |
|
| 30 |
The ``release()`` callback must be set and it is called when the last user |
| 31 |
of the video device exits. |
| 32 |
|
| 33 |
The default :c:func:`video_device_release` callback currently |
| 34 |
just calls ``kfree`` to free the allocated memory. |
| 35 |
|
| 36 |
There is also a :c:func:`video_device_release_empty` function that does |
| 37 |
nothing (is empty) and should be used if the struct is embedded and there |
| 38 |
is nothing to do when it is released. |
| 39 |
|
| 40 |
You 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 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 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 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 |
|
| 101 |
If 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 |
|
| 105 |
In some cases you want to tell the core that a function you had specified in |
| 106 |
your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by |
| 107 |
calling 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 |
|
| 112 |
This tends to be needed if based on external factors (e.g. which card is |
| 113 |
being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops` |
| 114 |
without having to make a new struct. |
| 115 |
|
| 116 |
The :c:type:`v4l2_file_operations` struct is a subset of file_operations. |
| 117 |
The main difference is that the inode argument is omitted since it is never |
| 118 |
used. |
| 119 |
|
| 120 |
If 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 |
|
| 131 |
The pads array must have been previously initialized. There is no need to |
| 132 |
manually set the struct media_entity type and name fields. |
| 133 |
|
| 134 |
A reference to the entity will be automatically acquired/released when the |
| 135 |
video device is opened/closed. |
| 136 |
|
| 137 |
ioctls and locking |
| 138 |
------------------ |
| 139 |
|
| 140 |
The V4L core provides optional locking services. The main service is the |
| 141 |
lock field in struct video_device, which is a pointer to a mutex. |
| 142 |
If you set this pointer, then that will be used by unlocked_ioctl to |
| 143 |
serialize all ioctls. |
| 144 |
|
| 145 |
If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there |
| 146 |
is a second lock that you can set: :c:type:`video_device`->queue->lock. If |
| 147 |
set, then this lock will be used instead of :c:type:`video_device`->lock |
| 148 |
to serialize all queuing ioctls (see the previous section |
| 149 |
for the full list of those ioctls). |
| 150 |
|
| 151 |
The advantage of using a different lock for the queuing ioctls is that for some |
| 152 |
drivers (particularly USB drivers) certain commands such as setting controls |
| 153 |
can take a long time, so you want to use a separate lock for the buffer queuing |
| 154 |
ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy |
| 155 |
changing the e.g. exposure of the webcam. |
| 156 |
|
| 157 |
Of course, you can always do all the locking yourself by leaving both lock |
| 158 |
pointers at ``NULL``. |
| 159 |
|
| 160 |
In the case of :ref:`videobuf2 <vb2_framework>` you must set the ``queue->lock`` |
| 161 |
pointer to the lock you use to serialize the queuing ioctls. This ensures that |
| 162 |
that lock is released while waiting in ``VIDIOC_DQBUF`` for a buffer to arrive, |
| 163 |
and it is retaken afterwards. |
| 164 |
|
| 165 |
The implementation of a hotplug disconnect should also take the lock from |
| 166 |
:c:type:`video_device` before calling v4l2_device_disconnect. If you are also |
| 167 |
using :c:type:`video_device`->queue->lock, then you have to first lock |
| 168 |
:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock. |
| 169 |
That way you can be sure no ioctl is running when you call |
| 170 |
:c:func:`v4l2_device_disconnect`. |
| 171 |
|
| 172 |
Video device registration |
| 173 |
------------------------- |
| 174 |
|
| 175 |
Next you register the video device with :c:func:`video_register_device`. |
| 176 |
This will create the character device for you. |
| 177 |
|
| 178 |
.. code-block:: c |
| 179 |
|
| 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 |
|
| 186 |
If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field, |
| 187 |
the video device entity will be automatically registered with the media |
| 188 |
device. |
| 189 |
|
| 190 |
Which device is registered depends on the type argument. The following |
| 191 |
types exist: |
| 192 |
|
| 193 |
========================== ==================== ============================== |
| 194 |
:c:type:`vfl_devnode_type` Device name Usage |
| 195 |
========================== ==================== ============================== |
| 196 |
``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices |
| 197 |
``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. |
| 198 |
closed captions, teletext) |
| 199 |
``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners |
| 200 |
``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices |
| 201 |
``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio |
| 202 |
(SDR) tuners |
| 203 |
``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors |
| 204 |
========================== ==================== ============================== |
| 205 |
|
| 206 |
The last argument gives you a certain amount of control over the device |
| 207 |
node number used (i.e. the X in ``videoX``). Normally you will pass -1 |
| 208 |
to let the v4l2 framework pick the first free number. But sometimes users |
| 209 |
want to select a specific node number. It is common that drivers allow |
| 210 |
the user to select a specific device node number through a driver module |
| 211 |
option. That number is then passed to this function and video_register_device |
| 212 |
will attempt to select that device node number. If that number was already |
| 213 |
in use, then the next free device node number will be selected and it |
| 214 |
will send a warning to the kernel log. |
| 215 |
|
| 216 |
Another use-case is if a driver creates many devices. In that case it can |
| 217 |
be useful to place different video devices in separate ranges. For example, |
| 218 |
video capture devices start at 0, video output devices start at 16. |
| 219 |
So you can use the last argument to specify a minimum device node number |
| 220 |
and the v4l2 framework will try to pick the first free number that is equal |
| 221 |
or higher to what you passed. If that fails, then it will just pick the |
| 222 |
first free number. |
| 223 |
|
| 224 |
Since in this case you do not care about a warning about not being able |
| 225 |
to select the specified device node number, you can call the function |
| 226 |
:c:func:`video_register_device_no_warn` instead. |
| 227 |
|
| 228 |
Whenever a device node is created some attributes are also created for you. |
| 229 |
If 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. The |
| 231 |
'name' attribute is the 'name' field of the video_device struct. The |
| 232 |
'dev_debug' attribute can be used to enable core debugging. See the next |
| 233 |
section for more detailed information on this. |
| 234 |
|
| 235 |
The 'index' attribute is the index of the device node: for each call to |
| 236 |
:c:func:`video_register_device()` the index is just increased by 1. The |
| 237 |
first video device node you register always starts with index 0. |
| 238 |
|
| 239 |
Users can setup udev rules that utilize the index attribute to make fancy |
| 240 |
device names (e.g. '``mpegX``' for MPEG video capture device nodes). |
| 241 |
|
| 242 |
After the device was successfully registered, then you can use these fields: |
| 243 |
|
| 244 |
- :c:type:`video_device`->vfl_type: the device type passed to |
| 245 |
: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 in |
| 248 |
``videoX``). |
| 249 |
- :c:type:`video_device`->index: the device index number. |
| 250 |
|
| 251 |
If the registration failed, then you need to call |
| 252 |
:c:func:`video_device_release` to free the allocated :c:type:`video_device` |
| 253 |
struct, or free your own struct if the :c:type:`video_device` was embedded in |
| 254 |
it. The ``vdev->release()`` callback will never be called if the registration |
| 255 |
failed, nor should you ever attempt to unregister the device if the |
| 256 |
registration failed. |
| 257 |
|
| 258 |
video device debugging |
| 259 |
---------------------- |
| 260 |
|
| 261 |
The 'dev_debug' attribute that is created for each video, vbi, radio or swradio |
| 262 |
device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of |
| 263 |
file operations. |
| 264 |
|
| 265 |
It is a bitmask and the following bits can be set: |
| 266 |
|
| 267 |
.. tabularcolumns:: |p{5ex}|L| |
| 268 |
|
| 269 |
===== ================================================================ |
| 270 |
Mask Description |
| 271 |
===== ================================================================ |
| 272 |
0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are |
| 273 |
only logged if bit 0x08 is also set. |
| 274 |
0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF |
| 275 |
ioctls are |
| 276 |
only logged if bit 0x08 is also set. |
| 277 |
0x04 Log the file operations open, release, read, write, mmap and |
| 278 |
get_unmapped_area. The read and write operations are only |
| 279 |
logged if bit 0x08 is also set. |
| 280 |
0x08 Log the read and write file operations and the VIDIOC_QBUF and |
| 281 |
VIDIOC_DQBUF ioctls. |
| 282 |
0x10 Log the poll file operation. |
| 283 |
0x20 Log error and messages in the control operations. |
| 284 |
===== ================================================================ |
| 285 |
|
| 286 |
Video device cleanup |
| 287 |
-------------------- |
| 288 |
|
| 289 |
When the video device nodes have to be removed, either during the unload |
| 290 |
of the driver or because the USB device was disconnected, then you should |
| 291 |
unregister them with: |
| 292 |
|
| 293 |
:c:func:`video_unregister_device` |
| 294 |
(:c:type:`vdev <video_device>`); |
| 295 |
|
| 296 |
This will remove the device nodes from sysfs (causing udev to remove them |
| 297 |
from ``/dev``). |
| 298 |
|
| 299 |
After :c:func:`video_unregister_device` returns no new opens can be done. |
| 300 |
However, in the case of USB devices some application might still have one of |
| 301 |
these device nodes open. So after the unregister all file operations (except |
| 302 |
release, of course) will return an error as well. |
| 303 |
|
| 304 |
When the last user of the video device node exits, then the ``vdev->release()`` |
| 305 |
callback is called and you can do the final cleanup there. |
| 306 |
|
| 307 |
Don't forget to cleanup the media entity associated with the video device if |
| 308 |
it has been initialized: |
| 309 |
|
| 310 |
:c:func:`media_entity_cleanup <media_entity_cleanup>` |
| 311 |
(&vdev->entity); |
| 312 |
|
| 313 |
This can be done from the release callback. |
| 314 |
|
| 315 |
|
| 316 |
helper functions |
| 317 |
---------------- |
| 318 |
|
| 319 |
There are a few useful helper functions: |
| 320 |
|
| 321 |
- file and :c:type:`video_device` private data |
| 322 |
|
| 323 |
You 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 |
|
| 331 |
Note that you can safely call :c:func:`video_set_drvdata` before calling |
| 332 |
:c:func:`video_register_device`. |
| 333 |
|
| 334 |
And this function: |
| 335 |
|
| 336 |
:c:func:`video_devdata <video_devdata>` |
| 337 |
(struct file \*file); |
| 338 |
|
| 339 |
returns the video_device belonging to the file struct. |
| 340 |
|
| 341 |
The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata` |
| 342 |
with :c:func:`video_devdata`: |
| 343 |
|
| 344 |
:c:func:`video_drvdata <video_drvdata>` |
| 345 |
(struct file \*file); |
| 346 |
|
| 347 |
You can go from a :c:type:`video_device` struct to the v4l2_device struct using: |
| 348 |
|
| 349 |
.. code-block:: c |
| 350 |
|
| 351 |
struct v4l2_device *v4l2_dev = vdev->v4l2_dev; |
| 352 |
|
| 353 |
- Device node name |
| 354 |
|
| 355 |
The :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 |
|
| 360 |
The name is used as a hint by userspace tools such as udev. The function |
| 361 |
should be used where possible instead of accessing the video_device::num and |
| 362 |
video_device::minor fields. |
| 363 |
|
| 364 |
video_device functions and data structures |
| 365 |
------------------------------------------ |
| 366 |
|
| 367 |
.. kernel-doc:: include/media/v4l2-dev.h |