1V4L2 File handlers 2------------------ 3 4struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific 5data that is used by the V4L2 framework. 6 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`). 11 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. 15This bit is set whenever :c:func:`v4l2_fh_init` is called. 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()`` 19function by the driver. 20 21In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger 22structure. In that case you should call: 23 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()`` 26 27Drivers can extract their own file handle structure by using the container_of 28macro. 29 30Example: 31 32.. code-block:: c 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 74Below is a short description of the :c:type:`v4l2_fh` functions used: 75 76:c:func:`v4l2_fh_init <v4l2_fh_init>` 77(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) 78 79 80- Initialise the file handle. This **MUST** be performed in the driver's 81 :c:type:`v4l2_file_operations`->open() handler. 82 83 84:c:func:`v4l2_fh_add <v4l2_fh_add>` 85(:c:type:`fh <v4l2_fh>`) 86 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. 89 90:c:func:`v4l2_fh_del <v4l2_fh_del>` 91(:c:type:`fh <v4l2_fh>`) 92 93- Unassociate the file handle from :c:type:`video_device`. The file handle 94 exit function may now be called. 95 96:c:func:`v4l2_fh_exit <v4l2_fh_exit>` 97(:c:type:`fh <v4l2_fh>`) 98 99- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` 100 memory can be freed. 101 102 103If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: 104 105:c:func:`v4l2_fh_open <v4l2_fh_open>` 106(struct file \*filp) 107 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. 110 111:c:func:`v4l2_fh_release <v4l2_fh_release>` 112(struct file \*filp) 113 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. 116 117These two functions can be plugged into the v4l2_file_operation's ``open()`` 118and ``release()`` ops. 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 122whether the :c:type:`v4l2_fh` struct is the only open filehandle of the 123associated device node: 124 125:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` 126(:c:type:`fh <v4l2_fh>`) 127 128- Returns 1 if the file handle is the only open file handle, else 0. 129 130:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` 131(struct file \*filp) 132 133- Same, but it calls v4l2_fh_is_singular with filp->private_data. 134 135 136V4L2 fh functions and data structures 137^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 138 139.. kernel-doc:: include/media/v4l2-fh.h 140