Commit | Line | Data |
---|---|---|
f2ac8ce8 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
f6fa883b MCC |
3 | Video device' s internal representation |
4 | ======================================= | |
81d866fd | 5 | |
243b6935 MCC |
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. | |
81d866fd | 9 | |
7b998bae | 10 | To allocate it dynamically use :c:func:`video_device_alloc`: |
81d866fd | 11 | |
243b6935 | 12 | .. code-block:: c |
81d866fd MCC |
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 | ||
243b6935 | 21 | If you embed it in a larger struct, then you must set the ``release()`` |
81d866fd MCC |
22 | callback to your own function: |
23 | ||
243b6935 | 24 | .. code-block:: c |
81d866fd MCC |
25 | |
26 | struct video_device *vdev = &my_vdev->vdev; | |
27 | ||
28 | vdev->release = my_vdev_release; | |
29 | ||
243b6935 | 30 | The ``release()`` callback must be set and it is called when the last user |
81d866fd MCC |
31 | of the video device exits. |
32 | ||
7b998bae | 33 | The default :c:func:`video_device_release` callback currently |
243b6935 MCC |
34 | just calls ``kfree`` to free the allocated memory. |
35 | ||
eed57565 | 36 | There is also a :c:func:`video_device_release_empty` function that does |
243b6935 MCC |
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 | |
daf3a4f7 | 61 | provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and |
243b6935 MCC |
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 | ||
9303c9d5 | 70 | - :c:type:`video_device`->queue: a pointer to the struct vb2_queue |
243b6935 MCC |
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 | |
81d866fd MCC |
79 | queuing ownership (i.e. is the filehandle calling it allowed to do the |
80 | operation). | |
81 | ||
243b6935 MCC |
82 | - :c:type:`video_device`->prio: keeps track of the priorities. Used to |
83 | implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. | |
9303c9d5 | 84 | If left to ``NULL``, then it will use the struct v4l2_prio_state |
243b6935 MCC |
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 | |
9303c9d5 | 98 | struct video_device is initialized you **do** know which parent |
243b6935 MCC |
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 | |
7b998bae | 102 | :c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your |
243b6935 | 103 | :c:type:`v4l2_file_operations` struct. |
81d866fd MCC |
104 | |
105 | In some cases you want to tell the core that a function you had specified in | |
243b6935 | 106 | your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by |
7b998bae | 107 | calling this function before :c:func:`video_register_device` is called: |
81d866fd | 108 | |
7b998bae | 109 | :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>` |
243b6935 | 110 | (:c:type:`vdev <video_device>`, cmd). |
81d866fd MCC |
111 | |
112 | This tends to be needed if based on external factors (e.g. which card is | |
243b6935 MCC |
113 | being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops` |
114 | without having to make a new struct. | |
81d866fd | 115 | |
243b6935 MCC |
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. | |
81d866fd MCC |
119 | |
120 | If integration with the media framework is needed, you must initialize the | |
243b6935 | 121 | :c:type:`media_entity` struct embedded in the :c:type:`video_device` struct |
7b998bae | 122 | (entity field) by calling :c:func:`media_entity_pads_init`: |
81d866fd | 123 | |
243b6935 | 124 | .. code-block:: c |
81d866fd MCC |
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 | |
9303c9d5 | 141 | lock field in struct video_device, which is a pointer to a mutex. |
243b6935 MCC |
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 | |
81d866fd MCC |
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 | |
243b6935 | 154 | ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy |
81d866fd MCC |
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 | |
243b6935 | 158 | pointers at ``NULL``. |
81d866fd | 159 | |
243b6935 MCC |
160 | If you use the old :ref:`videobuf framework <vb_framework>` then you must |
161 | pass the :c:type:`video_device`->lock to the videobuf queue initialize | |
162 | function: if videobuf has to wait for a frame to arrive, then it will | |
163 | temporarily unlock the lock and relock it afterwards. If your driver also | |
164 | waits in the code, then you should do the same to allow other | |
81d866fd MCC |
165 | processes to access the device node while the first process is waiting for |
166 | something. | |
167 | ||
243b6935 MCC |
168 | In 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. | |
170 | If you use the ``queue->lock`` pointer, then you can use the helper functions | |
1b81f010 | 171 | :c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`. |
81d866fd MCC |
172 | |
173 | The implementation of a hotplug disconnect should also take the lock from | |
243b6935 MCC |
174 | :c:type:`video_device` before calling v4l2_device_disconnect. If you are also |
175 | using :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. | |
177 | That way you can be sure no ioctl is running when you call | |
e383ce07 | 178 | :c:func:`v4l2_device_disconnect`. |
81d866fd | 179 | |
243b6935 | 180 | Video device registration |
81d866fd MCC |
181 | ------------------------- |
182 | ||
7b998bae | 183 | Next you register the video device with :c:func:`video_register_device`. |
243b6935 | 184 | This will create the character device for you. |
81d866fd | 185 | |
243b6935 | 186 | .. code-block:: c |
81d866fd | 187 | |
238e4a5b | 188 | err = video_register_device(vdev, VFL_TYPE_VIDEO, -1); |
81d866fd MCC |
189 | if (err) { |
190 | video_device_release(vdev); /* or kfree(my_vdev); */ | |
191 | return err; | |
192 | } | |
193 | ||
243b6935 MCC |
194 | If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field, |
195 | the video device entity will be automatically registered with the media | |
196 | device. | |
81d866fd MCC |
197 | |
198 | Which device is registered depends on the type argument. The following | |
199 | types exist: | |
200 | ||
4839c58f MCC |
201 | ========================== ==================== ============================== |
202 | :c:type:`vfl_devnode_type` Device name Usage | |
203 | ========================== ==================== ============================== | |
238e4a5b | 204 | ``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices |
4839c58f MCC |
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 | ========================== ==================== ============================== | |
81d866fd MCC |
213 | |
214 | The last argument gives you a certain amount of control over the device | |
3cf80a75 | 215 | node number used (i.e. the X in ``videoX``). Normally you will pass -1 |
81d866fd MCC |
216 | to let the v4l2 framework pick the first free number. But sometimes users |
217 | want to select a specific node number. It is common that drivers allow | |
218 | the user to select a specific device node number through a driver module | |
219 | option. That number is then passed to this function and video_register_device | |
220 | will attempt to select that device node number. If that number was already | |
221 | in use, then the next free device node number will be selected and it | |
222 | will send a warning to the kernel log. | |
223 | ||
224 | Another use-case is if a driver creates many devices. In that case it can | |
225 | be useful to place different video devices in separate ranges. For example, | |
226 | video capture devices start at 0, video output devices start at 16. | |
227 | So you can use the last argument to specify a minimum device node number | |
228 | and the v4l2 framework will try to pick the first free number that is equal | |
229 | or higher to what you passed. If that fails, then it will just pick the | |
230 | first free number. | |
231 | ||
232 | Since in this case you do not care about a warning about not being able | |
233 | to select the specified device node number, you can call the function | |
7b998bae | 234 | :c:func:`video_register_device_no_warn` instead. |
81d866fd MCC |
235 | |
236 | Whenever a device node is created some attributes are also created for you. | |
243b6935 MCC |
237 | If 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 | |
241 | section for more detailed information on this. | |
81d866fd MCC |
242 | |
243 | The 'index' attribute is the index of the device node: for each call to | |
7b998bae | 244 | :c:func:`video_register_device()` the index is just increased by 1. The |
243b6935 | 245 | first video device node you register always starts with index 0. |
81d866fd MCC |
246 | |
247 | Users can setup udev rules that utilize the index attribute to make fancy | |
243b6935 | 248 | device names (e.g. '``mpegX``' for MPEG video capture device nodes). |
81d866fd MCC |
249 | |
250 | After the device was successfully registered, then you can use these fields: | |
251 | ||
243b6935 | 252 | - :c:type:`video_device`->vfl_type: the device type passed to |
7b998bae | 253 | :c:func:`video_register_device`. |
243b6935 MCC |
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. | |
81d866fd | 258 | |
243b6935 | 259 | If the registration failed, then you need to call |
7b998bae | 260 | :c:func:`video_device_release` to free the allocated :c:type:`video_device` |
243b6935 MCC |
261 | struct, or free your own struct if the :c:type:`video_device` was embedded in |
262 | it. The ``vdev->release()`` callback will never be called if the registration | |
263 | failed, nor should you ever attempt to unregister the device if the | |
264 | registration failed. | |
81d866fd MCC |
265 | |
266 | video device debugging | |
267 | ---------------------- | |
268 | ||
269 | The 'dev_debug' attribute that is created for each video, vbi, radio or swradio | |
243b6935 | 270 | device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of |
81d866fd MCC |
271 | file operations. |
272 | ||
273 | It is a bitmask and the following bits can be set: | |
274 | ||
5257d268 | 275 | .. tabularcolumns:: |p{5ex}|L| |
81d866fd | 276 | |
243b6935 MCC |
277 | ===== ================================================================ |
278 | Mask Description | |
279 | ===== ================================================================ | |
280 | 0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are | |
281 | only logged if bit 0x08 is also set. | |
282 | 0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF | |
283 | ioctls are | |
284 | only logged if bit 0x08 is also set. | |
285 | 0x04 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. | |
288 | 0x08 Log the read and write file operations and the VIDIOC_QBUF and | |
289 | VIDIOC_DQBUF ioctls. | |
290 | 0x10 Log the poll file operation. | |
173f6eac | 291 | 0x20 Log error and messages in the control operations. |
243b6935 MCC |
292 | ===== ================================================================ |
293 | ||
294 | Video device cleanup | |
81d866fd MCC |
295 | -------------------- |
296 | ||
297 | When the video device nodes have to be removed, either during the unload | |
298 | of the driver or because the USB device was disconnected, then you should | |
243b6935 | 299 | unregister them with: |
81d866fd | 300 | |
7b998bae | 301 | :c:func:`video_unregister_device` |
243b6935 | 302 | (:c:type:`vdev <video_device>`); |
81d866fd MCC |
303 | |
304 | This will remove the device nodes from sysfs (causing udev to remove them | |
243b6935 | 305 | from ``/dev``). |
81d866fd | 306 | |
7b998bae | 307 | After :c:func:`video_unregister_device` returns no new opens can be done. |
243b6935 MCC |
308 | However, in the case of USB devices some application might still have one of |
309 | these device nodes open. So after the unregister all file operations (except | |
81d866fd MCC |
310 | release, of course) will return an error as well. |
311 | ||
243b6935 | 312 | When the last user of the video device node exits, then the ``vdev->release()`` |
81d866fd MCC |
313 | callback is called and you can do the final cleanup there. |
314 | ||
315 | Don't forget to cleanup the media entity associated with the video device if | |
316 | it has been initialized: | |
317 | ||
7b998bae | 318 | :c:func:`media_entity_cleanup <media_entity_cleanup>` |
243b6935 | 319 | (&vdev->entity); |
81d866fd MCC |
320 | |
321 | This can be done from the release callback. | |
322 | ||
323 | ||
f6fa883b MCC |
324 | helper functions |
325 | ---------------- | |
81d866fd MCC |
326 | |
327 | There are a few useful helper functions: | |
328 | ||
243b6935 | 329 | - file and :c:type:`video_device` private data |
81d866fd MCC |
330 | |
331 | You can set/get driver private data in the video_device struct using: | |
332 | ||
7b998bae | 333 | :c:func:`video_get_drvdata <video_get_drvdata>` |
243b6935 | 334 | (:c:type:`vdev <video_device>`); |
81d866fd | 335 | |
7b998bae | 336 | :c:func:`video_set_drvdata <video_set_drvdata>` |
243b6935 | 337 | (:c:type:`vdev <video_device>`); |
81d866fd | 338 | |
7b998bae MCC |
339 | Note that you can safely call :c:func:`video_set_drvdata` before calling |
340 | :c:func:`video_register_device`. | |
81d866fd MCC |
341 | |
342 | And this function: | |
343 | ||
7b998bae | 344 | :c:func:`video_devdata <video_devdata>` |
243b6935 | 345 | (struct file \*file); |
81d866fd MCC |
346 | |
347 | returns the video_device belonging to the file struct. | |
348 | ||
1b81f010 | 349 | The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata` |
7b998bae | 350 | with :c:func:`video_devdata`: |
81d866fd | 351 | |
7b998bae | 352 | :c:func:`video_drvdata <video_drvdata>` |
243b6935 | 353 | (struct file \*file); |
81d866fd | 354 | |
243b6935 | 355 | You can go from a :c:type:`video_device` struct to the v4l2_device struct using: |
81d866fd | 356 | |
243b6935 | 357 | .. code-block:: c |
81d866fd MCC |
358 | |
359 | struct v4l2_device *v4l2_dev = vdev->v4l2_dev; | |
360 | ||
361 | - Device node name | |
362 | ||
243b6935 | 363 | The :c:type:`video_device` node kernel name can be retrieved using: |
81d866fd | 364 | |
7b998bae | 365 | :c:func:`video_device_node_name <video_device_node_name>` |
243b6935 | 366 | (:c:type:`vdev <video_device>`); |
81d866fd MCC |
367 | |
368 | The name is used as a hint by userspace tools such as udev. The function | |
369 | should be used where possible instead of accessing the video_device::num and | |
370 | video_device::minor fields. | |
371 | ||
f6fa883b MCC |
372 | video_device functions and data structures |
373 | ------------------------------------------ | |
81d866fd MCC |
374 | |
375 | .. kernel-doc:: include/media/v4l2-dev.h |