1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Video device' s internal representation 3 Video device' s internal representation
4 ======================================= 4 =======================================
5 5
6 The actual device nodes in the ``/dev`` direct 6 The actual device nodes in the ``/dev`` directory are created using the
7 :c:type:`video_device` struct (``v4l2-dev.h``) 7 :c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
8 allocated dynamically or embedded in a larger 8 allocated dynamically or embedded in a larger struct.
9 9
10 To allocate it dynamically use :c:func:`video_ 10 To allocate it dynamically use :c:func:`video_device_alloc`:
11 11
12 .. code-block:: c 12 .. code-block:: c
13 13
14 struct video_device *vdev = video_devi 14 struct video_device *vdev = video_device_alloc();
15 15
16 if (vdev == NULL) 16 if (vdev == NULL)
17 return -ENOMEM; 17 return -ENOMEM;
18 18
19 vdev->release = video_device_release; 19 vdev->release = video_device_release;
20 20
21 If you embed it in a larger struct, then you m 21 If you embed it in a larger struct, then you must set the ``release()``
22 callback to your own function: 22 callback to your own function:
23 23
24 .. code-block:: c 24 .. code-block:: c
25 25
26 struct video_device *vdev = &my_vdev-> 26 struct video_device *vdev = &my_vdev->vdev;
27 27
28 vdev->release = my_vdev_release; 28 vdev->release = my_vdev_release;
29 29
30 The ``release()`` callback must be set and it 30 The ``release()`` callback must be set and it is called when the last user
31 of the video device exits. 31 of the video device exits.
32 32
33 The default :c:func:`video_device_release` cal 33 The default :c:func:`video_device_release` callback currently
34 just calls ``kfree`` to free the allocated mem 34 just calls ``kfree`` to free the allocated memory.
35 35
36 There is also a :c:func:`video_device_release_ 36 There is also a :c:func:`video_device_release_empty` function that does
37 nothing (is empty) and should be used if the s 37 nothing (is empty) and should be used if the struct is embedded and there
38 is nothing to do when it is released. 38 is nothing to do when it is released.
39 39
40 You should also set these fields of :c:type:`v 40 You should also set these fields of :c:type:`video_device`:
41 41
42 - :c:type:`video_device`->v4l2_dev: must be se 42 - :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
43 parent device. 43 parent device.
44 44
45 - :c:type:`video_device`->name: set to somethi 45 - :c:type:`video_device`->name: set to something descriptive and unique.
46 46
47 - :c:type:`video_device`->vfl_dir: set this to 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 48 devices (``VFL_DIR_RX`` has value 0, so this is normally already the
49 default), set to ``VFL_DIR_TX`` for output d 49 default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.
50 50
51 - :c:type:`video_device`->fops: set to the :c: 51 - :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
52 struct. 52 struct.
53 53
54 - :c:type:`video_device`->ioctl_ops: if you us 54 - :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
55 to simplify ioctl maintenance (highly recomm 55 to simplify ioctl maintenance (highly recommended to use this and it might
56 become compulsory in the future!), then set 56 become compulsory in the future!), then set this to your
57 :c:type:`v4l2_ioctl_ops` struct. The :c:type 57 :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
58 :c:type:`video_device`->vfl_dir fields are u 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 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 d 60 and output ops are disabled for a capture device. This makes it possible to
61 provide just one :c:type:`v4l2_ioctl_ops` st 61 provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and
62 video nodes. 62 video nodes.
63 63
64 - :c:type:`video_device`->lock: leave to ``NUL 64 - :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
65 locking in the driver. Otherwise you give i 65 locking in the driver. Otherwise you give it a pointer to a struct
66 ``mutex_lock`` and before the :c:type:`video 66 ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
67 file operation is called this lock will be t 67 file operation is called this lock will be taken by the core and released
68 afterwards. See the next section for more de 68 afterwards. See the next section for more details.
69 69
70 - :c:type:`video_device`->queue: a pointer to !! 70 - :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
71 associated with this device node. 71 associated with this device node.
72 If queue is not ``NULL``, and queue->lock is 72 If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
73 is used for the queuing ioctls (``VIDIOC_REQ 73 is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
74 ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPAR 74 ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and
75 ``STREAMOFF``) instead of the lock above. 75 ``STREAMOFF``) instead of the lock above.
76 That way the :ref:`vb2 <vb2_framework>` queu 76 That way the :ref:`vb2 <vb2_framework>` queuing framework does not have
77 to wait for other ioctls. This queue point 77 to wait for other ioctls. This queue pointer is also used by the
78 :ref:`vb2 <vb2_framework>` helper functions 78 :ref:`vb2 <vb2_framework>` helper functions to check for
79 queuing ownership (i.e. is the filehandle ca 79 queuing ownership (i.e. is the filehandle calling it allowed to do the
80 operation). 80 operation).
81 81
82 - :c:type:`video_device`->prio: keeps track of 82 - :c:type:`video_device`->prio: keeps track of the priorities. Used to
83 implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC 83 implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
84 If left to ``NULL``, then it will use the st !! 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 hav 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 po 86 (group of) device node(s), then you can point it to your own struct
87 :c:type:`v4l2_prio_state`. 87 :c:type:`v4l2_prio_state`.
88 88
89 - :c:type:`video_device`->dev_parent: you only 89 - :c:type:`video_device`->dev_parent: you only set this if v4l2_device was
90 registered with ``NULL`` as the parent ``dev 90 registered with ``NULL`` as the parent ``device`` struct. This only happens
91 in cases where one hardware device has multi 91 in cases where one hardware device has multiple PCI devices that all share
92 the same :c:type:`v4l2_device` core. 92 the same :c:type:`v4l2_device` core.
93 93
94 The cx88 driver is an example of this: one c 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 dev 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` ca 96 (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
97 devices at the same time it is setup without 97 devices at the same time it is setup without a parent device. But when the
98 struct video_device is initialized you **do* !! 98 struct :c:type:`video_device` is initialized you **do** know which parent
99 PCI device to use and so you set ``dev_devic 99 PCI device to use and so you set ``dev_device`` to the correct PCI device.
100 100
101 If you use :c:type:`v4l2_ioctl_ops`, then you 101 If you use :c:type:`v4l2_ioctl_ops`, then you should set
102 :c:type:`video_device`->unlocked_ioctl to :c:f 102 :c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your
103 :c:type:`v4l2_file_operations` struct. 103 :c:type:`v4l2_file_operations` struct.
104 104
105 In some cases you want to tell the core that a 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 ignore 106 your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
107 calling this function before :c:func:`video_re 107 calling this function before :c:func:`video_register_device` is called:
108 108
109 :c:func:`v4l2_disable_ioctl <v4l2_disa 109 :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
110 (:c:type:`vdev <video_device>`, cmd). 110 (:c:type:`vdev <video_device>`, cmd).
111 111
112 This tends to be needed if based on external f 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 feat 113 being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops`
114 without having to make a new struct. 114 without having to make a new struct.
115 115
116 The :c:type:`v4l2_file_operations` struct is a 116 The :c:type:`v4l2_file_operations` struct is a subset of file_operations.
117 The main difference is that the inode argument 117 The main difference is that the inode argument is omitted since it is never
118 used. 118 used.
119 119
120 If integration with the media framework is nee 120 If integration with the media framework is needed, you must initialize the
121 :c:type:`media_entity` struct embedded in the 121 :c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
122 (entity field) by calling :c:func:`media_entit 122 (entity field) by calling :c:func:`media_entity_pads_init`:
123 123
124 .. code-block:: c 124 .. code-block:: c
125 125
126 struct media_pad *pad = &my_vdev->pad; 126 struct media_pad *pad = &my_vdev->pad;
127 int err; 127 int err;
128 128
129 err = media_entity_pads_init(&vdev->en 129 err = media_entity_pads_init(&vdev->entity, 1, pad);
130 130
131 The pads array must have been previously initi 131 The pads array must have been previously initialized. There is no need to
132 manually set the struct media_entity type and 132 manually set the struct media_entity type and name fields.
133 133
134 A reference to the entity will be automaticall 134 A reference to the entity will be automatically acquired/released when the
135 video device is opened/closed. 135 video device is opened/closed.
136 136
137 ioctls and locking 137 ioctls and locking
138 ------------------ 138 ------------------
139 139
140 The V4L core provides optional locking service 140 The V4L core provides optional locking services. The main service is the
141 lock field in struct video_device, which is a !! 141 lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
142 If you set this pointer, then that will be use 142 If you set this pointer, then that will be used by unlocked_ioctl to
143 serialize all ioctls. 143 serialize all ioctls.
144 144
145 If you are using the :ref:`videobuf2 framework 145 If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there
146 is a second lock that you can set: :c:type:`vi 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 147 set, then this lock will be used instead of :c:type:`video_device`->lock
148 to serialize all queuing ioctls (see the previ 148 to serialize all queuing ioctls (see the previous section
149 for the full list of those ioctls). 149 for the full list of those ioctls).
150 150
151 The advantage of using a different lock for th 151 The advantage of using a different lock for the queuing ioctls is that for some
152 drivers (particularly USB drivers) certain com 152 drivers (particularly USB drivers) certain commands such as setting controls
153 can take a long time, so you want to use a sep 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 154 ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy
155 changing the e.g. exposure of the webcam. 155 changing the e.g. exposure of the webcam.
156 156
157 Of course, you can always do all the locking y 157 Of course, you can always do all the locking yourself by leaving both lock
158 pointers at ``NULL``. 158 pointers at ``NULL``.
159 159
>> 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
>> 165 processes to access the device node while the first process is waiting for
>> 166 something.
>> 167
160 In the case of :ref:`videobuf2 <vb2_framework> 168 In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
161 ``wait_prepare()`` and ``wait_finish()`` callb 169 ``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.
162 If you use the ``queue->lock`` pointer, then y 170 If you use the ``queue->lock`` pointer, then you can use the helper functions
163 :c:func:`vb2_ops_wait_prepare` and :c:func:`vb 171 :c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`.
164 172
165 The implementation of a hotplug disconnect sho 173 The implementation of a hotplug disconnect should also take the lock from
166 :c:type:`video_device` before calling v4l2_dev 174 :c:type:`video_device` before calling v4l2_device_disconnect. If you are also
167 using :c:type:`video_device`->queue->lock, the 175 using :c:type:`video_device`->queue->lock, then you have to first lock
168 :c:type:`video_device`->queue->lock followed b 176 :c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
169 That way you can be sure no ioctl is running w 177 That way you can be sure no ioctl is running when you call
170 :c:func:`v4l2_device_disconnect`. 178 :c:func:`v4l2_device_disconnect`.
171 179
172 Video device registration 180 Video device registration
173 ------------------------- 181 -------------------------
174 182
175 Next you register the video device with :c:fun 183 Next you register the video device with :c:func:`video_register_device`.
176 This will create the character device for you. 184 This will create the character device for you.
177 185
178 .. code-block:: c 186 .. code-block:: c
179 187
180 err = video_register_device(vdev, VFL_ 188 err = video_register_device(vdev, VFL_TYPE_VIDEO, -1);
181 if (err) { 189 if (err) {
182 video_device_release(vdev); /* 190 video_device_release(vdev); /* or kfree(my_vdev); */
183 return err; 191 return err;
184 } 192 }
185 193
186 If the :c:type:`v4l2_device` parent device has 194 If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,
187 the video device entity will be automatically 195 the video device entity will be automatically registered with the media
188 device. 196 device.
189 197
190 Which device is registered depends on the type 198 Which device is registered depends on the type argument. The following
191 types exist: 199 types exist:
192 200
193 ========================== =================== 201 ========================== ==================== ==============================
194 :c:type:`vfl_devnode_type` Device name 202 :c:type:`vfl_devnode_type` Device name Usage
195 ========================== =================== 203 ========================== ==================== ==============================
196 ``VFL_TYPE_VIDEO`` ``/dev/videoX`` 204 ``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices
197 ``VFL_TYPE_VBI`` ``/dev/vbiX`` 205 ``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e.
198 206 closed captions, teletext)
199 ``VFL_TYPE_RADIO`` ``/dev/radioX`` 207 ``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners
200 ``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX` 208 ``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices
201 ``VFL_TYPE_SDR`` ``/dev/swradioX`` 209 ``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio
202 210 (SDR) tuners
203 ``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` 211 ``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors
204 ========================== =================== 212 ========================== ==================== ==============================
205 213
206 The last argument gives you a certain amount o 214 The last argument gives you a certain amount of control over the device
207 node number used (i.e. the X in ``videoX``). N !! 215 device node number used (i.e. the X in ``videoX``). Normally you will pass -1
208 to let the v4l2 framework pick the first free 216 to let the v4l2 framework pick the first free number. But sometimes users
209 want to select a specific node number. It is c 217 want to select a specific node number. It is common that drivers allow
210 the user to select a specific device node numb 218 the user to select a specific device node number through a driver module
211 option. That number is then passed to this fun 219 option. That number is then passed to this function and video_register_device
212 will attempt to select that device node number 220 will attempt to select that device node number. If that number was already
213 in use, then the next free device node number 221 in use, then the next free device node number will be selected and it
214 will send a warning to the kernel log. 222 will send a warning to the kernel log.
215 223
216 Another use-case is if a driver creates many d 224 Another use-case is if a driver creates many devices. In that case it can
217 be useful to place different video devices in 225 be useful to place different video devices in separate ranges. For example,
218 video capture devices start at 0, video output 226 video capture devices start at 0, video output devices start at 16.
219 So you can use the last argument to specify a 227 So you can use the last argument to specify a minimum device node number
220 and the v4l2 framework will try to pick the fi 228 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, t 229 or higher to what you passed. If that fails, then it will just pick the
222 first free number. 230 first free number.
223 231
224 Since in this case you do not care about a war 232 Since in this case you do not care about a warning about not being able
225 to select the specified device node number, yo 233 to select the specified device node number, you can call the function
226 :c:func:`video_register_device_no_warn` instea 234 :c:func:`video_register_device_no_warn` instead.
227 235
228 Whenever a device node is created some attribu 236 Whenever a device node is created some attributes are also created for you.
229 If you look in ``/sys/class/video4linux`` you 237 If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
230 ``video0`` and you will see 'name', 'dev_debug 238 ``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The
231 'name' attribute is the 'name' field of the vi 239 'name' attribute is the 'name' field of the video_device struct. The
232 'dev_debug' attribute can be used to enable co 240 'dev_debug' attribute can be used to enable core debugging. See the next
233 section for more detailed information on this. 241 section for more detailed information on this.
234 242
235 The 'index' attribute is the index of the devi 243 The 'index' attribute is the index of the device node: for each call to
236 :c:func:`video_register_device()` the index is 244 :c:func:`video_register_device()` the index is just increased by 1. The
237 first video device node you register always st 245 first video device node you register always starts with index 0.
238 246
239 Users can setup udev rules that utilize the in 247 Users can setup udev rules that utilize the index attribute to make fancy
240 device names (e.g. '``mpegX``' for MPEG video 248 device names (e.g. '``mpegX``' for MPEG video capture device nodes).
241 249
242 After the device was successfully registered, 250 After the device was successfully registered, then you can use these fields:
243 251
244 - :c:type:`video_device`->vfl_type: the device 252 - :c:type:`video_device`->vfl_type: the device type passed to
245 :c:func:`video_register_device`. 253 :c:func:`video_register_device`.
246 - :c:type:`video_device`->minor: the assigned 254 - :c:type:`video_device`->minor: the assigned device minor number.
247 - :c:type:`video_device`->num: the device node 255 - :c:type:`video_device`->num: the device node number (i.e. the X in
248 ``videoX``). 256 ``videoX``).
249 - :c:type:`video_device`->index: the device in 257 - :c:type:`video_device`->index: the device index number.
250 258
251 If the registration failed, then you need to c 259 If the registration failed, then you need to call
252 :c:func:`video_device_release` to free the all 260 :c:func:`video_device_release` to free the allocated :c:type:`video_device`
253 struct, or free your own struct if the :c:type 261 struct, or free your own struct if the :c:type:`video_device` was embedded in
254 it. The ``vdev->release()`` callback will neve 262 it. The ``vdev->release()`` callback will never be called if the registration
255 failed, nor should you ever attempt to unregis 263 failed, nor should you ever attempt to unregister the device if the
256 registration failed. 264 registration failed.
257 265
258 video device debugging 266 video device debugging
259 ---------------------- 267 ----------------------
260 268
261 The 'dev_debug' attribute that is created for 269 The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
262 device in ``/sys/class/video4linux/<devX>/`` a 270 device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of
263 file operations. 271 file operations.
264 272
265 It is a bitmask and the following bits can be 273 It is a bitmask and the following bits can be set:
266 274
267 .. tabularcolumns:: |p{5ex}|L| 275 .. tabularcolumns:: |p{5ex}|L|
268 276
269 ===== ======================================== 277 ===== ================================================================
270 Mask Description 278 Mask Description
271 ===== ======================================== 279 ===== ================================================================
272 0x01 Log the ioctl name and error code. VIDIO 280 0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are
273 only logged if bit 0x08 is also set. 281 only logged if bit 0x08 is also set.
274 0x02 Log the ioctl name arguments and error c 282 0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF
275 ioctls are 283 ioctls are
276 only logged if bit 0x08 is also set. 284 only logged if bit 0x08 is also set.
277 0x04 Log the file operations open, release, r 285 0x04 Log the file operations open, release, read, write, mmap and
278 get_unmapped_area. The read and write op 286 get_unmapped_area. The read and write operations are only
279 logged if bit 0x08 is also set. 287 logged if bit 0x08 is also set.
280 0x08 Log the read and write file operations a 288 0x08 Log the read and write file operations and the VIDIOC_QBUF and
281 VIDIOC_DQBUF ioctls. 289 VIDIOC_DQBUF ioctls.
282 0x10 Log the poll file operation. 290 0x10 Log the poll file operation.
283 0x20 Log error and messages in the control op 291 0x20 Log error and messages in the control operations.
284 ===== ======================================== 292 ===== ================================================================
285 293
286 Video device cleanup 294 Video device cleanup
287 -------------------- 295 --------------------
288 296
289 When the video device nodes have to be removed 297 When the video device nodes have to be removed, either during the unload
290 of the driver or because the USB device was di 298 of the driver or because the USB device was disconnected, then you should
291 unregister them with: 299 unregister them with:
292 300
293 :c:func:`video_unregister_device` 301 :c:func:`video_unregister_device`
294 (:c:type:`vdev <video_device>`); 302 (:c:type:`vdev <video_device>`);
295 303
296 This will remove the device nodes from sysfs ( 304 This will remove the device nodes from sysfs (causing udev to remove them
297 from ``/dev``). 305 from ``/dev``).
298 306
299 After :c:func:`video_unregister_device` return 307 After :c:func:`video_unregister_device` returns no new opens can be done.
300 However, in the case of USB devices some appli 308 However, in the case of USB devices some application might still have one of
301 these device nodes open. So after the unregist 309 these device nodes open. So after the unregister all file operations (except
302 release, of course) will return an error as we 310 release, of course) will return an error as well.
303 311
304 When the last user of the video device node ex 312 When the last user of the video device node exits, then the ``vdev->release()``
305 callback is called and you can do the final cl 313 callback is called and you can do the final cleanup there.
306 314
307 Don't forget to cleanup the media entity assoc 315 Don't forget to cleanup the media entity associated with the video device if
308 it has been initialized: 316 it has been initialized:
309 317
310 :c:func:`media_entity_cleanup <media_e 318 :c:func:`media_entity_cleanup <media_entity_cleanup>`
311 (&vdev->entity); 319 (&vdev->entity);
312 320
313 This can be done from the release callback. 321 This can be done from the release callback.
314 322
315 323
316 helper functions 324 helper functions
317 ---------------- 325 ----------------
318 326
319 There are a few useful helper functions: 327 There are a few useful helper functions:
320 328
321 - file and :c:type:`video_device` private data 329 - file and :c:type:`video_device` private data
322 330
323 You can set/get driver private data in the vid 331 You can set/get driver private data in the video_device struct using:
324 332
325 :c:func:`video_get_drvdata <video_get_ 333 :c:func:`video_get_drvdata <video_get_drvdata>`
326 (:c:type:`vdev <video_device>`); 334 (:c:type:`vdev <video_device>`);
327 335
328 :c:func:`video_set_drvdata <video_set_ 336 :c:func:`video_set_drvdata <video_set_drvdata>`
329 (:c:type:`vdev <video_device>`); 337 (:c:type:`vdev <video_device>`);
330 338
331 Note that you can safely call :c:func:`video_s 339 Note that you can safely call :c:func:`video_set_drvdata` before calling
332 :c:func:`video_register_device`. 340 :c:func:`video_register_device`.
333 341
334 And this function: 342 And this function:
335 343
336 :c:func:`video_devdata <video_devdata> 344 :c:func:`video_devdata <video_devdata>`
337 (struct file \*file); 345 (struct file \*file);
338 346
339 returns the video_device belonging to the file 347 returns the video_device belonging to the file struct.
340 348
341 The :c:func:`video_devdata` function combines 349 The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata`
342 with :c:func:`video_devdata`: 350 with :c:func:`video_devdata`:
343 351
344 :c:func:`video_drvdata <video_drvdata> 352 :c:func:`video_drvdata <video_drvdata>`
345 (struct file \*file); 353 (struct file \*file);
346 354
347 You can go from a :c:type:`video_device` struc 355 You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
348 356
349 .. code-block:: c 357 .. code-block:: c
350 358
351 struct v4l2_device *v4l2_dev = vdev->v 359 struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
352 360
353 - Device node name 361 - Device node name
354 362
355 The :c:type:`video_device` node kernel name ca 363 The :c:type:`video_device` node kernel name can be retrieved using:
356 364
357 :c:func:`video_device_node_name <video 365 :c:func:`video_device_node_name <video_device_node_name>`
358 (:c:type:`vdev <video_device>`); 366 (:c:type:`vdev <video_device>`);
359 367
360 The name is used as a hint by userspace tools 368 The name is used as a hint by userspace tools such as udev. The function
361 should be used where possible instead of acces 369 should be used where possible instead of accessing the video_device::num and
362 video_device::minor fields. 370 video_device::minor fields.
363 371
364 video_device functions and data structures 372 video_device functions and data structures
365 ------------------------------------------ 373 ------------------------------------------
366 374
367 .. kernel-doc:: include/media/v4l2-dev.h 375 .. 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.