Debian Codegraph @

Documentation/driver-api/media/v4l2-fh.rst

raw
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