Documentation/video4linux/v4l2-framework.txt

9 ------------
13 /dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input
20 called 'sub-devices'.
27 connecting to sub-devices themselves. Some of this is quite complicated
39 ---------------------
45 2) A way of initializing and commanding sub-devices (if any).
48    and keeping track of device-node specific data.
50 4) Filehandle-specific structs containing per-filehandle data;
58       +-sub-device instances
60       \-V4L2 device nodes
62 	  \-filehandle instances
66 --------------------------
70 sub-device instances, the video_device struct stores V4L2 device node data
75 driver sets the struct v4l2_device mdev field, sub-devices and video nodes
80 ------------------
82 Each device instance is represented by a struct v4l2_device (v4l2-device.h).
83 Very simple devices can just allocate this struct, but most of the time you
90 Registration will initialize the v4l2_device struct. If the dev->driver_data
94 dev->driver_data manually to point to the driver-specific device structure
100 If v4l2_dev->name is empty then it will be set to a value derived from dev
103 you *must* setup v4l2_dev->name before calling v4l2_device_register.
106 a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
107 etc. If the name ends with a digit, then it will insert a dash: cx18-0,
108 cx18-1, etc. This function returns the instance number.
115 You can also supply a notify() callback that can be called by sub-devices to
116 notify you of events. Whether you need to set this depends on the sub-device.
117 Any notifications a sub-device supports must be defined in a header in
124 If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
140 hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
181 	state->instance = atomic_inc_return(&drv_instance) - 1;
201 ------------------
203 Many drivers need to communicate with sub-devices. These devices can do all
205 encoding or decoding. For webcams common sub-devices are sensors and camera
209 driver with a consistent interface to these sub-devices the v4l2_subdev struct
210 (v4l2-subdev.h) was created.
212 Each sub-device driver must have a v4l2_subdev struct. This struct can be
213 stand-alone for simple sub-devices or it might be embedded in a larger struct
214 if more state information needs to be stored. Usually there is a low-level
218 from a v4l2_subdev to the actual low-level bus-specific device data.
220 You also need a way to go from the low-level struct to v4l2_subdev. For the
224 Bridges might also need to store per-subdev private data, such as a pointer to
225 bridge-specific per-subdev private data. The v4l2_subdev structure provides
229 From the bridge driver perspective you load the sub-device module and somehow
232 Helper functions exists for sub-devices on an I2C bus that do most of this
235 Each v4l2_subdev contains function pointers that sub-device drivers can
236 implement (or leave NULL if it is not applicable). Since sub-devices can do
241 The top-level ops struct contains pointers to the category ops structs, which
273 depending on the sub-device. E.g. a video device is unlikely to support the
279 A sub-device driver initializes the v4l2_subdev struct using:
283 Afterwards you need to initialize subdev->name with a unique name and set the
290 	struct media_pad *pads = &my_sd->pads;
293 	err = media_entity_init(&sd->entity, npads, pads, 0);
302 Don't forget to cleanup the media entity before the sub-device is destroyed:
304 	media_entity_cleanup(&sd->entity);
312 After this function was called successfully the subdev->dev field points to
315 If the v4l2_device parent device has a non-NULL mdev field, the sub-device
318 You can unregister a sub-device using:
322 Afterwards the subdev module can be unloaded and sd->dev == NULL.
326 	err = sd->ops->core->g_chip_ident(sd, &chip);
332 The macro will to the right NULL pointer checks and returns -ENODEV if subdev
333 is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_chip_ident is
334 NULL, or the actual result of the subdev->ops->core->g_chip_ident ops.
336 It is also possible to call all or a subset of the sub-devices:
345 Any error except -ENOIOCTLCMD will exit the loop with that error. If no
346 errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
349 called. If non-zero, then only those whose group ID match that value will
350 be called. Before a bridge driver registers a subdev it can set sd->grp_id
352 bridge driver and the sub-device driver will never modify or use it.
362 If the sub-device needs to notify its v4l2_device parent of an event, then
364 whether there is a notify() callback defined and returns -ENODEV if not.
374 V4L2 sub-device userspace API
375 -----------------------------
378 sub-devices can also be controlled directly by userspace applications.
380 Device nodes named v4l-subdevX can be created in /dev to access sub-devices
381 directly. If a sub-device supports direct userspace configuration it must set
384 After registering sub-devices, the v4l2_device driver can create device nodes
385 for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
387 removed when sub-devices are unregistered.
401 	controls implemented in the sub-device. Depending on the driver, those
411 	events generated by the sub-device. Depending on the driver, those
414 	Sub-device drivers that want to use events need to set the
417 	sub-device. After registration events can be queued as usual on the
425 	All ioctls not in the above list are passed directly to the sub-device
429 I2C sub-device drivers
430 ----------------------
433 ease the use of these drivers (v4l2-common.h).
437 I2C device instance. Very simple devices have no state struct and in that case
450 	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
472 is called. This will unregister the sub-device from the bridge driver. It is
473 safe to call this even if the sub-device was never registered.
493 only used if the previous argument is 0. A non-zero argument means that you
510 0 then that will be used (non-probing variant), otherwise the probed_addrs
527 -------------------
530 video_device struct (v4l2-dev.h). This struct can either be allocated
538 		return -ENOMEM;
540 	vdev->release = video_device_release;
545 	struct video_device *vdev = &my_vdev->vdev;
547 	vdev->release = my_vdev_release;
557 - v4l2_dev: set to the v4l2_device parent device.
558 - name: set to something descriptive and unique.
559 - fops: set to the v4l2_file_operations struct.
560 - ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
563 - lock: leave to NULL if you want to do all the locking in the driver.
567 - prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
571 - parent: you only set this if v4l2_device was registered with NULL as
580 - flags: optional. Set to V4L2_FL_USE_FH_PRIO if you want to let the framework
597 	struct media_pad *pad = &my_vdev->pad;
600 	err = media_entity_init(&vdev->entity, 1, pad, 0);
609 --------------------------------
612 will be either a top-level mutex or a mutex per device node. If you want
613 finer-grained locking then you have to set it to NULL and do you own locking.
616 your driver has high-latency operations (for example, changing the exposure
619 the device while waiting for the high-latency command to finish.
637 -------------------------
642 	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
648 If the v4l2_device parent device has a non-NULL mdev field, the video device
659 device node number used (i.e. the X in videoX). Normally you will pass -1
668 Another use-case is if a driver creates many devices. In that case it can
694 - vfl_type: the device type passed to video_register_device.
695 - minor: the assigned device minor number.
696 - num: the device node number (i.e. the X in videoX).
697 - index: the device index number.
701 video_device was embedded in it. The vdev->release() callback will never
707 --------------------
723 When the last user of the video device node exits, then the vdev->release()
729 	media_entity_cleanup(&vdev->entity);
735 -----------------------------
739 - file/video_device private data
761 struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
763 - Device node name
775 -----------------------------
781 scatter/gather method (videobuf-dma-sg), DMA with linear access
782 (videobuf-dma-contig), and vmalloced buffers, mostly used on USB drivers
783 (videobuf-vmalloc).
789 --------------
797 whether a driver uses v4l2_fh as its file->private_data pointer by
798 testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
802 structure and file->private_data is set to it in the driver's open
831 	v4l2_fh_init(&my_fh->fh, vfd);
835 	file->private_data = &my_fh->fh;
836 	v4l2_fh_add(&my_fh->fh);
842 	struct v4l2_fh *fh = file->private_data;
846 	v4l2_fh_del(&my_fh->fh);
847 	v4l2_fh_exit(&my_fh->fh);
857   v4l2_file_operations->open() handler.
902   Same, but it calls v4l2_fh_is_singular with filp->private_data.
906 -----------
930 into that of the second-oldest event payload. It is called when there are two
936 A good example of these replace/merge callbacks is in v4l2-event.c:
944 - v4l2_event_queue()
950 - v4l2_event_subscribe()
952   The video_device->ioctl_ops->vidioc_subscribe_event must check the driver
958 - v4l2_event_unsubscribe()
967 - v4l2_event_pending()
972 can use v4l2_fh->wait (a wait_queue_head_t) as the argument for poll_wait().