1 .. SPDX-License-Identifier: GPL-2.0
2
3 V4L2 File handlers
4 ------------------
5
6 struct v4l2_fh provides a way to easily keep f
7 data that is used by the V4L2 framework.
8
9 .. attention::
10 New drivers must use struct v4l2_fh
11 since it is also used to implement pri
12 (:ref:`VIDIOC_G_PRIORITY`).
13
14 The users of :c:type:`v4l2_fh` (in the V4L2 fr
15 whether a driver uses :c:type:`v4l2_fh` as its
16 by testing the ``V4L2_FL_USES_V4L2_FH`` bit in
17 This bit is set whenever :c:func:`v4l2_fh_init
18
19 struct v4l2_fh is allocated as a part of the d
20 structure and ``file->private_data`` is set to
21 function by the driver.
22
23 In many cases the struct v4l2_fh will be embed
24 structure. In that case you should call:
25
26 #) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh
27 #) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_
28
29 Drivers can extract their own file handle stru
30 macro.
31
32 Example:
33
34 .. code-block:: c
35
36 struct my_fh {
37 int blah;
38 struct v4l2_fh fh;
39 };
40
41 ...
42
43 int my_open(struct file *file)
44 {
45 struct my_fh *my_fh;
46 struct video_device *vfd;
47 int ret;
48
49 ...
50
51 my_fh = kzalloc(sizeof(*my_fh)
52
53 ...
54
55 v4l2_fh_init(&my_fh->fh, vfd);
56
57 ...
58
59 file->private_data = &my_fh->f
60 v4l2_fh_add(&my_fh->fh);
61 return 0;
62 }
63
64 int my_release(struct file *file)
65 {
66 struct v4l2_fh *fh = file->pri
67 struct my_fh *my_fh = containe
68
69 ...
70 v4l2_fh_del(&my_fh->fh);
71 v4l2_fh_exit(&my_fh->fh);
72 kfree(my_fh);
73 return 0;
74 }
75
76 Below is a short description of the :c:type:`v
77
78 :c:func:`v4l2_fh_init <v4l2_fh_init>`
79 (:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_
80
81
82 - Initialise the file handle. This **MUST** be
83 :c:type:`v4l2_file_operations`->open() handl
84
85
86 :c:func:`v4l2_fh_add <v4l2_fh_add>`
87 (:c:type:`fh <v4l2_fh>`)
88
89 - Add a :c:type:`v4l2_fh` to :c:type:`video_de
90 Must be called once the file handle is compl
91
92 :c:func:`v4l2_fh_del <v4l2_fh_del>`
93 (:c:type:`fh <v4l2_fh>`)
94
95 - Unassociate the file handle from :c:type:`vi
96 exit function may now be called.
97
98 :c:func:`v4l2_fh_exit <v4l2_fh_exit>`
99 (:c:type:`fh <v4l2_fh>`)
100
101 - Uninitialise the file handle. After uninitia
102 memory can be freed.
103
104
105 If struct v4l2_fh is not embedded, then you ca
106
107 :c:func:`v4l2_fh_open <v4l2_fh_open>`
108 (struct file \*filp)
109
110 - This allocates a struct v4l2_fh, initializes
111 the struct video_device associated with the
112
113 :c:func:`v4l2_fh_release <v4l2_fh_release>`
114 (struct file \*filp)
115
116 - This deletes it from the struct video_device
117 file struct, uninitialised the :c:type:`v4l2
118
119 These two functions can be plugged into the v4
120 and ``release()`` ops.
121
122 Several drivers need to do something when the
123 when the last file handle closes. Two helper f
124 whether the :c:type:`v4l2_fh` struct is the on
125 associated device node:
126
127 :c:func:`v4l2_fh_is_singular <v4l2_fh_is_singu
128 (:c:type:`fh <v4l2_fh>`)
129
130 - Returns 1 if the file handle is the only op
131
132 :c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_
133 (struct file \*filp)
134
135 - Same, but it calls v4l2_fh_is_singular with
136
137
138 V4L2 fh functions and data structures
139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
140
141 .. kernel-doc:: include/media/v4l2-fh.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.