1 .. SPDX-License-Identifier: GPL-2.0
2
3 Video device' s internal representation
4 =======================================
5
6 The actual device nodes in the ``/dev`` direct
7 :c:type:`video_device` struct (``v4l2-dev.h``)
8 allocated dynamically or embedded in a larger
9
10 To allocate it dynamically use :c:func:`video_
11
12 .. code-block:: c
13
14 struct video_device *vdev = video_devi
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 m
22 callback to your own function:
23
24 .. code-block:: c
25
26 struct video_device *vdev = &my_vdev->
27
28 vdev->release = my_vdev_release;
29
30 The ``release()`` callback must be set and it
31 of the video device exits.
32
33 The default :c:func:`video_device_release` cal
34 just calls ``kfree`` to free the allocated mem
35
36 There is also a :c:func:`video_device_release_
37 nothing (is empty) and should be used if the s
38 is nothing to do when it is released.
39
40 You should also set these fields of :c:type:`v
41
42 - :c:type:`video_device`->v4l2_dev: must be se
43 parent device.
44
45 - :c:type:`video_device`->name: set to somethi
46
47 - :c:type:`video_device`->vfl_dir: set this to
48 devices (``VFL_DIR_RX`` has value 0, so this
49 default), set to ``VFL_DIR_TX`` for output d
50
51 - :c:type:`video_device`->fops: set to the :c:
52 struct.
53
54 - :c:type:`video_device`->ioctl_ops: if you us
55 to simplify ioctl maintenance (highly recomm
56 become compulsory in the future!), then set
57 :c:type:`v4l2_ioctl_ops` struct. The :c:type
58 :c:type:`video_device`->vfl_dir fields are u
59 match the type/dir combination. E.g. VBI ops
60 and output ops are disabled for a capture d
61 provide just one :c:type:`v4l2_ioctl_ops` st
62 video nodes.
63
64 - :c:type:`video_device`->lock: leave to ``NUL
65 locking in the driver. Otherwise you give i
66 ``mutex_lock`` and before the :c:type:`video
67 file operation is called this lock will be t
68 afterwards. See the next section for more de
69
70 - :c:type:`video_device`->queue: a pointer to
71 associated with this device node.
72 If queue is not ``NULL``, and queue->lock is
73 is used for the queuing ioctls (``VIDIOC_REQ
74 ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPAR
75 ``STREAMOFF``) instead of the lock above.
76 That way the :ref:`vb2 <vb2_framework>` queu
77 to wait for other ioctls. This queue point
78 :ref:`vb2 <vb2_framework>` helper functions
79 queuing ownership (i.e. is the filehandle ca
80 operation).
81
82 - :c:type:`video_device`->prio: keeps track of
83 implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC
84 If left to ``NULL``, then it will use the st
85 in :c:type:`v4l2_device`. If you want to hav
86 (group of) device node(s), then you can po
87 :c:type:`v4l2_prio_state`.
88
89 - :c:type:`video_device`->dev_parent: you only
90 registered with ``NULL`` as the parent ``dev
91 in cases where one hardware device has multi
92 the same :c:type:`v4l2_device` core.
93
94 The cx88 driver is an example of this: one c
95 but it is used by both a raw video PCI dev
96 (cx8802). Since the :c:type:`v4l2_device` ca
97 devices at the same time it is setup without
98 struct video_device is initialized you **do*
99 PCI device to use and so you set ``dev_devic
100
101 If you use :c:type:`v4l2_ioctl_ops`, then you
102 :c:type:`video_device`->unlocked_ioctl to :c:f
103 :c:type:`v4l2_file_operations` struct.
104
105 In some cases you want to tell the core that a
106 your :c:type:`v4l2_ioctl_ops` should be ignore
107 calling this function before :c:func:`video_re
108
109 :c:func:`v4l2_disable_ioctl <v4l2_disa
110 (:c:type:`vdev <video_device>`, cmd).
111
112 This tends to be needed if based on external f
113 being used) you want to turns off certain feat
114 without having to make a new struct.
115
116 The :c:type:`v4l2_file_operations` struct is a
117 The main difference is that the inode argument
118 used.
119
120 If integration with the media framework is nee
121 :c:type:`media_entity` struct embedded in the
122 (entity field) by calling :c:func:`media_entit
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->en
130
131 The pads array must have been previously initi
132 manually set the struct media_entity type and
133
134 A reference to the entity will be automaticall
135 video device is opened/closed.
136
137 ioctls and locking
138 ------------------
139
140 The V4L core provides optional locking service
141 lock field in struct video_device, which is a
142 If you set this pointer, then that will be use
143 serialize all ioctls.
144
145 If you are using the :ref:`videobuf2 framework
146 is a second lock that you can set: :c:type:`vi
147 set, then this lock will be used instead of :c
148 to serialize all queuing ioctls (see the previ
149 for the full list of those ioctls).
150
151 The advantage of using a different lock for th
152 drivers (particularly USB drivers) certain com
153 can take a long time, so you want to use a sep
154 ioctls. That way your ``VIDIOC_DQBUF`` doesn't
155 changing the e.g. exposure of the webcam.
156
157 Of course, you can always do all the locking y
158 pointers at ``NULL``.
159
160 In the case of :ref:`videobuf2 <vb2_framework>
161 ``wait_prepare()`` and ``wait_finish()`` callb
162 If you use the ``queue->lock`` pointer, then y
163 :c:func:`vb2_ops_wait_prepare` and :c:func:`vb
164
165 The implementation of a hotplug disconnect sho
166 :c:type:`video_device` before calling v4l2_dev
167 using :c:type:`video_device`->queue->lock, the
168 :c:type:`video_device`->queue->lock followed b
169 That way you can be sure no ioctl is running w
170 :c:func:`v4l2_device_disconnect`.
171
172 Video device registration
173 -------------------------
174
175 Next you register the video device with :c:fun
176 This will create the character device for you.
177
178 .. code-block:: c
179
180 err = video_register_device(vdev, VFL_
181 if (err) {
182 video_device_release(vdev); /*
183 return err;
184 }
185
186 If the :c:type:`v4l2_device` parent device has
187 the video device entity will be automatically
188 device.
189
190 Which device is registered depends on the type
191 types exist:
192
193 ========================== ===================
194 :c:type:`vfl_devnode_type` Device name
195 ========================== ===================
196 ``VFL_TYPE_VIDEO`` ``/dev/videoX``
197 ``VFL_TYPE_VBI`` ``/dev/vbiX``
198
199 ``VFL_TYPE_RADIO`` ``/dev/radioX``
200 ``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`
201 ``VFL_TYPE_SDR`` ``/dev/swradioX``
202
203 ``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX``
204 ========================== ===================
205
206 The last argument gives you a certain amount o
207 node number used (i.e. the X in ``videoX``). N
208 to let the v4l2 framework pick the first free
209 want to select a specific node number. It is c
210 the user to select a specific device node numb
211 option. That number is then passed to this fun
212 will attempt to select that device node number
213 in use, then the next free device node number
214 will send a warning to the kernel log.
215
216 Another use-case is if a driver creates many d
217 be useful to place different video devices in
218 video capture devices start at 0, video output
219 So you can use the last argument to specify a
220 and the v4l2 framework will try to pick the fi
221 or higher to what you passed. If that fails, t
222 first free number.
223
224 Since in this case you do not care about a war
225 to select the specified device node number, yo
226 :c:func:`video_register_device_no_warn` instea
227
228 Whenever a device node is created some attribu
229 If you look in ``/sys/class/video4linux`` you
230 ``video0`` and you will see 'name', 'dev_debug
231 'name' attribute is the 'name' field of the vi
232 'dev_debug' attribute can be used to enable co
233 section for more detailed information on this.
234
235 The 'index' attribute is the index of the devi
236 :c:func:`video_register_device()` the index is
237 first video device node you register always st
238
239 Users can setup udev rules that utilize the in
240 device names (e.g. '``mpegX``' for MPEG video
241
242 After the device was successfully registered,
243
244 - :c:type:`video_device`->vfl_type: the device
245 :c:func:`video_register_device`.
246 - :c:type:`video_device`->minor: the assigned
247 - :c:type:`video_device`->num: the device node
248 ``videoX``).
249 - :c:type:`video_device`->index: the device in
250
251 If the registration failed, then you need to c
252 :c:func:`video_device_release` to free the all
253 struct, or free your own struct if the :c:type
254 it. The ``vdev->release()`` callback will neve
255 failed, nor should you ever attempt to unregis
256 registration failed.
257
258 video device debugging
259 ----------------------
260
261 The 'dev_debug' attribute that is created for
262 device in ``/sys/class/video4linux/<devX>/`` a
263 file operations.
264
265 It is a bitmask and the following bits can be
266
267 .. tabularcolumns:: |p{5ex}|L|
268
269 ===== ========================================
270 Mask Description
271 ===== ========================================
272 0x01 Log the ioctl name and error code. VIDIO
273 only logged if bit 0x08 is also set.
274 0x02 Log the ioctl name arguments and error c
275 ioctls are
276 only logged if bit 0x08 is also set.
277 0x04 Log the file operations open, release, r
278 get_unmapped_area. The read and write op
279 logged if bit 0x08 is also set.
280 0x08 Log the read and write file operations a
281 VIDIOC_DQBUF ioctls.
282 0x10 Log the poll file operation.
283 0x20 Log error and messages in the control op
284 ===== ========================================
285
286 Video device cleanup
287 --------------------
288
289 When the video device nodes have to be removed
290 of the driver or because the USB device was di
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 (
297 from ``/dev``).
298
299 After :c:func:`video_unregister_device` return
300 However, in the case of USB devices some appli
301 these device nodes open. So after the unregist
302 release, of course) will return an error as we
303
304 When the last user of the video device node ex
305 callback is called and you can do the final cl
306
307 Don't forget to cleanup the media entity assoc
308 it has been initialized:
309
310 :c:func:`media_entity_cleanup <media_e
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 vid
324
325 :c:func:`video_get_drvdata <video_get_
326 (:c:type:`vdev <video_device>`);
327
328 :c:func:`video_set_drvdata <video_set_
329 (:c:type:`vdev <video_device>`);
330
331 Note that you can safely call :c:func:`video_s
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
340
341 The :c:func:`video_devdata` function combines
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` struc
348
349 .. code-block:: c
350
351 struct v4l2_device *v4l2_dev = vdev->v
352
353 - Device node name
354
355 The :c:type:`video_device` node kernel name ca
356
357 :c:func:`video_device_node_name <video
358 (:c:type:`vdev <video_device>`);
359
360 The name is used as a hint by userspace tools
361 should be used where possible instead of acces
362 video_device::minor fields.
363
364 video_device functions and data structures
365 ------------------------------------------
366
367 .. kernel-doc:: include/media/v4l2-dev.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.