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