| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
V4L2 File handles |
| 4 |
----------------- |
| 5 |
|
| 6 |
struct v4l2_fh provides a way to easily keep file handle specific data that is |
| 7 |
used by the V4L2 framework. Its usage is mandatory in all drivers. |
| 8 |
|
| 9 |
struct v4l2_fh is allocated in the driver's ``open()`` file operation handler. |
| 10 |
It is typically embedded in a larger driver-specific structure. The |
| 11 |
:c:type:`v4l2_fh` must be initialized with a call to :c:func:`v4l2_fh_init`, |
| 12 |
and added to the video device with :c:func:`v4l2_fh_add`. This associates the |
| 13 |
:c:type:`v4l2_fh` with the :c:type:`file` by setting ``file->private_data`` to |
| 14 |
point to the :c:type:`v4l2_fh`. |
| 15 |
|
| 16 |
Similarly, the struct v4l2_fh is freed in the driver's ``release()`` file |
| 17 |
operation handler. It must be removed from the video device with |
| 18 |
:c:func:`v4l2_fh_del` and cleaned up with :c:func:`v4l2_fh_exit` before being |
| 19 |
freed. |
| 20 |
|
| 21 |
Drivers must not access ``file->private_data`` directly. They can retrieve the |
| 22 |
:c:type:`v4l2_fh` associated with a :c:type:`file` by calling |
| 23 |
:c:func:`file_to_v4l2_fh`. Drivers can extract their own file handle structure |
| 24 |
by using the container_of macro. |
| 25 |
|
| 26 |
Example: |
| 27 |
|
| 28 |
.. code-block:: c |
| 29 |
|
| 30 |
struct my_fh { |
| 31 |
int blah; |
| 32 |
struct v4l2_fh fh; |
| 33 |
}; |
| 34 |
|
| 35 |
... |
| 36 |
|
| 37 |
int my_open(struct file *file) |
| 38 |
{ |
| 39 |
struct my_fh *my_fh; |
| 40 |
struct video_device *vfd; |
| 41 |
int ret; |
| 42 |
|
| 43 |
... |
| 44 |
|
| 45 |
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); |
| 46 |
|
| 47 |
... |
| 48 |
|
| 49 |
v4l2_fh_init(&my_fh->fh, vfd); |
| 50 |
|
| 51 |
... |
| 52 |
|
| 53 |
v4l2_fh_add(&my_fh->fh, file); |
| 54 |
return 0; |
| 55 |
} |
| 56 |
|
| 57 |
int my_release(struct file *file) |
| 58 |
{ |
| 59 |
struct v4l2_fh *fh = file_to_v4l2_fh(file); |
| 60 |
struct my_fh *my_fh = container_of(fh, struct my_fh, fh); |
| 61 |
|
| 62 |
... |
| 63 |
v4l2_fh_del(&my_fh->fh, file); |
| 64 |
v4l2_fh_exit(&my_fh->fh); |
| 65 |
kfree(my_fh); |
| 66 |
return 0; |
| 67 |
} |
| 68 |
|
| 69 |
Below is a short description of the :c:type:`v4l2_fh` functions used: |
| 70 |
|
| 71 |
:c:func:`v4l2_fh_init <v4l2_fh_init>` |
| 72 |
(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) |
| 73 |
|
| 74 |
- Initialise the file handle. This **MUST** be performed in the driver's |
| 75 |
:c:type:`v4l2_file_operations`->open() handler. |
| 76 |
|
| 77 |
:c:func:`v4l2_fh_add <v4l2_fh_add>` |
| 78 |
(:c:type:`fh <v4l2_fh>`, struct file \*filp) |
| 79 |
|
| 80 |
- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list. |
| 81 |
Must be called once the file handle is completely initialized. |
| 82 |
|
| 83 |
:c:func:`v4l2_fh_del <v4l2_fh_del>` |
| 84 |
(:c:type:`fh <v4l2_fh>`, struct file \*filp) |
| 85 |
|
| 86 |
- Unassociate the file handle from :c:type:`video_device`. The file handle |
| 87 |
exit function may now be called. |
| 88 |
|
| 89 |
:c:func:`v4l2_fh_exit <v4l2_fh_exit>` |
| 90 |
(:c:type:`fh <v4l2_fh>`) |
| 91 |
|
| 92 |
- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` |
| 93 |
memory can be freed. |
| 94 |
|
| 95 |
:c:func:`file_to_v4l2_fh <file_to_v4l2_fh>` |
| 96 |
(struct file \*filp) |
| 97 |
|
| 98 |
- Retrieve the :c:type:`v4l2_fh` instance associated with a :c:type:`file`. |
| 99 |
|
| 100 |
If struct v4l2_fh is not embedded, then you can use these helper functions: |
| 101 |
|
| 102 |
:c:func:`v4l2_fh_open <v4l2_fh_open>` |
| 103 |
(struct file \*filp) |
| 104 |
|
| 105 |
- This allocates a struct v4l2_fh, initializes it and adds it to |
| 106 |
the struct video_device associated with the file struct. |
| 107 |
|
| 108 |
:c:func:`v4l2_fh_release <v4l2_fh_release>` |
| 109 |
(struct file \*filp) |
| 110 |
|
| 111 |
- This deletes it from the struct video_device associated with the |
| 112 |
file struct, uninitialised the :c:type:`v4l2_fh` and frees it. |
| 113 |
|
| 114 |
These two functions can be plugged into the v4l2_file_operation's ``open()`` |
| 115 |
and ``release()`` ops. |
| 116 |
|
| 117 |
Several drivers need to do something when the first file handle is opened and |
| 118 |
when the last file handle closes. Two helper functions were added to check |
| 119 |
whether the :c:type:`v4l2_fh` struct is the only open filehandle of the |
| 120 |
associated device node: |
| 121 |
|
| 122 |
:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` |
| 123 |
(:c:type:`fh <v4l2_fh>`) |
| 124 |
|
| 125 |
- Returns 1 if the file handle is the only open file handle, else 0. |
| 126 |
|
| 127 |
:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` |
| 128 |
(struct file \*filp) |
| 129 |
|
| 130 |
- Same, but it calls v4l2_fh_is_singular with filp->private_data. |
| 131 |
|
| 132 |
|
| 133 |
V4L2 fh functions and data structures |
| 134 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 135 |
|
| 136 |
.. kernel-doc:: include/media/v4l2-fh.h |