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