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