2.6. V4L2 File handles¶
struct v4l2_fh provides a way to easily keep file handle specific data that is
used by the V4L2 framework. Its usage is mandatory in all drivers.
struct v4l2_fh is allocated in the driver’s open() file operation handler.
It is typically embedded in a larger driver-specific structure. The
v4l2_fh must be initialized with a call to v4l2_fh_init(),
and added to the video device with v4l2_fh_add(). This associates the
v4l2_fh with the file by setting file->private_data to
point to the v4l2_fh.
Similarly, the struct v4l2_fh is freed in the driver’s release() file
operation handler. It must be removed from the video device with
v4l2_fh_del() and cleaned up with v4l2_fh_exit() before being
freed.
Drivers must not access file->private_data directly. They can retrieve the
v4l2_fh associated with a file by calling
file_to_v4l2_fh(). Drivers can extract their own file handle structure
by using the container_of macro.
Example:
struct my_fh {
int blah;
struct v4l2_fh fh;
};
...
int my_open(struct file *file)
{
struct my_fh *my_fh;
struct video_device *vfd;
int ret;
...
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
...
v4l2_fh_init(&my_fh->fh, vfd);
...
v4l2_fh_add(&my_fh->fh, file);
return 0;
}
int my_release(struct file *file)
{
struct v4l2_fh *fh = file_to_v4l2_fh(file);
struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
...
v4l2_fh_del(&my_fh->fh, file);
v4l2_fh_exit(&my_fh->fh);
kfree(my_fh);
return 0;
}
Below is a short description of the v4l2_fh functions used:
v4l2_fh_init
(fh, vdev)
Initialise the file handle. This MUST be performed in the driver’s
v4l2_file_operations->open() handler.
v4l2_fh_add
(fh, struct file *filp)
Add a
v4l2_fhtovideo_devicefile handle list. Must be called once the file handle is completely initialized.
v4l2_fh_del
(fh, struct file *filp)
Unassociate the file handle from
video_device. The file handle exit function may now be called.
Uninitialise the file handle. After uninitialisation the
v4l2_fhmemory can be freed.
file_to_v4l2_fh
(struct file *filp)
If struct v4l2_fh is not embedded, then you can use these helper functions:
v4l2_fh_open
(struct file *filp)
This allocates a
struct v4l2_fh, initializes it and adds it to thestruct video_deviceassociated with the file struct.
v4l2_fh_release
(struct file *filp)
This deletes it from the
struct video_deviceassociated with the file struct, uninitialised thev4l2_fhand 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:
Returns 1 if the file handle is the only open file handle, else 0.
v4l2_fh_is_singular_file
(struct file *filp)
Same, but it calls v4l2_fh_is_singular with filp->private_data.
2.6.1. V4L2 fh functions and data structures¶
-
struct v4l2_fh¶
Describes a V4L2 file handler
Definition:
struct v4l2_fh {
struct list_head list;
struct video_device *vdev;
struct v4l2_ctrl_handler *ctrl_handler;
enum v4l2_priority prio;
wait_queue_head_t wait;
struct mutex subscribe_lock;
struct list_head subscribed;
struct list_head available;
unsigned int navailable;
u32 sequence;
struct v4l2_m2m_ctx *m2m_ctx;
};
Members
listlist of file handlers
vdevpointer to
struct video_devicectrl_handlerpointer to
struct v4l2_ctrl_handlerpriopriority of the file handler, as defined by
enum v4l2_prioritywaitevent’ s wait queue
subscribe_lockserialise changes to the subscribed list; guarantee that the add and del event callbacks are orderly called
subscribedlist of subscribed events
availablelist of events waiting to be dequeued
navailablenumber of available events at available list
sequenceevent sequence number
m2m_ctxpointer to
struct v4l2_m2m_ctx
-
struct v4l2_fh *file_to_v4l2_fh(struct file *filp)¶
Return the v4l2_fh associated with a
struct file
Parameters
struct file *filppointer to
struct file
Description
This function should be used by drivers to retrieve the struct v4l2_fh
instance pointer stored in the file private_data instead of accessing the
private_data field directly.
-
void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)¶
Initialise the file handle.
Parameters
struct v4l2_fh *fhpointer to
struct v4l2_fhstruct video_device *vdevpointer to
struct video_device
Description
Parts of the V4L2 framework using the
file handles should be initialised in this function. Must be called
from driver’s v4l2_file_operations->open() handler if the driver
uses struct v4l2_fh.
-
void v4l2_fh_add(struct v4l2_fh *fh, struct file *filp)¶
Add the fh to the list of file handles on a video_device.
Parameters
struct v4l2_fh *fhpointer to
struct v4l2_fhstruct file *filppointer to
struct fileassociated with fh
Description
The function sets filp->private_data to point to fh.
Note
The fh file handle must be initialised first.
-
int v4l2_fh_open(struct file *filp)¶
Ancillary routine that can be used as the open() op of v4l2_file_operations.
Parameters
struct file *filppointer to
struct file
Description
It allocates a v4l2_fh and inits and adds it to the struct video_device
associated with the file pointer.
On error filp->private_data will be NULL, otherwise it will point to
the struct v4l2_fh.
-
void v4l2_fh_del(struct v4l2_fh *fh, struct file *filp)¶
Remove file handle from the list of file handles.
Parameters
struct v4l2_fh *fhpointer to
struct v4l2_fhstruct file *filppointer to
struct fileassociated with fh
Description
The function resets filp->private_data to NULL.
Note
Must be called in v4l2_file_operations->release() handler if the driver
uses struct v4l2_fh.
Parameters
struct v4l2_fh *fhpointer to
struct v4l2_fh
Description
Parts of the V4L2 framework using the v4l2_fh must release their resources here, too.
Note
Must be called in v4l2_file_operations->release() handler if the
driver uses struct v4l2_fh.
-
int v4l2_fh_release(struct file *filp)¶
Ancillary routine that can be used as the
release()op of v4l2_file_operations.
Parameters
struct file *filppointer to
struct file
Description
It deletes and exits the v4l2_fh associated with the file pointer and
frees it. It will do nothing if filp->private_data (the pointer to the
v4l2_fh struct) is NULL.
This function always returns 0.
-
int v4l2_fh_is_singular(struct v4l2_fh *fh)¶
Returns 1 if this filehandle is the only filehandle opened for the associated video_device.
Parameters
struct v4l2_fh *fhpointer to
struct v4l2_fh
Description
If fh is NULL, then it returns 0.
-
int v4l2_fh_is_singular_file(struct file *filp)¶
Returns 1 if this filehandle is the only filehandle opened for the associated video_device.
Parameters
struct file *filppointer to
struct file
Description
This is a helper function variant of v4l2_fh_is_singular() with uses
struct file as argument.
If filp->private_data is NULL, then it will return 0.