1.. SPDX-License-Identifier: GPL-2.0 2 3V4L2 File handlers 4------------------ 5 6struct v4l2_fh provides a way to easily keep file handle specific 7data that is used by the V4L2 framework. 8 9.. attention:: 10 New drivers must use struct v4l2_fh 11 since it is also used to implement priority handling 12 (:ref:`VIDIOC_G_PRIORITY`). 13 14The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know 15whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer 16by 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 handle 20structure 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 larger 24structure. 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_of 30macro. 31 32Example: 33 34.. code-block:: c 35 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's 83 :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 handle 96 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 to 111 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 the 117 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 and 123when the last file handle closes. Two helper functions were added to check 124whether the :c:type:`v4l2_fh` struct is the only open filehandle of the 125associated 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 structures 139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 140 141.. kernel-doc:: include/media/v4l2-fh.h 142