blob: f22f35c271f38d34fda0c19d8942b536e2fc95d9 [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
37
38Structure of a driver
39---------------------
40
41All drivers have the following structure:
42
431) A struct for each device instance containing the device state.
44
452) A way of initializing and commanding sub-devices (if any).
46
Hans Verkuilf44026d2010-08-06 12:52:43 -0300473) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX)
48 and keeping track of device-node specific data.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030049
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300504) Filehandle-specific structs containing per-filehandle data;
51
525) video buffer handling.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030053
54This is a rough schematic of how it all relates:
55
56 device instances
57 |
58 +-sub-device instances
59 |
60 \-V4L2 device nodes
61 |
62 \-filehandle instances
63
64
65Structure of the framework
66--------------------------
67
68The framework closely resembles the driver structure: it has a v4l2_device
69struct for the device instance data, a v4l2_subdev struct to refer to
70sub-device instances, the video_device struct stores V4L2 device node data
71and in the future a v4l2_fh struct will keep track of filehandle instances
72(this is not yet implemented).
73
74
75struct v4l2_device
76------------------
77
78Each device instance is represented by a struct v4l2_device (v4l2-device.h).
79Very simple devices can just allocate this struct, but most of the time you
80would embed this struct inside a larger struct.
81
82You must register the device instance:
83
84 v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
85
86Registration will initialize the v4l2_device struct and link dev->driver_data
Hans Verkuil3a63e4492009-02-14 11:54:23 -030087to v4l2_dev. If v4l2_dev->name is empty then it will be set to a value derived
88from dev (driver name followed by the bus_id, to be precise). If you set it
89up before calling v4l2_device_register then it will be untouched. If dev is
90NULL, then you *must* setup v4l2_dev->name before calling v4l2_device_register.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -030091
Hans Verkuil102e7812009-05-02 10:12:50 -030092You can use v4l2_device_set_name() to set the name based on a driver name and
93a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
94etc. If the name ends with a digit, then it will insert a dash: cx18-0,
95cx18-1, etc. This function returns the instance number.
96
Hans Verkuila47ddf12008-12-19 10:20:22 -030097The first 'dev' argument is normally the struct device pointer of a pci_dev,
Janne Grunau073d6962009-04-01 08:30:06 -030098usb_interface or platform_device. It is rare for dev to be NULL, but it happens
Hans Verkuil00575962009-03-13 10:03:04 -030099with ISA devices or when one device creates multiple PCI devices, thus making
100it impossible to associate v4l2_dev with a particular parent.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300101
Hans Verkuil98ec6332009-03-08 17:02:10 -0300102You can also supply a notify() callback that can be called by sub-devices to
103notify you of events. Whether you need to set this depends on the sub-device.
104Any notifications a sub-device supports must be defined in a header in
105include/media/<subdevice>.h.
106
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300107You unregister with:
108
109 v4l2_device_unregister(struct v4l2_device *v4l2_dev);
110
111Unregistering will also automatically unregister all subdevs from the device.
112
Hans Verkuilae6cfaa2009-03-14 08:28:45 -0300113If you have a hotpluggable device (e.g. a USB device), then when a disconnect
114happens the parent device becomes invalid. Since v4l2_device has a pointer to
115that parent device it has to be cleared as well to mark that the parent is
116gone. To do this call:
117
118 v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
119
120This does *not* unregister the subdevs, so you still need to call the
121v4l2_device_unregister() function for that. If your driver is not hotpluggable,
122then there is no need to call v4l2_device_disconnect().
123
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300124Sometimes you need to iterate over all devices registered by a specific
125driver. This is usually the case if multiple device drivers use the same
126hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
127hardware. The same is true for alsa drivers for example.
128
129You can iterate over all registered devices as follows:
130
131static int callback(struct device *dev, void *p)
132{
133 struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
134
135 /* test if this device was inited */
136 if (v4l2_dev == NULL)
137 return 0;
138 ...
139 return 0;
140}
141
142int iterate(void *p)
143{
144 struct device_driver *drv;
145 int err;
146
147 /* Find driver 'ivtv' on the PCI bus.
148 pci_bus_type is a global. For USB busses use usb_bus_type. */
149 drv = driver_find("ivtv", &pci_bus_type);
150 /* iterate over all ivtv device instances */
151 err = driver_for_each_device(drv, NULL, p, callback);
152 put_driver(drv);
153 return err;
154}
155
156Sometimes you need to keep a running counter of the device instance. This is
157commonly used to map a device instance to an index of a module option array.
158
159The recommended approach is as follows:
160
161static atomic_t drv_instance = ATOMIC_INIT(0);
162
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300163static int __devinit drv_probe(struct pci_dev *pdev,
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300164 const struct pci_device_id *pci_id)
165{
166 ...
167 state->instance = atomic_inc_return(&drv_instance) - 1;
168}
169
170
171struct v4l2_subdev
172------------------
173
174Many drivers need to communicate with sub-devices. These devices can do all
175sort of tasks, but most commonly they handle audio and/or video muxing,
176encoding or decoding. For webcams common sub-devices are sensors and camera
177controllers.
178
179Usually these are I2C devices, but not necessarily. In order to provide the
180driver with a consistent interface to these sub-devices the v4l2_subdev struct
181(v4l2-subdev.h) was created.
182
183Each sub-device driver must have a v4l2_subdev struct. This struct can be
184stand-alone for simple sub-devices or it might be embedded in a larger struct
185if more state information needs to be stored. Usually there is a low-level
186device struct (e.g. i2c_client) that contains the device data as setup
187by the kernel. It is recommended to store that pointer in the private
188data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
189from a v4l2_subdev to the actual low-level bus-specific device data.
190
191You also need a way to go from the low-level struct to v4l2_subdev. For the
192common i2c_client struct the i2c_set_clientdata() call is used to store a
193v4l2_subdev pointer, for other busses you may have to use other methods.
194
Laurent Pinchart692d55222010-07-30 17:24:55 -0300195Bridges might also need to store per-subdev private data, such as a pointer to
196bridge-specific per-subdev private data. The v4l2_subdev structure provides
197host private data for that purpose that can be accessed with
198v4l2_get_subdev_hostdata() and v4l2_set_subdev_hostdata().
199
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300200From the bridge driver perspective you load the sub-device module and somehow
201obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
202i2c_get_clientdata(). For other busses something similar needs to be done.
203Helper functions exists for sub-devices on an I2C bus that do most of this
204tricky work for you.
205
206Each v4l2_subdev contains function pointers that sub-device drivers can
207implement (or leave NULL if it is not applicable). Since sub-devices can do
208so many different things and you do not want to end up with a huge ops struct
209of which only a handful of ops are commonly implemented, the function pointers
210are sorted according to category and each category has its own ops struct.
211
212The top-level ops struct contains pointers to the category ops structs, which
213may be NULL if the subdev driver does not support anything from that category.
214
215It looks like this:
216
217struct v4l2_subdev_core_ops {
Hans Verkuilaecde8b52008-12-30 07:14:19 -0300218 int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300219 int (*log_status)(struct v4l2_subdev *sd);
220 int (*init)(struct v4l2_subdev *sd, u32 val);
221 ...
222};
223
224struct v4l2_subdev_tuner_ops {
225 ...
226};
227
228struct v4l2_subdev_audio_ops {
229 ...
230};
231
232struct v4l2_subdev_video_ops {
233 ...
234};
235
236struct v4l2_subdev_ops {
237 const struct v4l2_subdev_core_ops *core;
238 const struct v4l2_subdev_tuner_ops *tuner;
239 const struct v4l2_subdev_audio_ops *audio;
240 const struct v4l2_subdev_video_ops *video;
241};
242
243The core ops are common to all subdevs, the other categories are implemented
244depending on the sub-device. E.g. a video device is unlikely to support the
245audio ops and vice versa.
246
247This setup limits the number of function pointers while still making it easy
248to add new ops and categories.
249
250A sub-device driver initializes the v4l2_subdev struct using:
251
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300252 v4l2_subdev_init(sd, &ops);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300253
254Afterwards you need to initialize subdev->name with a unique name and set the
255module owner. This is done for you if you use the i2c helper functions.
256
257A device (bridge) driver needs to register the v4l2_subdev with the
258v4l2_device:
259
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300260 int err = v4l2_device_register_subdev(v4l2_dev, sd);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300261
262This can fail if the subdev module disappeared before it could be registered.
263After this function was called successfully the subdev->dev field points to
264the v4l2_device.
265
266You can unregister a sub-device using:
267
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300268 v4l2_device_unregister_subdev(sd);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300269
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300270Afterwards the subdev module can be unloaded and sd->dev == NULL.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300271
272You can call an ops function either directly:
273
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300274 err = sd->ops->core->g_chip_ident(sd, &chip);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300275
276but it is better and easier to use this macro:
277
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300278 err = v4l2_subdev_call(sd, core, g_chip_ident, &chip);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300279
280The macro will to the right NULL pointer checks and returns -ENODEV if subdev
281is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_chip_ident is
282NULL, or the actual result of the subdev->ops->core->g_chip_ident ops.
283
284It is also possible to call all or a subset of the sub-devices:
285
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300286 v4l2_device_call_all(v4l2_dev, 0, core, g_chip_ident, &chip);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300287
288Any subdev that does not support this ops is skipped and error results are
289ignored. If you want to check for errors use this:
290
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300291 err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300292
293Any error except -ENOIOCTLCMD will exit the loop with that error. If no
294errors (except -ENOIOCTLCMD) occured, then 0 is returned.
295
296The second argument to both calls is a group ID. If 0, then all subdevs are
297called. If non-zero, then only those whose group ID match that value will
Hans Verkuilb0167602009-02-14 12:00:53 -0300298be called. Before a bridge driver registers a subdev it can set sd->grp_id
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300299to whatever value it wants (it's 0 by default). This value is owned by the
300bridge driver and the sub-device driver will never modify or use it.
301
302The group ID gives the bridge driver more control how callbacks are called.
303For example, there may be multiple audio chips on a board, each capable of
304changing the volume. But usually only one will actually be used when the
305user want to change the volume. You can set the group ID for that subdev to
306e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
307v4l2_device_call_all(). That ensures that it will only go to the subdev
308that needs it.
309
Hans Verkuil98ec6332009-03-08 17:02:10 -0300310If the sub-device needs to notify its v4l2_device parent of an event, then
311it can call v4l2_subdev_notify(sd, notification, arg). This macro checks
312whether there is a notify() callback defined and returns -ENODEV if not.
313Otherwise the result of the notify() call is returned.
314
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300315The advantage of using v4l2_subdev is that it is a generic struct and does
316not contain any knowledge about the underlying hardware. So a driver might
317contain several subdevs that use an I2C bus, but also a subdev that is
318controlled through GPIO pins. This distinction is only relevant when setting
319up the device, but once the subdev is registered it is completely transparent.
320
321
322I2C sub-device drivers
323----------------------
324
325Since these drivers are so common, special helper functions are available to
326ease the use of these drivers (v4l2-common.h).
327
328The recommended method of adding v4l2_subdev support to an I2C driver is to
329embed the v4l2_subdev struct into the state struct that is created for each
330I2C device instance. Very simple devices have no state struct and in that case
331you can just create a v4l2_subdev directly.
332
333A typical state struct would look like this (where 'chipname' is replaced by
334the name of the chip):
335
336struct chipname_state {
337 struct v4l2_subdev sd;
338 ... /* additional state fields */
339};
340
341Initialize the v4l2_subdev struct as follows:
342
343 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
344
345This function will fill in all the fields of v4l2_subdev and ensure that the
346v4l2_subdev and i2c_client both point to one another.
347
348You should also add a helper inline function to go from a v4l2_subdev pointer
349to a chipname_state struct:
350
351static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
352{
353 return container_of(sd, struct chipname_state, sd);
354}
355
356Use this to go from the v4l2_subdev struct to the i2c_client struct:
357
358 struct i2c_client *client = v4l2_get_subdevdata(sd);
359
360And this to go from an i2c_client to a v4l2_subdev struct:
361
362 struct v4l2_subdev *sd = i2c_get_clientdata(client);
363
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300364Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
365is called. This will unregister the sub-device from the bridge driver. It is
366safe to call this even if the sub-device was never registered.
367
Hans Verkuilf5360bd2009-01-15 06:09:05 -0300368You need to do this because when the bridge driver destroys the i2c adapter
369the remove() callbacks are called of the i2c devices on that adapter.
370After that the corresponding v4l2_subdev structures are invalid, so they
371have to be unregistered first. Calling v4l2_device_unregister_subdev(sd)
372from the remove() callback ensures that this is always done correctly.
373
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300374
375The bridge driver also has some helper functions it can use:
376
Hans Verkuile6574f22009-04-01 03:57:53 -0300377struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
Hans Verkuil53dacb12009-08-10 02:49:08 -0300378 "module_foo", "chipid", 0x36, NULL);
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300379
380This loads the given module (can be NULL if no module needs to be loaded) and
381calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
Hans Verkuile6574f22009-04-01 03:57:53 -0300382If all goes well, then it registers the subdev with the v4l2_device.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300383
Hans Verkuil53dacb12009-08-10 02:49:08 -0300384You can also use the last argument of v4l2_i2c_new_subdev() to pass an array
385of possible I2C addresses that it should probe. These probe addresses are
386only used if the previous argument is 0. A non-zero argument means that you
387know the exact i2c address so in that case no probing will take place.
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300388
389Both functions return NULL if something went wrong.
390
Hans Verkuil53dacb12009-08-10 02:49:08 -0300391Note that the chipid you pass to v4l2_i2c_new_subdev() is usually
Hans Verkuil2c792522009-03-12 18:34:19 -0300392the same as the module name. It allows you to specify a chip variant, e.g.
393"saa7114" or "saa7115". In general though the i2c driver autodetects this.
394The use of chipid is something that needs to be looked at more closely at a
395later date. It differs between i2c drivers and as such can be confusing.
396To see which chip variants are supported you can look in the i2c driver code
397for the i2c_device_id table. This lists all the possibilities.
398
Hans Verkuil2c0b19a2009-06-09 17:29:29 -0300399There are two more helper functions:
400
401v4l2_i2c_new_subdev_cfg: this function adds new irq and platform_data
402arguments and has both 'addr' and 'probed_addrs' arguments: if addr is not
4030 then that will be used (non-probing variant), otherwise the probed_addrs
404are probed.
405
406For example: this will probe for address 0x10:
407
408struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
409 "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
410
411v4l2_i2c_new_subdev_board uses an i2c_board_info struct which is passed
412to the i2c driver and replaces the irq, platform_data and addr arguments.
413
414If the subdev supports the s_config core ops, then that op is called with
415the irq and platform_data arguments after the subdev was setup. The older
416v4l2_i2c_new_(probed_)subdev functions will call s_config as well, but with
417irq set to 0 and platform_data set to NULL.
418
Hans Verkuil2a1fcdf2008-11-29 21:36:58 -0300419struct video_device
420-------------------
421
Hans Verkuila47ddf12008-12-19 10:20:22 -0300422The actual device nodes in the /dev directory are created using the
423video_device struct (v4l2-dev.h). This struct can either be allocated
424dynamically or embedded in a larger struct.
425
426To allocate it dynamically use:
427
428 struct video_device *vdev = video_device_alloc();
429
430 if (vdev == NULL)
431 return -ENOMEM;
432
433 vdev->release = video_device_release;
434
435If you embed it in a larger struct, then you must set the release()
436callback to your own function:
437
438 struct video_device *vdev = &my_vdev->vdev;
439
440 vdev->release = my_vdev_release;
441
442The release callback must be set and it is called when the last user
443of the video device exits.
444
445The default video_device_release() callback just calls kfree to free the
446allocated memory.
447
448You should also set these fields:
449
Hans Verkuildfa9a5a2008-12-23 12:17:23 -0300450- v4l2_dev: set to the v4l2_device parent device.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300451- name: set to something descriptive and unique.
Hans Verkuilc7dd09d2008-12-23 13:42:25 -0300452- fops: set to the v4l2_file_operations struct.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300453- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
454 (highly recommended to use this and it might become compulsory in the
455 future!), then set this to your v4l2_ioctl_ops struct.
Hans Verkuilee6869a2010-09-26 08:47:38 -0300456- lock: leave to NULL if you want to do all the locking in the driver.
457 Otherwise you give it a pointer to a struct mutex_lock and before any
458 of the v4l2_file_operations is called this lock will be taken by the
459 core and released afterwards.
Hans Verkuil00575962009-03-13 10:03:04 -0300460- parent: you only set this if v4l2_device was registered with NULL as
461 the parent device struct. This only happens in cases where one hardware
462 device has multiple PCI devices that all share the same v4l2_device core.
463
464 The cx88 driver is an example of this: one core v4l2_device struct, but
465 it is used by both an raw video PCI device (cx8800) and a MPEG PCI device
466 (cx8802). Since the v4l2_device cannot be associated with a particular
467 PCI device it is setup without a parent device. But when the struct
468 video_device is setup you do know which parent PCI device to use.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300469
Hans Verkuilc7dd09d2008-12-23 13:42:25 -0300470If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or
471.ioctl to video_ioctl2 in your v4l2_file_operations struct.
472
473The v4l2_file_operations struct is a subset of file_operations. The main
474difference is that the inode argument is omitted since it is never used.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300475
Hans Verkuilee6869a2010-09-26 08:47:38 -0300476v4l2_file_operations and locking
477--------------------------------
478
479You can set a pointer to a mutex_lock in struct video_device. Usually this
480will be either a top-level mutex or a mutex per device node. If you want
481finer-grained locking then you have to set it to NULL and do you own locking.
482
483If a lock is specified then all file operations will be serialized on that
484lock. If you use videobuf then you must pass the same lock to the videobuf
485queue initialize function: if videobuf has to wait for a frame to arrive, then
486it will temporarily unlock the lock and relock it afterwards. If your driver
487also waits in the code, then you should do the same to allow other processes
488to access the device node while the first process is waiting for something.
489
490The implementation of a hotplug disconnect should also take the lock before
Hans Verkuil9c84d892010-10-11 12:36:37 -0300491calling v4l2_device_disconnect.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300492
493video_device registration
494-------------------------
495
496Next you register the video device: this will create the character device
497for you.
498
499 err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
500 if (err) {
Hans Verkuil50a2a8b2008-12-22 09:13:11 -0300501 video_device_release(vdev); /* or kfree(my_vdev); */
Hans Verkuila47ddf12008-12-19 10:20:22 -0300502 return err;
503 }
504
505Which device is registered depends on the type argument. The following
506types exist:
507
508VFL_TYPE_GRABBER: videoX for video input/output devices
509VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
510VFL_TYPE_RADIO: radioX for radio tuners
Hans Verkuila47ddf12008-12-19 10:20:22 -0300511
512The last argument gives you a certain amount of control over the device
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300513device node number used (i.e. the X in videoX). Normally you will pass -1
514to let the v4l2 framework pick the first free number. But sometimes users
515want to select a specific node number. It is common that drivers allow
516the user to select a specific device node number through a driver module
517option. That number is then passed to this function and video_register_device
518will attempt to select that device node number. If that number was already
519in use, then the next free device node number will be selected and it
520will send a warning to the kernel log.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300521
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300522Another use-case is if a driver creates many devices. In that case it can
523be useful to place different video devices in separate ranges. For example,
524video capture devices start at 0, video output devices start at 16.
Hans Verkuil22e22122009-09-06 07:13:14 -0300525So you can use the last argument to specify a minimum device node number
526and the v4l2 framework will try to pick the first free number that is equal
Hans Verkuila47ddf12008-12-19 10:20:22 -0300527or higher to what you passed. If that fails, then it will just pick the
528first free number.
529
Hans Verkuil6b5270d2009-09-06 07:54:00 -0300530Since in this case you do not care about a warning about not being able
531to select the specified device node number, you can call the function
532video_register_device_no_warn() instead.
533
Hans Verkuila47ddf12008-12-19 10:20:22 -0300534Whenever a device node is created some attributes are also created for you.
535If you look in /sys/class/video4linux you see the devices. Go into e.g.
536video0 and you will see 'name' and 'index' attributes. The 'name' attribute
Hans Verkuil7ae0cd92009-06-19 11:32:56 -0300537is the 'name' field of the video_device struct.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300538
Hans Verkuil7ae0cd92009-06-19 11:32:56 -0300539The 'index' attribute is the index of the device node: for each call to
540video_register_device() the index is just increased by 1. The first video
541device node you register always starts with index 0.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300542
543Users can setup udev rules that utilize the index attribute to make fancy
544device names (e.g. 'mpegX' for MPEG video capture device nodes).
545
546After the device was successfully registered, then you can use these fields:
547
548- vfl_type: the device type passed to video_register_device.
549- minor: the assigned device minor number.
Hans Verkuil22e22122009-09-06 07:13:14 -0300550- num: the device node number (i.e. the X in videoX).
Hans Verkuil7ae0cd92009-06-19 11:32:56 -0300551- index: the device index number.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300552
553If the registration failed, then you need to call video_device_release()
554to free the allocated video_device struct, or free your own struct if the
555video_device was embedded in it. The vdev->release() callback will never
556be called if the registration failed, nor should you ever attempt to
557unregister the device if the registration failed.
558
559
560video_device cleanup
561--------------------
562
563When the video device nodes have to be removed, either during the unload
564of the driver or because the USB device was disconnected, then you should
565unregister them:
566
567 video_unregister_device(vdev);
568
569This will remove the device nodes from sysfs (causing udev to remove them
570from /dev).
571
Hans Verkuildd1ad942010-04-06 11:44:39 -0300572After video_unregister_device() returns no new opens can be done. However,
573in the case of USB devices some application might still have one of these
Hans Verkuild69f2712010-09-26 08:16:56 -0300574device nodes open. So after the unregister all file operations (except
575release, of course) will return an error as well.
Hans Verkuila47ddf12008-12-19 10:20:22 -0300576
577When the last user of the video device node exits, then the vdev->release()
578callback is called and you can do the final cleanup there.
579
580
581video_device helper functions
582-----------------------------
583
584There are a few useful helper functions:
585
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300586- file/video_device private data
587
Hans Verkuila47ddf12008-12-19 10:20:22 -0300588You can set/get driver private data in the video_device struct using:
589
Hans Verkuil89aec3e2009-02-07 07:07:04 -0300590void *video_get_drvdata(struct video_device *vdev);
591void video_set_drvdata(struct video_device *vdev, void *data);
Hans Verkuila47ddf12008-12-19 10:20:22 -0300592
593Note that you can safely call video_set_drvdata() before calling
594video_register_device().
595
596And this function:
597
598struct video_device *video_devdata(struct file *file);
599
600returns the video_device belonging to the file struct.
601
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300602The video_drvdata function combines video_get_drvdata with video_devdata:
Hans Verkuila47ddf12008-12-19 10:20:22 -0300603
604void *video_drvdata(struct file *file);
605
606You can go from a video_device struct to the v4l2_device struct using:
607
Hans Verkuildfa9a5a2008-12-23 12:17:23 -0300608struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300609
Laurent Pincharteac8ea52009-11-27 13:56:50 -0300610- Device node name
611
612The video_device node kernel name can be retrieved using
613
614const char *video_device_node_name(struct video_device *vdev);
615
616The name is used as a hint by userspace tools such as udev. The function
617should be used where possible instead of accessing the video_device::num and
618video_device::minor fields.
619
620
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300621video buffer helper functions
622-----------------------------
623
Jonathan Corbet4b586a32010-02-22 17:47:46 -0300624The v4l2 core API provides a set of standard methods (called "videobuf")
625for dealing with video buffers. Those methods allow a driver to implement
626read(), mmap() and overlay() in a consistent way. There are currently
627methods for using video buffers on devices that supports DMA with
628scatter/gather method (videobuf-dma-sg), DMA with linear access
629(videobuf-dma-contig), and vmalloced buffers, mostly used on USB drivers
630(videobuf-vmalloc).
Mauro Carvalho Chehab44061c02009-02-14 07:29:07 -0300631
Jonathan Corbet4b586a32010-02-22 17:47:46 -0300632Please see Documentation/video4linux/videobuf for more information on how
633to use the videobuf layer.
Sakari Ailus6cd84b72010-03-20 18:28:48 -0300634
635struct v4l2_fh
636--------------
637
638struct v4l2_fh provides a way to easily keep file handle specific data
639that is used by the V4L2 framework. Using v4l2_fh is optional for
640drivers.
641
642The users of v4l2_fh (in the V4L2 framework, not the driver) know
643whether a driver uses v4l2_fh as its file->private_data pointer by
644testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags.
645
646Useful functions:
647
648- v4l2_fh_init()
649
650 Initialise the file handle. This *MUST* be performed in the driver's
651 v4l2_file_operations->open() handler.
652
653- v4l2_fh_add()
654
655 Add a v4l2_fh to video_device file handle list. May be called after
656 initialising the file handle.
657
658- v4l2_fh_del()
659
660 Unassociate the file handle from video_device(). The file handle
661 exit function may now be called.
662
663- v4l2_fh_exit()
664
665 Uninitialise the file handle. After uninitialisation the v4l2_fh
666 memory can be freed.
667
668struct v4l2_fh is allocated as a part of the driver's own file handle
669structure and is set to file->private_data in the driver's open
670function by the driver. Drivers can extract their own file handle
671structure by using the container_of macro. Example:
672
673struct my_fh {
674 int blah;
675 struct v4l2_fh fh;
676};
677
678...
679
680int my_open(struct file *file)
681{
682 struct my_fh *my_fh;
683 struct video_device *vfd;
684 int ret;
685
686 ...
687
688 ret = v4l2_fh_init(&my_fh->fh, vfd);
689 if (ret)
690 return ret;
691
692 v4l2_fh_add(&my_fh->fh);
693
694 file->private_data = &my_fh->fh;
695
696 ...
697}
698
699int my_release(struct file *file)
700{
701 struct v4l2_fh *fh = file->private_data;
702 struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
703
704 ...
705}
Sakari Ailusdd966082010-03-27 10:58:24 -0300706
707V4L2 events
708-----------
709
710The V4L2 events provide a generic way to pass events to user space.
711The driver must use v4l2_fh to be able to support V4L2 events.
712
713Useful functions:
714
715- v4l2_event_alloc()
716
717 To use events, the driver must allocate events for the file handle. By
718 calling the function more than once, the driver may assure that at least n
719 events in total have been allocated. The function may not be called in
720 atomic context.
721
722- v4l2_event_queue()
723
724 Queue events to video device. The driver's only responsibility is to fill
725 in the type and the data fields. The other fields will be filled in by
726 V4L2.
727
728- v4l2_event_subscribe()
729
730 The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
731 is able to produce events with specified event id. Then it calls
732 v4l2_event_subscribe() to subscribe the event.
733
734- v4l2_event_unsubscribe()
735
736 vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use
737 v4l2_event_unsubscribe() directly unless it wants to be involved in
738 unsubscription process.
739
740 The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The
741 drivers may want to handle this in a special way.
742
743- v4l2_event_pending()
744
745 Returns the number of pending events. Useful when implementing poll.
746
747Drivers do not initialise events directly. The events are initialised
748through v4l2_fh_init() if video_device->ioctl_ops->vidioc_subscribe_event is
749non-NULL. This *MUST* be performed in the driver's
750v4l2_file_operations->open() handler.
751
752Events are delivered to user space through the poll system call. The driver
753can use v4l2_fh->events->wait wait_queue_head_t as the argument for
754poll_wait().
755
756There are standard and private events. New standard events must use the
757smallest available event type. The drivers must allocate their events from
758their own class starting from class base. Class base is
759V4L2_EVENT_PRIVATE_START + n * 1000 where n is the lowest available number.
760The first event type in the class is reserved for future use, so the first
761available event type is 'class base + 1'.
762
763An example on how the V4L2 events may be used can be found in the OMAP
7643 ISP driver available at <URL:http://gitorious.org/omap3camera> as of
765writing this.