142 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3V4L2 File handlers4------------------5 6struct v4l2_fh provides a way to easily keep file handle specific7data that is used by the V4L2 framework.8 9.. attention::10 New drivers must use struct v4l2_fh11 since it is also used to implement priority handling12 (:ref:`VIDIOC_G_PRIORITY`).13 14The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know15whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer16by 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 v4l2_fh is allocated as a part of the driver's own file handle20structure and ``file->private_data`` is set to it in the driver's ``open()``21function by the driver.22 23In many cases the struct v4l2_fh will be embedded in a larger24structure. 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_of30macro.31 32Example:33 34.. code-block:: c35 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's83 :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 handle96 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 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 v4l2_fh, initializes it and adds it to111 the struct 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 video_device associated with the117 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 and123when the last file handle closes. Two helper functions were added to check124whether the :c:type:`v4l2_fh` struct is the only open filehandle of the125associated 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 structures139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^140 141.. kernel-doc:: include/media/v4l2-fh.h142