1ff768f59SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2ff768f59SMauro Carvalho Chehab 3ff768f59SMauro Carvalho ChehabV4L2 File handlers 4ff768f59SMauro Carvalho Chehab------------------ 5ff768f59SMauro Carvalho Chehab 6*9303c9d5SMauro Carvalho Chehabstruct v4l2_fh provides a way to easily keep file handle specific 7ff768f59SMauro Carvalho Chehabdata that is used by the V4L2 framework. 8ff768f59SMauro Carvalho Chehab 9ff768f59SMauro Carvalho Chehab.. attention:: 10*9303c9d5SMauro Carvalho Chehab New drivers must use struct v4l2_fh 11ff768f59SMauro Carvalho Chehab since it is also used to implement priority handling 12ff768f59SMauro Carvalho Chehab (:ref:`VIDIOC_G_PRIORITY`). 13ff768f59SMauro Carvalho Chehab 14ff768f59SMauro Carvalho ChehabThe users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know 15ff768f59SMauro Carvalho Chehabwhether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer 16ff768f59SMauro Carvalho Chehabby testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. 17ff768f59SMauro Carvalho ChehabThis bit is set whenever :c:func:`v4l2_fh_init` is called. 18ff768f59SMauro Carvalho Chehab 19*9303c9d5SMauro Carvalho Chehabstruct v4l2_fh is allocated as a part of the driver's own file handle 20ff768f59SMauro Carvalho Chehabstructure and ``file->private_data`` is set to it in the driver's ``open()`` 21ff768f59SMauro Carvalho Chehabfunction by the driver. 22ff768f59SMauro Carvalho Chehab 23*9303c9d5SMauro Carvalho ChehabIn many cases the struct v4l2_fh will be embedded in a larger 24ff768f59SMauro Carvalho Chehabstructure. In that case you should call: 25ff768f59SMauro Carvalho Chehab 26ff768f59SMauro Carvalho Chehab#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()`` 27ff768f59SMauro Carvalho Chehab#) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_exit` in ``release()`` 28ff768f59SMauro Carvalho Chehab 29ff768f59SMauro Carvalho ChehabDrivers can extract their own file handle structure by using the container_of 30ff768f59SMauro Carvalho Chehabmacro. 31ff768f59SMauro Carvalho Chehab 32ff768f59SMauro Carvalho ChehabExample: 33ff768f59SMauro Carvalho Chehab 34ff768f59SMauro Carvalho Chehab.. code-block:: c 35ff768f59SMauro Carvalho Chehab 36ff768f59SMauro Carvalho Chehab struct my_fh { 37ff768f59SMauro Carvalho Chehab int blah; 38ff768f59SMauro Carvalho Chehab struct v4l2_fh fh; 39ff768f59SMauro Carvalho Chehab }; 40ff768f59SMauro Carvalho Chehab 41ff768f59SMauro Carvalho Chehab ... 42ff768f59SMauro Carvalho Chehab 43ff768f59SMauro Carvalho Chehab int my_open(struct file *file) 44ff768f59SMauro Carvalho Chehab { 45ff768f59SMauro Carvalho Chehab struct my_fh *my_fh; 46ff768f59SMauro Carvalho Chehab struct video_device *vfd; 47ff768f59SMauro Carvalho Chehab int ret; 48ff768f59SMauro Carvalho Chehab 49ff768f59SMauro Carvalho Chehab ... 50ff768f59SMauro Carvalho Chehab 51ff768f59SMauro Carvalho Chehab my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); 52ff768f59SMauro Carvalho Chehab 53ff768f59SMauro Carvalho Chehab ... 54ff768f59SMauro Carvalho Chehab 55ff768f59SMauro Carvalho Chehab v4l2_fh_init(&my_fh->fh, vfd); 56ff768f59SMauro Carvalho Chehab 57ff768f59SMauro Carvalho Chehab ... 58ff768f59SMauro Carvalho Chehab 59ff768f59SMauro Carvalho Chehab file->private_data = &my_fh->fh; 60ff768f59SMauro Carvalho Chehab v4l2_fh_add(&my_fh->fh); 61ff768f59SMauro Carvalho Chehab return 0; 62ff768f59SMauro Carvalho Chehab } 63ff768f59SMauro Carvalho Chehab 64ff768f59SMauro Carvalho Chehab int my_release(struct file *file) 65ff768f59SMauro Carvalho Chehab { 66ff768f59SMauro Carvalho Chehab struct v4l2_fh *fh = file->private_data; 67ff768f59SMauro Carvalho Chehab struct my_fh *my_fh = container_of(fh, struct my_fh, fh); 68ff768f59SMauro Carvalho Chehab 69ff768f59SMauro Carvalho Chehab ... 70ff768f59SMauro Carvalho Chehab v4l2_fh_del(&my_fh->fh); 71ff768f59SMauro Carvalho Chehab v4l2_fh_exit(&my_fh->fh); 72ff768f59SMauro Carvalho Chehab kfree(my_fh); 73ff768f59SMauro Carvalho Chehab return 0; 74ff768f59SMauro Carvalho Chehab } 75ff768f59SMauro Carvalho Chehab 76ff768f59SMauro Carvalho ChehabBelow is a short description of the :c:type:`v4l2_fh` functions used: 77ff768f59SMauro Carvalho Chehab 78ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_init <v4l2_fh_init>` 79ff768f59SMauro Carvalho Chehab(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) 80ff768f59SMauro Carvalho Chehab 81ff768f59SMauro Carvalho Chehab 82ff768f59SMauro Carvalho Chehab- Initialise the file handle. This **MUST** be performed in the driver's 83ff768f59SMauro Carvalho Chehab :c:type:`v4l2_file_operations`->open() handler. 84ff768f59SMauro Carvalho Chehab 85ff768f59SMauro Carvalho Chehab 86ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_add <v4l2_fh_add>` 87ff768f59SMauro Carvalho Chehab(:c:type:`fh <v4l2_fh>`) 88ff768f59SMauro Carvalho Chehab 89ff768f59SMauro Carvalho Chehab- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list. 90ff768f59SMauro Carvalho Chehab Must be called once the file handle is completely initialized. 91ff768f59SMauro Carvalho Chehab 92ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_del <v4l2_fh_del>` 93ff768f59SMauro Carvalho Chehab(:c:type:`fh <v4l2_fh>`) 94ff768f59SMauro Carvalho Chehab 95ff768f59SMauro Carvalho Chehab- Unassociate the file handle from :c:type:`video_device`. The file handle 96ff768f59SMauro Carvalho Chehab exit function may now be called. 97ff768f59SMauro Carvalho Chehab 98ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_exit <v4l2_fh_exit>` 99ff768f59SMauro Carvalho Chehab(:c:type:`fh <v4l2_fh>`) 100ff768f59SMauro Carvalho Chehab 101ff768f59SMauro Carvalho Chehab- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` 102ff768f59SMauro Carvalho Chehab memory can be freed. 103ff768f59SMauro Carvalho Chehab 104ff768f59SMauro Carvalho Chehab 105*9303c9d5SMauro Carvalho ChehabIf struct v4l2_fh is not embedded, then you can use these helper functions: 106ff768f59SMauro Carvalho Chehab 107ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_open <v4l2_fh_open>` 108ff768f59SMauro Carvalho Chehab(struct file \*filp) 109ff768f59SMauro Carvalho Chehab 110*9303c9d5SMauro Carvalho Chehab- This allocates a struct v4l2_fh, initializes it and adds it to 111*9303c9d5SMauro Carvalho Chehab the struct video_device associated with the file struct. 112ff768f59SMauro Carvalho Chehab 113ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_release <v4l2_fh_release>` 114ff768f59SMauro Carvalho Chehab(struct file \*filp) 115ff768f59SMauro Carvalho Chehab 116*9303c9d5SMauro Carvalho Chehab- This deletes it from the struct video_device associated with the 117ff768f59SMauro Carvalho Chehab file struct, uninitialised the :c:type:`v4l2_fh` and frees it. 118ff768f59SMauro Carvalho Chehab 119ff768f59SMauro Carvalho ChehabThese two functions can be plugged into the v4l2_file_operation's ``open()`` 120ff768f59SMauro Carvalho Chehaband ``release()`` ops. 121ff768f59SMauro Carvalho Chehab 122ff768f59SMauro Carvalho ChehabSeveral drivers need to do something when the first file handle is opened and 123ff768f59SMauro Carvalho Chehabwhen the last file handle closes. Two helper functions were added to check 124ff768f59SMauro Carvalho Chehabwhether the :c:type:`v4l2_fh` struct is the only open filehandle of the 125ff768f59SMauro Carvalho Chehabassociated device node: 126ff768f59SMauro Carvalho Chehab 127ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` 128ff768f59SMauro Carvalho Chehab(:c:type:`fh <v4l2_fh>`) 129ff768f59SMauro Carvalho Chehab 130ff768f59SMauro Carvalho Chehab- Returns 1 if the file handle is the only open file handle, else 0. 131ff768f59SMauro Carvalho Chehab 132ff768f59SMauro Carvalho Chehab:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` 133ff768f59SMauro Carvalho Chehab(struct file \*filp) 134ff768f59SMauro Carvalho Chehab 135ff768f59SMauro Carvalho Chehab- Same, but it calls v4l2_fh_is_singular with filp->private_data. 136ff768f59SMauro Carvalho Chehab 137ff768f59SMauro Carvalho Chehab 138ff768f59SMauro Carvalho ChehabV4L2 fh functions and data structures 139ff768f59SMauro Carvalho Chehab^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 140ff768f59SMauro Carvalho Chehab 141ff768f59SMauro Carvalho Chehab.. kernel-doc:: include/media/v4l2-fh.h 142