v4l2-fh.rst

  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