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