Merge remote-tracking branch 'omap_dss2/for-next'
[deliverable/linux.git] / Documentation / media / kapi / v4l2-fh.rst
CommitLineData
378d4a54
MCC
1V4L2 File handlers
2------------------
3
46f74f1d
MCC
4struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
5data 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
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.
7b998bae 15This bit is set whenever :c:func:`v4l2_fh_init` is called.
46f74f1d
MCC
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()``
378d4a54
MCC
19function by the driver.
20
46f74f1d
MCC
21In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
22structure. 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
27Drivers can extract their own file handle structure by using the container_of
46f74f1d
MCC
28macro.
29
30Example:
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 74Below 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 103If 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
117These two functions can be plugged into the v4l2_file_operation's ``open()``
118and ``release()`` ops.
378d4a54
MCC
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
46f74f1d
MCC
122whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
123associated 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
136V4L2 fh functions and data structures
137^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
138
4ada120e 139.. kernel-doc:: include/media/v4l2-fh.h
This page took 0.041452 seconds and 5 git commands to generate.