blob: cbefc7902f5f0edcbf175ed4207ae36741f5df84 [file] [log] [blame]
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -03001Overview of the V4L2 driver framework
2=====================================
3
4This text documents the various structures provided by the V4L2 framework and
5their relationships.
6
7
8Introduction
9------------
10
11The V4L2 drivers tend to be very complex due to the complexity of the
12hardware: most devices have multiple ICs, export multiple device nodes in
13/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input
14(IR) devices.
15
16Especially the fact that V4L2 drivers have to setup supporting ICs to
17do audio/video muxing/encoding/decoding makes it more complex than most.
18Usually these ICs are connected to the main bridge driver through one or
19more I2C busses, but other busses can also be used. Such devices are
20called 'sub-devices'.
21
22For a long time the framework was limited to the video_device struct for
23creating V4L device nodes and video_buf for handling the video buffers
24(note that this document does not discuss the video_buf framework).
25
26This meant that all drivers had to do the setup of device instances and
27connecting to sub-devices themselves. Some of this is quite complicated
28to do right and many drivers never did do it correctly.
29
30There is also a lot of common code that could never be refactored due to
31the lack of a framework.
32
33So this framework sets up the basic building blocks that all drivers
34need and this same framework should make it much easier to refactor
35common code into utility functions shared by all drivers.
36
Hans Verkuil926977e2014-03-14 08:38:21 -030037A good example to look at as a reference is the v4l2-pci-skeleton.c
Arnd Bergmann0185f852016-04-25 10:17:21 -030038source that is available in samples/v4l/. It is a skeleton driver for
Hans Verkuil926977e2014-03-14 08:38:21 -030039a PCI capture card, and demonstrates how to use the V4L2 driver
40framework. It can be used as a template for real PCI video capture driver.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030041
42Structure of a driver
43---------------------
44
45All drivers have the following structure:
46
471) A struct for each device instance containing the device state.
48
492) A way of initializing and commanding sub-devices (if any).
50
Hans Verkuilf44026d2010-08-06 12:52:43 -0300513) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX)
52 and keeping track of device-node specific data.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030053
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300544) Filehandle-specific structs containing per-filehandle data;
55
565) video buffer handling.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030057
58This is a rough schematic of how it all relates:
59
60 device instances
61 |
62 +-sub-device instances
63 |
64 \-V4L2 device nodes
65 |
66 \-filehandle instances
67
68
69Structure of the framework
70--------------------------
71
72The framework closely resembles the driver structure: it has a v4l2_device
73struct for the device instance data, a v4l2_subdev struct to refer to
74sub-device instances, the video_device struct stores V4L2 device node data
Nicolas THERYf818b352012-10-26 09:01:55 -030075and the v4l2_fh struct keeps track of filehandle instances.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030076
Laurent Pinchart2c0ab672009-12-09 08:40:10 -030077The V4L2 framework also optionally integrates with the media framework. If a
78driver sets the struct v4l2_device mdev field, sub-devices and video nodes
79will automatically appear in the media framework as entities.
80
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030081
82struct v4l2_device
83------------------
84
85Each device instance is represented by a struct v4l2_device (v4l2-device.h).
86Very simple devices can just allocate this struct, but most of the time you
87would embed this struct inside a larger struct.
88
89You must register the device instance:
90
91 v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
92
Laurent Pinchart95db3a62009-12-09 08:40:05 -030093Registration will initialize the v4l2_device struct. If the dev->driver_data
Laurent Pinchart2c0ab672009-12-09 08:40:10 -030094field is NULL, it will be linked to v4l2_dev.
95
96Drivers that want integration with the media device framework need to set
Laurent Pinchart95db3a62009-12-09 08:40:05 -030097dev->driver_data manually to point to the driver-specific device structure
98that embed the struct v4l2_device instance. This is achieved by a
Laurent Pinchart2c0ab672009-12-09 08:40:10 -030099dev_set_drvdata() call before registering the V4L2 device instance. They must
100also set the struct v4l2_device mdev field to point to a properly initialized
101and registered media_device instance.
Laurent Pinchart95db3a62009-12-09 08:40:05 -0300102
103If v4l2_dev->name is empty then it will be set to a value derived from dev
104(driver name followed by the bus_id, to be precise). If you set it up before
105calling v4l2_device_register then it will be untouched. If dev is NULL, then
106you *must* setup v4l2_dev->name before calling v4l2_device_register.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300107
Hans Verkuil102e7812009-05-02 10:12:50 -0300108You can use v4l2_device_set_name() to set the name based on a driver name and
109a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
110etc. If the name ends with a digit, then it will insert a dash: cx18-0,
111cx18-1, etc. This function returns the instance number.
112
Hans Verkuila47ddf12008-12-19 10:20:22 -0300113The first 'dev' argument is normally the struct device pointer of a pci_dev,
Janne Grunau073d6962009-04-01 08:30:06 -0300114usb_interface or platform_device. It is rare for dev to be NULL, but it happens
Hans Verkuil00575962009-03-13 10:03:04 -0300115with ISA devices or when one device creates multiple PCI devices, thus making
116it impossible to associate v4l2_dev with a particular parent.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300117
Hans Verkuil98ec6332009-03-08 17:02:10 -0300118You can also supply a notify() callback that can be called by sub-devices to
119notify you of events. Whether you need to set this depends on the sub-device.
120Any notifications a sub-device supports must be defined in a header in
121include/media/<subdevice>.h.
122
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300123You unregister with:
124
125 v4l2_device_unregister(struct v4l2_device *v4l2_dev);
126
Laurent Pinchart95db3a62009-12-09 08:40:05 -0300127If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300128Unregistering will also automatically unregister all subdevs from the device.
129
Hans Verkuilae6cfaa2009-03-14 08:28:45 -0300130If you have a hotpluggable device (e.g. a USB device), then when a disconnect
131happens the parent device becomes invalid. Since v4l2_device has a pointer to
132that parent device it has to be cleared as well to mark that the parent is
133gone. To do this call:
134
135 v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
136
137This does *not* unregister the subdevs, so you still need to call the
138v4l2_device_unregister() function for that. If your driver is not hotpluggable,
139then there is no need to call v4l2_device_disconnect().
140
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300141Sometimes you need to iterate over all devices registered by a specific
142driver. This is usually the case if multiple device drivers use the same
143hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
144hardware. The same is true for alsa drivers for example.
145
146You can iterate over all registered devices as follows:
147
148static int callback(struct device *dev, void *p)
149{
150 struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
151
152 /* test if this device was inited */
153 if (v4l2_dev == NULL)
154 return 0;
155 ...
156 return 0;
157}
158
159int iterate(void *p)
160{
161 struct device_driver *drv;
162 int err;
163
164 /* Find driver 'ivtv' on the PCI bus.
165 pci_bus_type is a global. For USB busses use usb_bus_type. */
166 drv = driver_find("ivtv", &pci_bus_type);
167 /* iterate over all ivtv device instances */
168 err = driver_for_each_device(drv, NULL, p, callback);
169 put_driver(drv);
170 return err;
171}
172
173Sometimes you need to keep a running counter of the device instance. This is
174commonly used to map a device instance to an index of a module option array.
175
176The recommended approach is as follows:
177
178static atomic_t drv_instance = ATOMIC_INIT(0);
179
Greg Kroah-Hartman63a29f72012-12-21 15:15:02 -0800180static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300181{
182 ...
183 state->instance = atomic_inc_return(&drv_instance) - 1;
184}
185
Hans Verkuil2335e2b2011-02-24 06:28:46 -0300186If you have multiple device nodes then it can be difficult to know when it is
Hans Verkuilee71e7b2012-04-19 12:27:56 -0300187safe to unregister v4l2_device for hotpluggable devices. For this purpose
188v4l2_device has refcounting support. The refcount is increased whenever
189video_register_device is called and it is decreased whenever that device node
190is released. When the refcount reaches zero, then the v4l2_device release()
191callback is called. You can do your final cleanup there.
Hans Verkuil2335e2b2011-02-24 06:28:46 -0300192
193If other device nodes (e.g. ALSA) are created, then you can increase and
194decrease the refcount manually as well by calling:
195
196void v4l2_device_get(struct v4l2_device *v4l2_dev);
197
198or:
199
200int v4l2_device_put(struct v4l2_device *v4l2_dev);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300201
Hans Verkuilee71e7b2012-04-19 12:27:56 -0300202Since the initial refcount is 1 you also need to call v4l2_device_put in the
203disconnect() callback (for USB devices) or in the remove() callback (for e.g.
204PCI devices), otherwise the refcount will never reach 0.
205
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300206struct v4l2_subdev
207------------------
208
209Many drivers need to communicate with sub-devices. These devices can do all
210sort of tasks, but most commonly they handle audio and/or video muxing,
211encoding or decoding. For webcams common sub-devices are sensors and camera
212controllers.
213
214Usually these are I2C devices, but not necessarily. In order to provide the
215driver with a consistent interface to these sub-devices the v4l2_subdev struct
216(v4l2-subdev.h) was created.
217
218Each sub-device driver must have a v4l2_subdev struct. This struct can be
219stand-alone for simple sub-devices or it might be embedded in a larger struct
220if more state information needs to be stored. Usually there is a low-level
221device struct (e.g. i2c_client) that contains the device data as setup
222by the kernel. It is recommended to store that pointer in the private
223data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
224from a v4l2_subdev to the actual low-level bus-specific device data.
225
226You also need a way to go from the low-level struct to v4l2_subdev. For the
227common i2c_client struct the i2c_set_clientdata() call is used to store a
228v4l2_subdev pointer, for other busses you may have to use other methods.
229
Laurent Pinchart692d55222010-07-30 17:24:55 -0300230Bridges might also need to store per-subdev private data, such as a pointer to
231bridge-specific per-subdev private data. The v4l2_subdev structure provides
232host private data for that purpose that can be accessed with
233v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata().
234
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300235From the bridge driver perspective you load the sub-device module and somehow
236obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
237i2c_get_clientdata(). For other busses something similar needs to be done.
238Helper functions exists for sub-devices on an I2C bus that do most of this
239tricky work for you.
240
241Each v4l2_subdev contains function pointers that sub-device drivers can
242implement (or leave NULL if it is not applicable). Since sub-devices can do
243so many different things and you do not want to end up with a huge ops struct
244of which only a handful of ops are commonly implemented, the function pointers
245are sorted according to category and each category has its own ops struct.
246
247The top-level ops struct contains pointers to the category ops structs, which
248may be NULL if the subdev driver does not support anything from that category.
249
250It looks like this:
251
252struct v4l2_subdev_core_ops {
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300253 int (*log_status)(struct v4l2_subdev *sd);
254 int (*init)(struct v4l2_subdev *sd, u32 val);
255 ...
256};
257
258struct v4l2_subdev_tuner_ops {
259 ...
260};
261
262struct v4l2_subdev_audio_ops {
263 ...
264};
265
266struct v4l2_subdev_video_ops {
267 ...
268};
269
Sakari Ailus48398f92012-01-23 03:03:00 -0300270struct v4l2_subdev_pad_ops {
271 ...
272};
273
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300274struct v4l2_subdev_ops {
275 const struct v4l2_subdev_core_ops *core;
276 const struct v4l2_subdev_tuner_ops *tuner;
277 const struct v4l2_subdev_audio_ops *audio;
278 const struct v4l2_subdev_video_ops *video;
Sakari Ailus48398f92012-01-23 03:03:00 -0300279 const struct v4l2_subdev_pad_ops *video;
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300280};
281
282The core ops are common to all subdevs, the other categories are implemented
283depending on the sub-device. E.g. a video device is unlikely to support the
284audio ops and vice versa.
285
286This setup limits the number of function pointers while still making it easy
287to add new ops and categories.
288
289A sub-device driver initializes the v4l2_subdev struct using:
290
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300291 v4l2_subdev_init(sd, &ops);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300292
293Afterwards you need to initialize subdev->name with a unique name and set the
294module owner. This is done for you if you use the i2c helper functions.
295
Laurent Pinchart61f5db52009-12-09 08:40:08 -0300296If integration with the media framework is needed, you must initialize the
297media_entity struct embedded in the v4l2_subdev struct (entity field) by
Mauro Carvalho Chehabab22e772015-12-11 07:44:40 -0200298calling media_entity_pads_init(), if the entity has pads:
Laurent Pinchart61f5db52009-12-09 08:40:08 -0300299
300 struct media_pad *pads = &my_sd->pads;
301 int err;
302
Mauro Carvalho Chehabab22e772015-12-11 07:44:40 -0200303 err = media_entity_pads_init(&sd->entity, npads, pads);
Laurent Pinchart61f5db52009-12-09 08:40:08 -0300304
305The pads array must have been previously initialized. There is no need to
Mauro Carvalho Chehab0e576b72015-09-06 09:33:39 -0300306manually set the struct media_entity function and name fields, but the
307revision field must be initialized if needed.
Laurent Pinchart61f5db52009-12-09 08:40:08 -0300308
309A reference to the entity will be automatically acquired/released when the
310subdev device node (if any) is opened/closed.
311
312Don't forget to cleanup the media entity before the sub-device is destroyed:
313
314 media_entity_cleanup(&sd->entity);
315
Sakari Ailus48398f92012-01-23 03:03:00 -0300316If the subdev driver intends to process video and integrate with the media
317framework, it must implement format related functionality using
318v4l2_subdev_pad_ops instead of v4l2_subdev_video_ops.
319
Sakari Ailus8227c922011-10-10 17:01:25 -0300320In that case, the subdev driver may set the link_validate field to provide
321its own link validation function. The link validation function is called for
322every link in the pipeline where both of the ends of the links are V4L2
323sub-devices. The driver is still responsible for validating the correctness
324of the format configuration between sub-devices and video nodes.
325
326If link_validate op is not set, the default function
327v4l2_subdev_link_validate_default() is used instead. This function ensures
328that width, height and the media bus pixel code are equal on both source and
329sink of the link. Subdev drivers are also free to use this function to
330perform the checks mentioned above in addition to their own checks.
331
Guennadi Liakhovetskic67f1a32013-06-17 02:50:33 -0300332There are currently two ways to register subdevices with the V4L2 core. The
333first (traditional) possibility is to have subdevices registered by bridge
334drivers. This can be done when the bridge driver has the complete information
335about subdevices connected to it and knows exactly when to register them. This
336is typically the case for internal subdevices, like video data processing units
337within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
338to SoCs, which pass information about them to bridge drivers, usually in their
339platform data.
340
341There are however also situations where subdevices have to be registered
342asynchronously to bridge devices. An example of such a configuration is a Device
343Tree based system where information about subdevices is made available to the
344system independently from the bridge devices, e.g. when subdevices are defined
345in DT as I2C device nodes. The API used in this second case is described further
346below.
347
348Using one or the other registration method only affects the probing process, the
349run-time bridge-subdevice interaction is in both cases the same.
350
351In the synchronous case a device (bridge) driver needs to register the
352v4l2_subdev with the v4l2_device:
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300353
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300354 int err = v4l2_device_register_subdev(v4l2_dev, sd);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300355
356This can fail if the subdev module disappeared before it could be registered.
357After this function was called successfully the subdev->dev field points to
358the v4l2_device.
359
Laurent Pinchart61f5db52009-12-09 08:40:08 -0300360If the v4l2_device parent device has a non-NULL mdev field, the sub-device
361entity will be automatically registered with the media device.
362
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300363You can unregister a sub-device using:
364
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300365 v4l2_device_unregister_subdev(sd);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300366
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300367Afterwards the subdev module can be unloaded and sd->dev == NULL.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300368
369You can call an ops function either directly:
370
Hans Verkuil2249aa52013-05-29 07:59:57 -0300371 err = sd->ops->core->g_std(sd, &norm);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300372
373but it is better and easier to use this macro:
374
Hans Verkuil2249aa52013-05-29 07:59:57 -0300375 err = v4l2_subdev_call(sd, core, g_std, &norm);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300376
377The macro will to the right NULL pointer checks and returns -ENODEV if subdev
Hans Verkuil2249aa52013-05-29 07:59:57 -0300378is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_std is
379NULL, or the actual result of the subdev->ops->core->g_std ops.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300380
381It is also possible to call all or a subset of the sub-devices:
382
Hans Verkuil2249aa52013-05-29 07:59:57 -0300383 v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300384
385Any subdev that does not support this ops is skipped and error results are
386ignored. If you want to check for errors use this:
387
Hans Verkuil2249aa52013-05-29 07:59:57 -0300388 err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300389
390Any error except -ENOIOCTLCMD will exit the loop with that error. If no
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300391errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300392
393The second argument to both calls is a group ID. If 0, then all subdevs are
394called. If non-zero, then only those whose group ID match that value will
Hans Verkuilb0167602009-02-14 12:00:53 -0300395be called. Before a bridge driver registers a subdev it can set sd->grp_id
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300396to whatever value it wants (it's 0 by default). This value is owned by the
397bridge driver and the sub-device driver will never modify or use it.
398
399The group ID gives the bridge driver more control how callbacks are called.
400For example, there may be multiple audio chips on a board, each capable of
401changing the volume. But usually only one will actually be used when the
402user want to change the volume. You can set the group ID for that subdev to
403e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
404v4l2_device_call_all(). That ensures that it will only go to the subdev
405that needs it.
406
Hans Verkuil98ec6332009-03-08 17:02:10 -0300407If the sub-device needs to notify its v4l2_device parent of an event, then
408it can call v4l2_subdev_notify(sd, notification, arg). This macro checks
409whether there is a notify() callback defined and returns -ENODEV if not.
410Otherwise the result of the notify() call is returned.
411
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300412The advantage of using v4l2_subdev is that it is a generic struct and does
413not contain any knowledge about the underlying hardware. So a driver might
414contain several subdevs that use an I2C bus, but also a subdev that is
415controlled through GPIO pins. This distinction is only relevant when setting
416up the device, but once the subdev is registered it is completely transparent.
417
418
Guennadi Liakhovetskic67f1a32013-06-17 02:50:33 -0300419In the asynchronous case subdevice probing can be invoked independently of the
420bridge driver availability. The subdevice driver then has to verify whether all
421the requirements for a successful probing are satisfied. This can include a
422check for a master clock availability. If any of the conditions aren't satisfied
423the driver might decide to return -EPROBE_DEFER to request further reprobing
424attempts. Once all conditions are met the subdevice shall be registered using
425the v4l2_async_register_subdev() function. Unregistration is performed using
426the v4l2_async_unregister_subdev() call. Subdevices registered this way are
427stored in a global list of subdevices, ready to be picked up by bridge drivers.
428
429Bridge drivers in turn have to register a notifier object with an array of
430subdevice descriptors that the bridge device needs for its operation. This is
431performed using the v4l2_async_notifier_register() call. To unregister the
432notifier the driver has to call v4l2_async_notifier_unregister(). The former of
433the two functions takes two arguments: a pointer to struct v4l2_device and a
434pointer to struct v4l2_async_notifier. The latter contains a pointer to an array
435of pointers to subdevice descriptors of type struct v4l2_async_subdev type. The
436V4L2 core will then use these descriptors to match asynchronously registered
437subdevices to them. If a match is detected the .bound() notifier callback is
438called. After all subdevices have been located the .complete() callback is
439called. When a subdevice is removed from the system the .unbind() method is
440called. All three callbacks are optional.
441
442
Laurent Pinchart2096a5d2009-12-09 08:38:49 -0300443V4L2 sub-device userspace API
444-----------------------------
445
446Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
447sub-devices can also be controlled directly by userspace applications.
448
449Device nodes named v4l-subdevX can be created in /dev to access sub-devices
450directly. If a sub-device supports direct userspace configuration it must set
451the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
452
453After registering sub-devices, the v4l2_device driver can create device nodes
454for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
455v4l2_device_register_subdev_nodes(). Those device nodes will be automatically
456removed when sub-devices are unregistered.
457
Laurent Pinchartea8aa432009-12-09 08:39:54 -0300458The device node handles a subset of the V4L2 API.
459
460VIDIOC_QUERYCTRL
461VIDIOC_QUERYMENU
462VIDIOC_G_CTRL
463VIDIOC_S_CTRL
464VIDIOC_G_EXT_CTRLS
465VIDIOC_S_EXT_CTRLS
466VIDIOC_TRY_EXT_CTRLS
467
468 The controls ioctls are identical to the ones defined in V4L2. They
469 behave identically, with the only exception that they deal only with
470 controls implemented in the sub-device. Depending on the driver, those
471 controls can be also be accessed through one (or several) V4L2 device
472 nodes.
473
Sakari Ailus02adb1c2010-03-03 12:49:38 -0300474VIDIOC_DQEVENT
475VIDIOC_SUBSCRIBE_EVENT
476VIDIOC_UNSUBSCRIBE_EVENT
477
478 The events ioctls are identical to the ones defined in V4L2. They
479 behave identically, with the only exception that they deal only with
480 events generated by the sub-device. Depending on the driver, those
481 events can also be reported by one (or several) V4L2 device nodes.
482
483 Sub-device drivers that want to use events need to set the
484 V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
485 v4l2_subdev::nevents to events queue depth before registering the
486 sub-device. After registration events can be queued as usual on the
487 v4l2_subdev::devnode device node.
488
489 To properly support events, the poll() file operation is also
490 implemented.
491
Laurent Pinchartc30b46e2010-02-26 12:23:10 -0300492Private ioctls
493
494 All ioctls not in the above list are passed directly to the sub-device
495 driver through the core::ioctl operation.
496
Laurent Pinchart2096a5d2009-12-09 08:38:49 -0300497
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300498I2C sub-device drivers
499----------------------
500
501Since these drivers are so common, special helper functions are available to
502ease the use of these drivers (v4l2-common.h).
503
504The recommended method of adding v4l2_subdev support to an I2C driver is to
505embed the v4l2_subdev struct into the state struct that is created for each
506I2C device instance. Very simple devices have no state struct and in that case
507you can just create a v4l2_subdev directly.
508
509A typical state struct would look like this (where 'chipname' is replaced by
510the name of the chip):
511
512struct chipname_state {
513 struct v4l2_subdev sd;
514 ... /* additional state fields */
515};
516
517Initialize the v4l2_subdev struct as follows:
518
519 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
520
521This function will fill in all the fields of v4l2_subdev and ensure that the
522v4l2_subdev and i2c_client both point to one another.
523
524You should also add a helper inline function to go from a v4l2_subdev pointer
525to a chipname_state struct:
526
527static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
528{
529 return container_of(sd, struct chipname_state, sd);
530}
531
532Use this to go from the v4l2_subdev struct to the i2c_client struct:
533
534 struct i2c_client *client = v4l2_get_subdevdata(sd);
535
536And this to go from an i2c_client to a v4l2_subdev struct:
537
538 struct v4l2_subdev *sd = i2c_get_clientdata(client);
539
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300540Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
541is called. This will unregister the sub-device from the bridge driver. It is
542safe to call this even if the sub-device was never registered.
543
Hans Verkuilf5360bd2009-01-15 06:09:05 -0300544You need to do this because when the bridge driver destroys the i2c adapter
545the remove() callbacks are called of the i2c devices on that adapter.
546After that the corresponding v4l2_subdev structures are invalid, so they
547have to be unregistered first. Calling v4l2_device_unregister_subdev(sd)
548from the remove() callback ensures that this is always done correctly.
549
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300550
551The bridge driver also has some helper functions it can use:
552
Hans Verkuile6574f22009-04-01 03:57:53 -0300553struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
Hans Verkuil53dacb12009-08-10 02:49:08 -0300554 "module_foo", "chipid", 0x36, NULL);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300555
556This loads the given module (can be NULL if no module needs to be loaded) and
557calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
Hans Verkuile6574f22009-04-01 03:57:53 -0300558If all goes well, then it registers the subdev with the v4l2_device.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300559
Hans Verkuil53dacb12009-08-10 02:49:08 -0300560You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
561of possible I2C addresses that it should probe. These probe addresses are
562only used if the previous argument is 0. A non-zero argument means that you
563know the exact i2c address so in that case no probing will take place.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300564
565Both functions return NULL if something went wrong.
566
Hans Verkuil53dacb12009-08-10 02:49:08 -0300567Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
Hans Verkuil2c792522009-03-12 18:34:19 -0300568the same as the module name. It allows you to specify a chip variant, e.g.
569"saa7114" or "saa7115". In general though the i2c driver autodetects this.
570The use of chipid is something that needs to be looked at more closely at a
571later date. It differs between i2c drivers and as such can be confusing.
572To see which chip variants are supported you can look in the i2c driver code
573for the i2c_device_id table. This lists all the possibilities.
574
Hans Verkuil2c0b19a2009-06-09 17:29:29 -0300575There are two more helper functions:
576
577v4l2_i2c_new_subdev_cfg: this function adds new irq and platform_data
578arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not
5790 then that will be used (non-probing variant), otherwise the probed_addrs
580are probed.
581
582For example: this will probe for address 0x10:
583
584struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
585 "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
586
587v4l2_i2c_new_subdev_board uses an i2c_board_info struct which is passed
588to the i2c driver and replaces the irq, platform_data and addr arguments.
589
590If the subdev supports the s_config core ops, then that op is called with
591the irq and platform_data arguments after the subdev was setup. The older
592v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with
593irq set to 0 and platform_data set to NULL.
594
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300595struct video_device
596-------------------
597
Hans Verkuila47ddf12008-12-19 10:20:22 -0300598The actual device nodes in the /dev directory are created using the
599video_device struct (v4l2-dev.h). This struct can either be allocated
600dynamically or embedded in a larger struct.
601
602To allocate it dynamically use:
603
604 struct video_device *vdev = video_device_alloc();
605
606 if (vdev == NULL)
607 return -ENOMEM;
608
609 vdev->release = video_device_release;
610
611If you embed it in a larger struct, then you must set the release()
612callback to your own function:
613
614 struct video_device *vdev = &my_vdev->vdev;
615
616 vdev->release = my_vdev_release;
617
618The release callback must be set and it is called when the last user
619of the video device exits.
620
621The default video_device_release() callback just calls kfree to free the
622allocated memory.
623
Hans Verkuil7cb59502013-06-12 11:28:08 -0300624There is also a video_device_release_empty() function that does nothing
625(is empty) and can be used if the struct is embedded and there is nothing
626to do when it is released.
627
Hans Verkuila47ddf12008-12-19 10:20:22 -0300628You should also set these fields:
629
Hans Verkuil7cb59502013-06-12 11:28:08 -0300630- v4l2_dev: must be set to the v4l2_device parent device.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300631
Hans Verkuila47ddf12008-12-19 10:20:22 -0300632- name: set to something descriptive and unique.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300633
Hans Verkuild2210f92012-09-17 05:06:33 -0300634- vfl_dir: set this to VFL_DIR_RX for capture devices (VFL_DIR_RX has value 0,
635 so this is normally already the default), set to VFL_DIR_TX for output
636 devices and VFL_DIR_M2M for mem2mem (codec) devices.
637
Hans Verkuilc7dd09d2008-12-23 13:42:25 -0300638- fops: set to the v4l2_file_operations struct.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300639
Hans Verkuila47ddf12008-12-19 10:20:22 -0300640- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
641 (highly recommended to use this and it might become compulsory in the
Hans Verkuild2210f92012-09-17 05:06:33 -0300642 future!), then set this to your v4l2_ioctl_ops struct. The vfl_type and
643 vfl_dir fields are used to disable ops that do not match the type/dir
644 combination. E.g. VBI ops are disabled for non-VBI nodes, and output ops
645 are disabled for a capture device. This makes it possible to provide
646 just one v4l2_ioctl_ops struct for both vbi and video nodes.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300647
Hans Verkuilee6869a2010-09-26 08:47:38 -0300648- lock: leave to NULL if you want to do all the locking in the driver.
Hans Verkuil74f22c42012-05-14 12:54:27 -0300649 Otherwise you give it a pointer to a struct mutex_lock and before the
650 unlocked_ioctl file operation is called this lock will be taken by the
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300651 core and released afterwards. See the next section for more details.
652
Hans Verkuil4a77a832012-07-02 05:43:34 -0300653- queue: a pointer to the struct vb2_queue associated with this device node.
654 If queue is non-NULL, and queue->lock is non-NULL, then queue->lock is
655 used for the queuing ioctls (VIDIOC_REQBUFS, CREATE_BUFS, QBUF, DQBUF,
656 QUERYBUF, PREPARE_BUF, STREAMON and STREAMOFF) instead of the lock above.
657 That way the vb2 queuing framework does not have to wait for other ioctls.
658 This queue pointer is also used by the vb2 helper functions to check for
659 queuing ownership (i.e. is the filehandle calling it allowed to do the
660 operation).
661
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300662- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
663 If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
664 If you want to have a separate priority state per (group of) device node(s),
665 then you can point it to your own struct v4l2_prio_state.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300666
Hans Verkuil7cb59502013-06-12 11:28:08 -0300667- dev_parent: you only set this if v4l2_device was registered with NULL as
Hans Verkuil00575962009-03-13 10:03:04 -0300668 the parent device struct. This only happens in cases where one hardware
669 device has multiple PCI devices that all share the same v4l2_device core.
670
671 The cx88 driver is an example of this: one core v4l2_device struct, but
Hans Verkuil7cb59502013-06-12 11:28:08 -0300672 it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
673 (cx8802). Since the v4l2_device cannot be associated with two PCI devices
674 at the same time it is setup without a parent device. But when the struct
675 video_device is initialized you *do* know which parent PCI device to use and
676 so you set dev_device to the correct PCI device.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300677
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300678If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
679in your v4l2_file_operations struct.
680
681Do not use .ioctl! This is deprecated and will go away in the future.
Hans Verkuilc7dd09d2008-12-23 13:42:25 -0300682
Hans Verkuil1dd87282012-05-10 05:04:41 -0300683In some cases you want to tell the core that a function you had specified in
684your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this
685function before video_device_register is called:
686
Hans Verkuil152a3a72012-05-14 11:32:48 -0300687void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
Hans Verkuil1dd87282012-05-10 05:04:41 -0300688
689This tends to be needed if based on external factors (e.g. which card is
690being used) you want to turns off certain features in v4l2_ioctl_ops without
691having to make a new struct.
692
Hans Verkuilc7dd09d2008-12-23 13:42:25 -0300693The v4l2_file_operations struct is a subset of file_operations. The main
694difference is that the inode argument is omitted since it is never used.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300695
Laurent Pinchart2c0ab672009-12-09 08:40:10 -0300696If integration with the media framework is needed, you must initialize the
697media_entity struct embedded in the video_device struct (entity field) by
Mauro Carvalho Chehabab22e772015-12-11 07:44:40 -0200698calling media_entity_pads_init():
Laurent Pinchart2c0ab672009-12-09 08:40:10 -0300699
700 struct media_pad *pad = &my_vdev->pad;
701 int err;
702
Mauro Carvalho Chehabab22e772015-12-11 07:44:40 -0200703 err = media_entity_pads_init(&vdev->entity, 1, pad);
Laurent Pinchart2c0ab672009-12-09 08:40:10 -0300704
705The pads array must have been previously initialized. There is no need to
706manually set the struct media_entity type and name fields.
707
708A reference to the entity will be automatically acquired/released when the
709video device is opened/closed.
710
Hans Verkuil4a77a832012-07-02 05:43:34 -0300711ioctls and locking
712------------------
Hans Verkuilee6869a2010-09-26 08:47:38 -0300713
Hans Verkuil4a77a832012-07-02 05:43:34 -0300714The V4L core provides optional locking services. The main service is the
715lock field in struct video_device, which is a pointer to a mutex. If you set
716this pointer, then that will be used by unlocked_ioctl to serialize all ioctls.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300717
Hans Verkuil4a77a832012-07-02 05:43:34 -0300718If you are using the videobuf2 framework, then there is a second lock that you
719can set: video_device->queue->lock. If set, then this lock will be used instead
720of video_device->lock to serialize all queuing ioctls (see the previous section
721for the full list of those ioctls).
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300722
Hans Verkuil4a77a832012-07-02 05:43:34 -0300723The advantage of using a different lock for the queuing ioctls is that for some
724drivers (particularly USB drivers) certain commands such as setting controls
725can take a long time, so you want to use a separate lock for the buffer queuing
726ioctls. That way your VIDIOC_DQBUF doesn't stall because the driver is busy
727changing the e.g. exposure of the webcam.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300728
Hans Verkuil4a77a832012-07-02 05:43:34 -0300729Of course, you can always do all the locking yourself by leaving both lock
730pointers at NULL.
Hans Verkuil8ab75e32012-05-10 02:51:31 -0300731
Hans Verkuil4a77a832012-07-02 05:43:34 -0300732If you use the old videobuf then you must pass the video_device lock to the
733videobuf queue initialize function: if videobuf has to wait for a frame to
734arrive, then it will temporarily unlock the lock and relock it afterwards. If
735your driver also waits in the code, then you should do the same to allow other
736processes to access the device node while the first process is waiting for
737something.
Hans Verkuilee6869a2010-09-26 08:47:38 -0300738
Hans Verkuil43599f32011-11-07 12:44:28 -0300739In the case of videobuf2 you will need to implement the wait_prepare and
Hans Verkuil4a77a832012-07-02 05:43:34 -0300740wait_finish callbacks to unlock/lock if applicable. If you use the queue->lock
741pointer, then you can use the helper functions vb2_ops_wait_prepare/finish.
Hans Verkuil43599f32011-11-07 12:44:28 -0300742
Hans Verkuil4a77a832012-07-02 05:43:34 -0300743The implementation of a hotplug disconnect should also take the lock from
744video_device before calling v4l2_device_disconnect. If you are also using
745video_device->queue->lock, then you have to first lock video_device->queue->lock
746followed by video_device->lock. That way you can be sure no ioctl is running
747when you call v4l2_device_disconnect.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300748
749video_device registration
750-------------------------
751
752Next you register the video device: this will create the character device
753for you.
754
755 err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
756 if (err) {
Hans Verkuil50a2a8b2008-12-22 09:13:11 -0300757 video_device_release(vdev); /* or kfree(my_vdev); */
Hans Verkuila47ddf12008-12-19 10:20:22 -0300758 return err;
759 }
760
Laurent Pinchart2c0ab672009-12-09 08:40:10 -0300761If the v4l2_device parent device has a non-NULL mdev field, the video device
762entity will be automatically registered with the media device.
763
Hans Verkuila47ddf12008-12-19 10:20:22 -0300764Which device is registered depends on the type argument. The following
765types exist:
766
767VFL_TYPE_GRABBER: videoX for video input/output devices
768VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
769VFL_TYPE_RADIO: radioX for radio tuners
Antti Palosaarib36514d2013-12-20 01:52:29 -0300770VFL_TYPE_SDR: swradioX for Software Defined Radio tuners
Hans Verkuila47ddf12008-12-19 10:20:22 -0300771
772The last argument gives you a certain amount of control over the device
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300773device node number used (i.e. the X in videoX). Normally you will pass -1
774to let the v4l2 framework pick the first free number. But sometimes users
775want to select a specific node number. It is common that drivers allow
776the user to select a specific device node number through a driver module
777option. That number is then passed to this function and video_register_device
778will attempt to select that device node number. If that number was already
779in use, then the next free device node number will be selected and it
780will send a warning to the kernel log.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300781
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300782Another use-case is if a driver creates many devices. In that case it can
783be useful to place different video devices in separate ranges. For example,
784video capture devices start at 0, video output devices start at 16.
Hans Verkuil22e22122009-09-06 07:13:14 -0300785So you can use the last argument to specify a minimum device node number
786and the v4l2 framework will try to pick the first free number that is equal
Hans Verkuila47ddf12008-12-19 10:20:22 -0300787or higher to what you passed. If that fails, then it will just pick the
788first free number.
789
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300790Since in this case you do not care about a warning about not being able
791to select the specified device node number, you can call the function
792video_register_device_no_warn() instead.
793
Hans Verkuila47ddf12008-12-19 10:20:22 -0300794Whenever a device node is created some attributes are also created for you.
795If you look in /sys/class/video4linux you see the devices. Go into e.g.
Hans Verkuil66108e32015-03-08 04:30:03 -0300796video0 and you will see 'name', 'dev_debug' and 'index' attributes. The 'name'
797attribute is the 'name' field of the video_device struct. The 'dev_debug' attribute
Hans Verkuil88f414f2014-12-01 10:10:45 -0300798can be used to enable core debugging. See the next section for more detailed
799information on this.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300800
Hans Verkuil7ae0cd92009-06-19 11:32:56 -0300801The 'index' attribute is the index of the device node: for each call to
802video_register_device() the index is just increased by 1. The first video
803device node you register always starts with index 0.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300804
805Users can setup udev rules that utilize the index attribute to make fancy
806device names (e.g. 'mpegX' for MPEG video capture device nodes).
807
808After the device was successfully registered, then you can use these fields:
809
810- vfl_type: the device type passed to video_register_device.
811- minor: the assigned device minor number.
Hans Verkuil22e22122009-09-06 07:13:14 -0300812- num: the device node number (i.e. the X in videoX).
Hans Verkuil7ae0cd92009-06-19 11:32:56 -0300813- index: the device index number.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300814
815If the registration failed, then you need to call video_device_release()
816to free the allocated video_device struct, or free your own struct if the
817video_device was embedded in it. The vdev->release() callback will never
818be called if the registration failed, nor should you ever attempt to
819unregister the device if the registration failed.
820
Hans Verkuil88f414f2014-12-01 10:10:45 -0300821video device debugging
822----------------------
823
Hans Verkuil66108e32015-03-08 04:30:03 -0300824The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
Hans Verkuil88f414f2014-12-01 10:10:45 -0300825device in /sys/class/video4linux/<devX>/ allows you to enable logging of
826file operations.
827
828It is a bitmask and the following bits can be set:
829
8300x01: Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are only logged
831 if bit 0x08 is also set.
8320x02: Log the ioctl name arguments and error code. VIDIOC_(D)QBUF ioctls are
833 only logged if bit 0x08 is also set.
8340x04: Log the file operations open, release, read, write, mmap and
835 get_unmapped_area. The read and write operations are only logged if
836 bit 0x08 is also set.
8370x08: Log the read and write file operations and the VIDIOC_QBUF and
838 VIDIOC_DQBUF ioctls.
8390x10: Log the poll file operation.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300840
841video_device cleanup
842--------------------
843
844When the video device nodes have to be removed, either during the unload
845of the driver or because the USB device was disconnected, then you should
846unregister them:
847
848 video_unregister_device(vdev);
849
850This will remove the device nodes from sysfs (causing udev to remove them
851from /dev).
852
Hans Verkuildd1ad942010-04-06 11:44:39 -0300853After video_unregister_device() returns no new opens can be done. However,
854in the case of USB devices some application might still have one of these
Hans Verkuild69f2712010-09-26 08:16:56 -0300855device nodes open. So after the unregister all file operations (except
856release, of course) will return an error as well.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300857
858When the last user of the video device node exits, then the vdev->release()
859callback is called and you can do the final cleanup there.
860
Laurent Pinchart2c0ab672009-12-09 08:40:10 -0300861Don't forget to cleanup the media entity associated with the video device if
862it has been initialized:
863
864 media_entity_cleanup(&vdev->entity);
865
866This can be done from the release callback.
867
Hans Verkuila47ddf12008-12-19 10:20:22 -0300868
869video_device helper functions
870-----------------------------
871
872There are a few useful helper functions:
873
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300874- file/video_device private data
875
Hans Verkuila47ddf12008-12-19 10:20:22 -0300876You can set/get driver private data in the video_device struct using:
877
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300878void *video_get_drvdata(struct video_device *vdev);
879void video_set_drvdata(struct video_device *vdev, void *data);
Hans Verkuila47ddf12008-12-19 10:20:22 -0300880
881Note that you can safely call video_set_drvdata() before calling
882video_register_device().
883
884And this function:
885
886struct video_device *video_devdata(struct file *file);
887
888returns the video_device belonging to the file struct.
889
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300890The video_drvdata function combines video_get_drvdata with video_devdata:
Hans Verkuila47ddf12008-12-19 10:20:22 -0300891
892void *video_drvdata(struct file *file);
893
894You can go from a video_device struct to the v4l2_device struct using:
895
Hans Verkuildfa9a5a2008-12-23 12:17:23 -0300896struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300897
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300898- Device node name
899
900The video_device node kernel name can be retrieved using
901
902const char *video_device_node_name(struct video_device *vdev);
903
904The name is used as a hint by userspace tools such as udev. The function
905should be used where possible instead of accessing the video_device::num and
906video_device::minor fields.
907
908
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300909video buffer helper functions
910-----------------------------
911
Jonathan Corbet4b586a32010-02-22 17:47:46 -0300912The v4l2 core API provides a set of standard methods (called "videobuf")
913for dealing with video buffers. Those methods allow a driver to implement
914read(), mmap() and overlay() in a consistent way. There are currently
915methods for using video buffers on devices that supports DMA with
916scatter/gather method (videobuf-dma-sg), DMA with linear access
917(videobuf-dma-contig), and vmalloced buffers, mostly used on USB drivers
918(videobuf-vmalloc).
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300919
Jonathan Corbet4b586a32010-02-22 17:47:46 -0300920Please see Documentation/video4linux/videobuf for more information on how
921to use the videobuf layer.
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300922
923struct v4l2_fh
924--------------
925
926struct v4l2_fh provides a way to easily keep file handle specific data
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300927that is used by the V4L2 framework. New drivers must use struct v4l2_fh
Ramakrishnan Muthukrishnanff792c82014-06-19 14:23:00 -0300928since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY).
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300929
930The users of v4l2_fh (in the V4L2 framework, not the driver) know
931whether a driver uses v4l2_fh as its file->private_data pointer by
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300932testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
933set whenever v4l2_fh_init() is called.
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300934
935struct v4l2_fh is allocated as a part of the driver's own file handle
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300936structure and file->private_data is set to it in the driver's open
937function by the driver.
938
939In many cases the struct v4l2_fh will be embedded in a larger structure.
940In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
941v4l2_fh_del+v4l2_fh_exit in release().
942
943Drivers can extract their own file handle structure by using the container_of
944macro. Example:
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300945
946struct my_fh {
947 int blah;
948 struct v4l2_fh fh;
949};
950
951...
952
953int my_open(struct file *file)
954{
955 struct my_fh *my_fh;
956 struct video_device *vfd;
957 int ret;
958
959 ...
960
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300961 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300962
963 ...
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300964
Hans Verkuil98019f52011-06-18 05:13:55 -0300965 v4l2_fh_init(&my_fh->fh, vfd);
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300966
967 ...
968
969 file->private_data = &my_fh->fh;
970 v4l2_fh_add(&my_fh->fh);
971 return 0;
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300972}
973
974int my_release(struct file *file)
975{
976 struct v4l2_fh *fh = file->private_data;
977 struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
978
979 ...
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300980 v4l2_fh_del(&my_fh->fh);
981 v4l2_fh_exit(&my_fh->fh);
982 kfree(my_fh);
983 return 0;
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300984}
Sakari Ailusdd966082010-03-27 10:58:24 -0300985
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300986Below is a short description of the v4l2_fh functions used:
987
Hans Verkuil98019f52011-06-18 05:13:55 -0300988void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
Hans Verkuil6e29ad52011-02-24 10:58:13 -0300989
990 Initialise the file handle. This *MUST* be performed in the driver's
991 v4l2_file_operations->open() handler.
992
993void v4l2_fh_add(struct v4l2_fh *fh)
994
995 Add a v4l2_fh to video_device file handle list. Must be called once the
996 file handle is completely initialized.
997
998void v4l2_fh_del(struct v4l2_fh *fh)
999
1000 Unassociate the file handle from video_device(). The file handle
1001 exit function may now be called.
1002
1003void v4l2_fh_exit(struct v4l2_fh *fh)
1004
1005 Uninitialise the file handle. After uninitialisation the v4l2_fh
1006 memory can be freed.
1007
1008
1009If struct v4l2_fh is not embedded, then you can use these helper functions:
1010
1011int v4l2_fh_open(struct file *filp)
1012
1013 This allocates a struct v4l2_fh, initializes it and adds it to the struct
1014 video_device associated with the file struct.
1015
1016int v4l2_fh_release(struct file *filp)
1017
1018 This deletes it from the struct video_device associated with the file
1019 struct, uninitialised the v4l2_fh and frees it.
1020
1021These two functions can be plugged into the v4l2_file_operation's open() and
1022release() ops.
1023
1024
1025Several drivers need to do something when the first file handle is opened and
1026when the last file handle closes. Two helper functions were added to check
1027whether the v4l2_fh struct is the only open filehandle of the associated
1028device node:
1029
1030int v4l2_fh_is_singular(struct v4l2_fh *fh)
1031
1032 Returns 1 if the file handle is the only open file handle, else 0.
1033
1034int v4l2_fh_is_singular_file(struct file *filp)
1035
1036 Same, but it calls v4l2_fh_is_singular with filp->private_data.
1037
1038
Sakari Ailusdd966082010-03-27 10:58:24 -03001039V4L2 events
1040-----------
1041
1042The V4L2 events provide a generic way to pass events to user space.
1043The driver must use v4l2_fh to be able to support V4L2 events.
1044
Hans Verkuil1de73102011-06-18 06:14:42 -03001045Events are defined by a type and an optional ID. The ID may refer to a V4L2
1046object such as a control ID. If unused, then the ID is 0.
1047
1048When the user subscribes to an event the driver will allocate a number of
1049kevent structs for that event. So every (type, ID) event tuple will have
1050its own set of kevent structs. This guarantees that if a driver is generating
1051lots of events of one type in a short time, then that will not overwrite
1052events of another type.
1053
1054But if you get more events of one type than the number of kevents that were
1055reserved, then the oldest event will be dropped and the new one added.
1056
1057Furthermore, the internal struct v4l2_subscribed_event has merge() and
1058replace() callbacks which drivers can set. These callbacks are called when
1059a new event is raised and there is no more room. The replace() callback
1060allows you to replace the payload of the old event with that of the new event,
1061merging any relevant data from the old payload into the new payload that
1062replaces it. It is called when this event type has only one kevent struct
1063allocated. The merge() callback allows you to merge the oldest event payload
1064into that of the second-oldest event payload. It is called when there are two
1065or more kevent structs allocated.
1066
1067This way no status information is lost, just the intermediate steps leading
1068up to that state.
1069
1070A good example of these replace/merge callbacks is in v4l2-event.c:
1071ctrls_replace() and ctrls_merge() callbacks for the control event.
1072
1073Note: these callbacks can be called from interrupt context, so they must be
1074fast.
1075
Sakari Ailusdd966082010-03-27 10:58:24 -03001076Useful functions:
1077
Hans de Goedec53c2542012-04-08 12:59:46 -03001078void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
Sakari Ailusdd966082010-03-27 10:58:24 -03001079
1080 Queue events to video device. The driver's only responsibility is to fill
1081 in the type and the data fields. The other fields will be filled in by
1082 V4L2.
1083
Hans de Goedec53c2542012-04-08 12:59:46 -03001084int v4l2_event_subscribe(struct v4l2_fh *fh,
1085 struct v4l2_event_subscription *sub, unsigned elems,
1086 const struct v4l2_subscribed_event_ops *ops)
Sakari Ailusdd966082010-03-27 10:58:24 -03001087
1088 The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
1089 is able to produce events with specified event id. Then it calls
Hans de Goedec53c2542012-04-08 12:59:46 -03001090 v4l2_event_subscribe() to subscribe the event.
Sakari Ailusdd966082010-03-27 10:58:24 -03001091
Hans de Goedec53c2542012-04-08 12:59:46 -03001092 The elems argument is the size of the event queue for this event. If it is 0,
1093 then the framework will fill in a default value (this depends on the event
1094 type).
1095
1096 The ops argument allows the driver to specify a number of callbacks:
1097 * add: called when a new listener gets added (subscribing to the same
1098 event twice will only cause this callback to get called once)
1099 * del: called when a listener stops listening
1100 * replace: replace event 'old' with event 'new'.
1101 * merge: merge event 'old' into event 'new'.
1102 All 4 callbacks are optional, if you don't want to specify any callbacks
1103 the ops argument itself maybe NULL.
1104
1105int v4l2_event_unsubscribe(struct v4l2_fh *fh,
1106 struct v4l2_event_subscription *sub)
Sakari Ailusdd966082010-03-27 10:58:24 -03001107
1108 vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
1109 v4l2_event_unsubscribe() directly unless it wants to be involved in
1110 unsubscription process.
1111
1112 The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
1113 drivers may want to handle this in a special way.
1114
Hans de Goedec53c2542012-04-08 12:59:46 -03001115int v4l2_event_pending(struct v4l2_fh *fh)
Sakari Ailusdd966082010-03-27 10:58:24 -03001116
1117 Returns the number of pending events. Useful when implementing poll.
1118
Sakari Ailusdd966082010-03-27 10:58:24 -03001119Events are delivered to user space through the poll system call. The driver
Hans Verkuil1de73102011-06-18 06:14:42 -03001120can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().
Sakari Ailusdd966082010-03-27 10:58:24 -03001121
1122There are standard and private events. New standard events must use the
1123smallest available event type. The drivers must allocate their events from
1124their own class starting from class base. Class base is
1125V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
1126The first event type in the class is reserved for future use, so the first
1127available event type is 'class base + 1'.
1128
1129An example on how the V4L2 events may be used can be found in the OMAP
Lad, Prabhakar83c73532012-09-14 05:17:52 -030011303 ISP driver (drivers/media/platform/omap3isp).
Guennadi Liakhovetskic67f1a32013-06-17 02:50:33 -03001131
jean-michel.hautbois@vodalys.com17e48462015-03-18 07:21:47 -03001132A subdev can directly send an event to the v4l2_device notify function with
1133V4L2_DEVICE_NOTIFY_EVENT. This allows the bridge to map the subdev that sends
1134the event to the video node(s) associated with the subdev that need to be
1135informed about such an event.
Guennadi Liakhovetskic67f1a32013-06-17 02:50:33 -03001136
1137V4L2 clocks
1138-----------
1139
1140Many subdevices, like camera sensors, TV decoders and encoders, need a clock
1141signal to be supplied by the system. Often this clock is supplied by the
1142respective bridge device. The Linux kernel provides a Common Clock Framework for
1143this purpose. However, it is not (yet) available on all architectures. Besides,
1144the nature of the multi-functional (clock, data + synchronisation, I2C control)
1145connection of subdevices to the system might impose special requirements on the
1146clock API usage. E.g. V4L2 has to support clock provider driver unregistration
1147while a subdevice driver is holding a reference to the clock. For these reasons
1148a V4L2 clock helper API has been developed and is provided to bridge and
1149subdevice drivers.
1150
1151The API consists of two parts: two functions to register and unregister a V4L2
1152clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control
1153a clock object, similar to the respective generic clock API calls:
1154v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(),
1155v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide
1156clock operations that will be called when clock users invoke respective API
1157methods.
1158
1159It is expected that once the CCF becomes available on all relevant
1160architectures this API will be removed.