state->instance = atomic_inc_return(&drv_instance) - 1;
}
+If you have multiple device nodes then it can be difficult to know when it is
+safe to unregister v4l2_device. For this purpose v4l2_device has refcounting
+support. The refcount is increased whenever video_register_device is called and
+it is decreased whenever that device node is released. When the refcount reaches
+zero, then the v4l2_device release() callback is called. You can do your final
+cleanup there.
+
+If other device nodes (e.g. ALSA) are created, then you can increase and
+decrease the refcount manually as well by calling:
+
+void v4l2_device_get(struct v4l2_device *v4l2_dev);
+
+or:
+
+int v4l2_device_put(struct v4l2_device *v4l2_dev);
struct v4l2_subdev
------------------
err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip);
Any error except -ENOIOCTLCMD will exit the loop with that error. If no
-errors (except -ENOIOCTLCMD) occured, then 0 is returned.
+errors (except -ENOIOCTLCMD) occurred, then 0 is returned.
The second argument to both calls is a group ID. If 0, then all subdevs are
called. If non-zero, then only those whose group ID match that value will
Otherwise you give it a pointer to a struct mutex_lock and before any
of the v4l2_file_operations is called this lock will be taken by the
core and released afterwards.
+- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
+ If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
+ If you want to have a separate priority state per (group of) device node(s),
+ then you can point it to your own struct v4l2_prio_state.
- parent: you only set this if v4l2_device was registered with NULL as
the parent device struct. This only happens in cases where one hardware
device has multiple PCI devices that all share the same v4l2_device core.
(cx8802). Since the v4l2_device cannot be associated with a particular
PCI device it is setup without a parent device. But when the struct
video_device is setup you do know which parent PCI device to use.
+- flags: optional. Set to V4L2_FL_USE_FH_PRIO if you want to let the framework
+ handle the VIDIOC_G/S_PRIORITY ioctls. This requires that you use struct
+ v4l2_fh. Eventually this flag will disappear once all drivers use the core
+ priority handling. But for now it has to be set explicitly.
-If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or
-.ioctl to video_ioctl2 in your v4l2_file_operations struct.
+If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
+in your v4l2_file_operations struct.
+
+Do not use .ioctl! This is deprecated and will go away in the future.
The v4l2_file_operations struct is a subset of file_operations. The main
difference is that the inode argument is omitted since it is never used.
--------------
struct v4l2_fh provides a way to easily keep file handle specific data
-that is used by the V4L2 framework. Using v4l2_fh is optional for
-drivers.
+that is used by the V4L2 framework. New drivers must use struct v4l2_fh
+since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY)
+if the video_device flag V4L2_FL_USE_FH_PRIO is also set.
The users of v4l2_fh (in the V4L2 framework, not the driver) know
whether a driver uses v4l2_fh as its file->private_data pointer by
-testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags.
-
-Useful functions:
-
-- v4l2_fh_init()
+testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
+set whenever v4l2_fh_init() is called.
- Initialise the file handle. This *MUST* be performed in the driver's
- v4l2_file_operations->open() handler.
-
-- v4l2_fh_add()
-
- Add a v4l2_fh to video_device file handle list. May be called after
- initialising the file handle.
-
-- v4l2_fh_del()
-
- Unassociate the file handle from video_device(). The file handle
- exit function may now be called.
-
-- v4l2_fh_exit()
+struct v4l2_fh is allocated as a part of the driver's own file handle
+structure and file->private_data is set to it in the driver's open
+function by the driver.
- Uninitialise the file handle. After uninitialisation the v4l2_fh
- memory can be freed.
+In many cases the struct v4l2_fh will be embedded in a larger structure.
+In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
+v4l2_fh_del+v4l2_fh_exit in release().
-struct v4l2_fh is allocated as a part of the driver's own file handle
-structure and is set to file->private_data in the driver's open
-function by the driver. Drivers can extract their own file handle
-structure by using the container_of macro. Example:
+Drivers can extract their own file handle structure by using the container_of
+macro. Example:
struct my_fh {
int blah;
...
+ my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+
+ ...
+
ret = v4l2_fh_init(&my_fh->fh, vfd);
- if (ret)
+ if (ret) {
+ kfree(my_fh);
return ret;
+ }
- v4l2_fh_add(&my_fh->fh);
+ ...
file->private_data = &my_fh->fh;
-
- ...
+ v4l2_fh_add(&my_fh->fh);
+ return 0;
}
int my_release(struct file *file)
struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
...
+ v4l2_fh_del(&my_fh->fh);
+ v4l2_fh_exit(&my_fh->fh);
+ kfree(my_fh);
+ return 0;
}
+Below is a short description of the v4l2_fh functions used:
+
+int v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
+
+ Initialise the file handle. This *MUST* be performed in the driver's
+ v4l2_file_operations->open() handler.
+
+void v4l2_fh_add(struct v4l2_fh *fh)
+
+ Add a v4l2_fh to video_device file handle list. Must be called once the
+ file handle is completely initialized.
+
+void v4l2_fh_del(struct v4l2_fh *fh)
+
+ Unassociate the file handle from video_device(). The file handle
+ exit function may now be called.
+
+void v4l2_fh_exit(struct v4l2_fh *fh)
+
+ Uninitialise the file handle. After uninitialisation the v4l2_fh
+ memory can be freed.
+
+
+If struct v4l2_fh is not embedded, then you can use these helper functions:
+
+int v4l2_fh_open(struct file *filp)
+
+ This allocates a struct v4l2_fh, initializes it and adds it to the struct
+ video_device associated with the file struct.
+
+int v4l2_fh_release(struct file *filp)
+
+ This deletes it from the struct video_device associated with the file
+ struct, uninitialised the v4l2_fh and frees it.
+
+These two functions can be plugged into the v4l2_file_operation's open() and
+release() ops.
+
+
+Several drivers need to do something when the first file handle is opened and
+when the last file handle closes. Two helper functions were added to check
+whether the v4l2_fh struct is the only open filehandle of the associated
+device node:
+
+int v4l2_fh_is_singular(struct v4l2_fh *fh)
+
+ Returns 1 if the file handle is the only open file handle, else 0.
+
+int v4l2_fh_is_singular_file(struct file *filp)
+
+ Same, but it calls v4l2_fh_is_singular with filp->private_data.
+
+
V4L2 events
-----------
git.openpandora.org / pandora-kernel.git / blobdiff