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