Commit | Line | Data |
---|---|---|
378d4a54 MCC |
1 | V4L2 File handlers |
2 | ------------------ | |
3 | ||
46f74f1d MCC |
4 | struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific |
5 | data that is used by the V4L2 framework. | |
378d4a54 | 6 | |
46f74f1d MCC |
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`). | |
378d4a54 | 11 | |
46f74f1d MCC |
12 | The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know |
13 | whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer | |
14 | by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. | |
7b998bae | 15 | This bit is set whenever :c:func:`v4l2_fh_init` is called. |
46f74f1d MCC |
16 | |
17 | struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle | |
18 | structure and ``file->private_data`` is set to it in the driver's ``open()`` | |
378d4a54 MCC |
19 | function by the driver. |
20 | ||
46f74f1d MCC |
21 | In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger |
22 | structure. In that case you should call: | |
23 | ||
1b81f010 MCC |
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()`` | |
378d4a54 MCC |
26 | |
27 | Drivers can extract their own file handle structure by using the container_of | |
46f74f1d MCC |
28 | macro. |
29 | ||
30 | Example: | |
378d4a54 | 31 | |
46f74f1d | 32 | .. code-block:: c |
378d4a54 MCC |
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 | ||
46f74f1d | 74 | Below is a short description of the :c:type:`v4l2_fh` functions used: |
378d4a54 | 75 | |
7b998bae | 76 | :c:func:`v4l2_fh_init <v4l2_fh_init>` |
46f74f1d | 77 | (:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) |
378d4a54 | 78 | |
378d4a54 | 79 | |
46f74f1d MCC |
80 | - Initialise the file handle. This **MUST** be performed in the driver's |
81 | :c:type:`v4l2_file_operations`->open() handler. | |
378d4a54 | 82 | |
378d4a54 | 83 | |
7b998bae | 84 | :c:func:`v4l2_fh_add <v4l2_fh_add>` |
46f74f1d | 85 | (:c:type:`fh <v4l2_fh>`) |
378d4a54 | 86 | |
46f74f1d MCC |
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. | |
378d4a54 | 89 | |
7b998bae | 90 | :c:func:`v4l2_fh_del <v4l2_fh_del>` |
46f74f1d | 91 | (:c:type:`fh <v4l2_fh>`) |
378d4a54 | 92 | |
46f74f1d | 93 | - Unassociate the file handle from :c:type:`video_device`. The file handle |
378d4a54 MCC |
94 | exit function may now be called. |
95 | ||
7b998bae | 96 | :c:func:`v4l2_fh_exit <v4l2_fh_exit>` |
46f74f1d | 97 | (:c:type:`fh <v4l2_fh>`) |
378d4a54 | 98 | |
46f74f1d | 99 | - Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` |
378d4a54 MCC |
100 | memory can be freed. |
101 | ||
102 | ||
46f74f1d | 103 | If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: |
378d4a54 | 104 | |
7b998bae | 105 | :c:func:`v4l2_fh_open <v4l2_fh_open>` |
46f74f1d | 106 | (struct file \*filp) |
378d4a54 | 107 | |
46f74f1d MCC |
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. | |
378d4a54 | 110 | |
7b998bae | 111 | :c:func:`v4l2_fh_release <v4l2_fh_release>` |
46f74f1d | 112 | (struct file \*filp) |
378d4a54 | 113 | |
46f74f1d MCC |
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. | |
378d4a54 | 116 | |
46f74f1d MCC |
117 | These two functions can be plugged into the v4l2_file_operation's ``open()`` |
118 | and ``release()`` ops. | |
378d4a54 MCC |
119 | |
120 | Several drivers need to do something when the first file handle is opened and | |
121 | when the last file handle closes. Two helper functions were added to check | |
46f74f1d MCC |
122 | whether the :c:type:`v4l2_fh` struct is the only open filehandle of the |
123 | associated device node: | |
378d4a54 | 124 | |
7b998bae | 125 | :c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` |
46f74f1d | 126 | (:c:type:`fh <v4l2_fh>`) |
378d4a54 | 127 | |
46f74f1d | 128 | - Returns 1 if the file handle is the only open file handle, else 0. |
378d4a54 | 129 | |
7b998bae | 130 | :c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` |
46f74f1d | 131 | (struct file \*filp) |
378d4a54 | 132 | |
46f74f1d | 133 | - Same, but it calls v4l2_fh_is_singular with filp->private_data. |
378d4a54 MCC |
134 | |
135 | ||
f6fa883b MCC |
136 | V4L2 fh functions and data structures |
137 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
138 | ||
4ada120e | 139 | .. kernel-doc:: include/media/v4l2-fh.h |