1.. SPDX-License-Identifier: GPL-2.0 2 3V4L2 File handles 4----------------- 5 6struct v4l2_fh provides a way to easily keep file handle specific data that is 7used by the V4L2 framework. Its usage is mandatory in all drivers. 8 9struct v4l2_fh is allocated in the driver's ``open()`` file operation handler. 10It is typically embedded in a larger driver-specific structure. The 11:c:type:`v4l2_fh` must be initialized with a call to :c:func:`v4l2_fh_init`, 12and added to the video device with :c:func:`v4l2_fh_add`. This associates the 13:c:type:`v4l2_fh` with the :c:type:`file` by setting ``file->private_data`` to 14point to the :c:type:`v4l2_fh`. 15 16Similarly, the struct v4l2_fh is freed in the driver's ``release()`` file 17operation handler. It must be removed from the video device with 18:c:func:`v4l2_fh_del` and cleaned up with :c:func:`v4l2_fh_exit` before being 19freed. 20 21Drivers must not access ``file->private_data`` directly. They can retrieve the 22:c:type:`v4l2_fh` associated with a :c:type:`file` by calling 23:c:func:`file_to_v4l2_fh`. Drivers can extract their own file handle structure 24by using the container_of macro. 25 26Example: 27 28.. code-block:: c 29 30 struct my_fh { 31 int blah; 32 struct v4l2_fh fh; 33 }; 34 35 ... 36 37 int my_open(struct file *file) 38 { 39 struct my_fh *my_fh; 40 struct video_device *vfd; 41 int ret; 42 43 ... 44 45 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); 46 47 ... 48 49 v4l2_fh_init(&my_fh->fh, vfd); 50 51 ... 52 53 v4l2_fh_add(&my_fh->fh, file); 54 return 0; 55 } 56 57 int my_release(struct file *file) 58 { 59 struct v4l2_fh *fh = file_to_v4l2_fh(file); 60 struct my_fh *my_fh = container_of(fh, struct my_fh, fh); 61 62 ... 63 v4l2_fh_del(&my_fh->fh, file); 64 v4l2_fh_exit(&my_fh->fh); 65 kfree(my_fh); 66 return 0; 67 } 68 69Below is a short description of the :c:type:`v4l2_fh` functions used: 70 71:c:func:`v4l2_fh_init <v4l2_fh_init>` 72(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) 73 74- Initialise the file handle. This **MUST** be performed in the driver's 75 :c:type:`v4l2_file_operations`->open() handler. 76 77:c:func:`v4l2_fh_add <v4l2_fh_add>` 78(:c:type:`fh <v4l2_fh>`, struct file \*filp) 79 80- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list. 81 Must be called once the file handle is completely initialized. 82 83:c:func:`v4l2_fh_del <v4l2_fh_del>` 84(:c:type:`fh <v4l2_fh>`, struct file \*filp) 85 86- Unassociate the file handle from :c:type:`video_device`. The file handle 87 exit function may now be called. 88 89:c:func:`v4l2_fh_exit <v4l2_fh_exit>` 90(:c:type:`fh <v4l2_fh>`) 91 92- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` 93 memory can be freed. 94 95:c:func:`file_to_v4l2_fh <file_to_v4l2_fh>` 96(struct file \*filp) 97 98- Retrieve the :c:type:`v4l2_fh` instance associated with a :c:type:`file`. 99 100If struct v4l2_fh is not embedded, then you can use these helper functions: 101 102:c:func:`v4l2_fh_open <v4l2_fh_open>` 103(struct file \*filp) 104 105- This allocates a struct v4l2_fh, initializes it and adds it to 106 the struct video_device associated with the file struct. 107 108:c:func:`v4l2_fh_release <v4l2_fh_release>` 109(struct file \*filp) 110 111- This deletes it from the struct video_device associated with the 112 file struct, uninitialised the :c:type:`v4l2_fh` and frees it. 113 114These two functions can be plugged into the v4l2_file_operation's ``open()`` 115and ``release()`` ops. 116 117Several drivers need to do something when the first file handle is opened and 118when the last file handle closes. Two helper functions were added to check 119whether the :c:type:`v4l2_fh` struct is the only open filehandle of the 120associated device node: 121 122:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` 123(:c:type:`fh <v4l2_fh>`) 124 125- Returns 1 if the file handle is the only open file handle, else 0. 126 127:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` 128(struct file \*filp) 129 130- Same, but it calls v4l2_fh_is_singular with filp->private_data. 131 132 133V4L2 fh functions and data structures 134^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 135 136.. kernel-doc:: include/media/v4l2-fh.h 137