diff options
| author | Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com> | 2025-08-10 04:29:50 +0300 |
|---|---|---|
| committer | Hans Verkuil <hverkuil+cisco@kernel.org> | 2025-08-13 08:33:23 +0200 |
| commit | 618882c92681de18e9bd99d2a88bb21c897283f3 (patch) | |
| tree | 06572425dc09a2ac4d133ed31cbfa419ab94bdba /Documentation/driver-api | |
| parent | 0fd7155307bebb7daf946abae0ee8e50d20819ed (diff) | |
| download | linux-618882c92681de18e9bd99d2a88bb21c897283f3.tar.gz | |
media: Wrap file->private_data access with a helper function
Accessing file->private_data manually to retrieve the v4l2_fh pointer is
error-prone, as the field is a void * and will happily convert
implicitly to any pointer type. To avoid direct access to
file->private_data, introduce a new inline function that retrieves the
v4l2_fh pointer, and use it to replace common access patterns through
the kernel.
Changes to drivers have been generated with the following coccinelle
semantic patch:
@@
struct file *filp;
identifier fh;
@@
- struct v4l2_fh *fh = filp->private_data;
+ struct v4l2_fh *fh = file_to_v4l2_fh(filp);
Manual changes have been applied to Documentation/ to update the usage
patterns, and to include/media/v4l2-fh.h to add the new function.
While at it, fix a typo in the title of v4l2-fh.rst: the file describes
the "file handles" API, not "file handlers".
No functional change is intended, this only paves the way to remove
direct accesses to file->private_data and make V4L2 drivers safer.
Other accesses to the field will be addressed separately.
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/media/v4l2-fh.rst | 16 |
1 files changed, 10 insertions, 6 deletions
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst index 3eeaa8da0c9ec6..2c87b74578d97a 100644 --- a/Documentation/driver-api/media/v4l2-fh.rst +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -V4L2 File handlers ------------------- +V4L2 File handles +----------------- struct v4l2_fh provides a way to easily keep file handle specific data that is used by the V4L2 framework. @@ -18,7 +18,9 @@ This bit is set whenever :c:func:`v4l2_fh_init` is called. struct v4l2_fh is allocated as a part of the driver's own file handle structure and ``file->private_data`` is set to it in the driver's ``open()`` -function by the driver. +function by the driver. The :c:type:`v4l2_fh` file handle can be retrieved +from the :c:type:`file` using :c:func:`file_to_v4l2_fh`. Drivers must not +access ``file->private_data`` directly. In many cases the struct v4l2_fh will be embedded in a larger structure. In that case you should call: @@ -63,7 +65,7 @@ Example: int my_release(struct file *file) { - struct v4l2_fh *fh = file->private_data; + struct v4l2_fh *fh = file_to_v4l2_fh(file); struct my_fh *my_fh = container_of(fh, struct my_fh, fh); ... @@ -78,11 +80,9 @@ Below is a short description of the :c:type:`v4l2_fh` functions used: :c:func:`v4l2_fh_init <v4l2_fh_init>` (:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) - - Initialise the file handle. This **MUST** be performed in the driver's :c:type:`v4l2_file_operations`->open() handler. - :c:func:`v4l2_fh_add <v4l2_fh_add>` (:c:type:`fh <v4l2_fh>`) @@ -101,6 +101,10 @@ Below is a short description of the :c:type:`v4l2_fh` functions used: - Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` memory can be freed. +:c:func:`file_to_v4l2_fh <file_to_v4l2_fh>` +(struct file \*filp) + +- Retrieve the :c:type:`v4l2_fh` instance associated with a :c:type:`file`. If struct v4l2_fh is not embedded, then you can use these helper functions: |