1.. SPDX-License-Identifier: GPL-2.0
2
3V4L2 File handlers
4------------------
5
6struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
7data that is used by the V4L2 framework.
8
9.. attention::
10	New drivers must use struct :c:type:`v4l2_fh`
11	since it is also used to implement priority handling
12	(:ref:`VIDIOC_G_PRIORITY`).
13
14The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
15whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
16by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
17This bit is set whenever :c:func:`v4l2_fh_init` is called.
18
19struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
20structure and ``file->private_data`` is set to it in the driver's ``open()``
21function by the driver.
22
23In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
24structure. In that case you should call:
25
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_exit` in ``release()``
28
29Drivers can extract their own file handle structure by using the container_of
30macro.
31
32Example:
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), GFP_KERNEL);
52
53		...
54
55		v4l2_fh_init(&my_fh->fh, vfd);
56
57		...
58
59		file->private_data = &my_fh->fh;
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->private_data;
67		struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
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
76Below is a short description of the :c:type:`v4l2_fh` functions used:
77
78:c:func:`v4l2_fh_init <v4l2_fh_init>`
79(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
80
81
82- Initialise the file handle. This **MUST** be performed in the driver's
83  :c:type:`v4l2_file_operations`->open() handler.
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_device` file handle list.
90  Must be called once the file handle is completely initialized.
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:`video_device`. The file handle
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 uninitialisation the :c:type:`v4l2_fh`
102  memory can be freed.
103
104
105If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
106
107:c:func:`v4l2_fh_open <v4l2_fh_open>`
108(struct file \*filp)
109
110- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
111  the struct :c:type:`video_device` associated with the file struct.
112
113:c:func:`v4l2_fh_release <v4l2_fh_release>`
114(struct file \*filp)
115
116- This deletes it from the struct :c:type:`video_device` associated with the
117  file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
118
119These two functions can be plugged into the v4l2_file_operation's ``open()``
120and ``release()`` ops.
121
122Several drivers need to do something when the first file handle is opened and
123when the last file handle closes. Two helper functions were added to check
124whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
125associated device node:
126
127:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
128(:c:type:`fh <v4l2_fh>`)
129
130-  Returns 1 if the file handle is the only open file handle, else 0.
131
132:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
133(struct file \*filp)
134
135- Same, but it calls v4l2_fh_is_singular with filp->private_data.
136
137
138V4L2 fh functions and data structures
139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
140
141.. kernel-doc:: include/media/v4l2-fh.h
142