0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 V4L2 File handlers
0004 ------------------
0005
0006 struct v4l2_fh provides a way to easily keep file handle specific
0007 data that is used by the V4L2 framework.
0008
0009 .. attention::
0010 New drivers must use struct v4l2_fh
0011 since it is also used to implement priority handling
0012 (:ref:`VIDIOC_G_PRIORITY`).
0013
0014 The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
0015 whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
0016 by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
0017 This bit is set whenever :c:func:`v4l2_fh_init` is called.
0018
0019 struct v4l2_fh is allocated as a part of the driver's own file handle
0020 structure and ``file->private_data`` is set to it in the driver's ``open()``
0021 function by the driver.
0022
0023 In many cases the struct v4l2_fh will be embedded in a larger
0024 structure. In that case you should call:
0025
0026 #) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()``
0027 #) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_exit` in ``release()``
0028
0029 Drivers can extract their own file handle structure by using the container_of
0030 macro.
0031
0032 Example:
0033
0034 .. code-block:: c
0035
0036 struct my_fh {
0037 int blah;
0038 struct v4l2_fh fh;
0039 };
0040
0041 ...
0042
0043 int my_open(struct file *file)
0044 {
0045 struct my_fh *my_fh;
0046 struct video_device *vfd;
0047 int ret;
0048
0049 ...
0050
0051 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
0052
0053 ...
0054
0055 v4l2_fh_init(&my_fh->fh, vfd);
0056
0057 ...
0058
0059 file->private_data = &my_fh->fh;
0060 v4l2_fh_add(&my_fh->fh);
0061 return 0;
0062 }
0063
0064 int my_release(struct file *file)
0065 {
0066 struct v4l2_fh *fh = file->private_data;
0067 struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
0068
0069 ...
0070 v4l2_fh_del(&my_fh->fh);
0071 v4l2_fh_exit(&my_fh->fh);
0072 kfree(my_fh);
0073 return 0;
0074 }
0075
0076 Below is a short description of the :c:type:`v4l2_fh` functions used:
0077
0078 :c:func:`v4l2_fh_init <v4l2_fh_init>`
0079 (:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
0080
0081
0082 - Initialise the file handle. This **MUST** be performed in the driver's
0083 :c:type:`v4l2_file_operations`->open() handler.
0084
0085
0086 :c:func:`v4l2_fh_add <v4l2_fh_add>`
0087 (:c:type:`fh <v4l2_fh>`)
0088
0089 - Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
0090 Must be called once the file handle is completely initialized.
0091
0092 :c:func:`v4l2_fh_del <v4l2_fh_del>`
0093 (:c:type:`fh <v4l2_fh>`)
0094
0095 - Unassociate the file handle from :c:type:`video_device`. The file handle
0096 exit function may now be called.
0097
0098 :c:func:`v4l2_fh_exit <v4l2_fh_exit>`
0099 (:c:type:`fh <v4l2_fh>`)
0100
0101 - Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
0102 memory can be freed.
0103
0104
0105 If struct v4l2_fh is not embedded, then you can use these helper functions:
0106
0107 :c:func:`v4l2_fh_open <v4l2_fh_open>`
0108 (struct file \*filp)
0109
0110 - This allocates a struct v4l2_fh, initializes it and adds it to
0111 the struct video_device associated with the file struct.
0112
0113 :c:func:`v4l2_fh_release <v4l2_fh_release>`
0114 (struct file \*filp)
0115
0116 - This deletes it from the struct video_device associated with the
0117 file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
0118
0119 These two functions can be plugged into the v4l2_file_operation's ``open()``
0120 and ``release()`` ops.
0121
0122 Several drivers need to do something when the first file handle is opened and
0123 when the last file handle closes. Two helper functions were added to check
0124 whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
0125 associated device node:
0126
0127 :c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
0128 (:c:type:`fh <v4l2_fh>`)
0129
0130 - Returns 1 if the file handle is the only open file handle, else 0.
0131
0132 :c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
0133 (struct file \*filp)
0134
0135 - Same, but it calls v4l2_fh_is_singular with filp->private_data.
0136
0137
0138 V4L2 fh functions and data structures
0139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0140
0141 .. kernel-doc:: include/media/v4l2-fh.h
