media: Set file->private_data in v4l2_fh_add()

All the drivers that use v4l2_fh and call v4l2_fh_add() manually store a
pointer to the v4l2_fh instance in file->private_data in their video
device .open() file operation handler. Move the code to the
v4l2_fh_add() function to avoid direct access to file->private_data in
drivers. This requires adding a file pointer argument to the function.

Changes to drivers have been generated with the following coccinelle
semantic patch:

@@
expression fh;
identifier filp;
identifier open;
type ret;
@@
ret open(..., struct file *filp, ...)
{
	<...
-	filp->private_data = fh;
	...
-	v4l2_fh_add(fh);
+	v4l2_fh_add(fh, filp);
	...>
}

@@
expression fh;
identifier filp;
identifier open;
type ret;
@@
ret open(..., struct file *filp, ...)
{
	<...
-	v4l2_fh_add(fh);
+	v4l2_fh_add(fh, filp);
	...
-	filp->private_data = fh;
	...>
}

Manual changes have been applied to Documentation/ to update the usage
patterns, to drivers/media/v4l2-core/v4l2-fh.c to update the
v4l2_fh_add() prototype set file->private_data, and to
include/media/v4l2-fh.h to update the v4l2_fh_add() function prototype
and its documentation.

Additionally, white space issues have been fixed manually in
drivers/media/platform/nvidia/tegra-vde/v4l2.c,
drivers/media/platform/rockchip/rkvdec/rkvdec.c,
drivers/media/v4l2-core/v4l2-fh.c and
drivers/staging/most/video/video.c.

Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>

1 files changed, 24 insertions, 22 deletions

diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index 2c87b74578d9..a7393067f5db 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -11,25 +11,22 @@ data that is used by the V4L2 framework.
 	since it is also used to implement priority handling
 	(:ref:`VIDIOC_G_PRIORITY`).
 
-The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
-whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
-by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
-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. 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:
-
-#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()``
-#) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_exit` in ``release()``
-
-Drivers can extract their own file handle structure by using the container_of
-macro.
+struct v4l2_fh is allocated in the driver's ``open()`` file operation handler.
+It is typically embedded in a larger driver-specific structure. The
+:c:type:`v4l2_fh` must be initialized with a call to :c:func:`v4l2_fh_init`,
+and added to the video device with :c:func:`v4l2_fh_add`. This associates the
+:c:type:`v4l2_fh` with the :c:type:`file` by setting ``file->private_data`` to
+point to the :c:type:`v4l2_fh`.
+
+Similarly, the struct v4l2_fh is freed in the driver's ``release()`` file
+operation handler. It must be removed from the video device with
+:c:func:`v4l2_fh_del` and cleaned up with :c:func:`v4l2_fh_exit` before being
+freed.
+
+Drivers must not access ``file->private_data`` directly. They can retrieve the
+:c:type:`v4l2_fh` associated with a :c:type:`file` by calling
+:c:func:`file_to_v4l2_fh`. Drivers can extract their own file handle structure
+by using the container_of macro.
 
 Example:
 
@@ -58,8 +55,7 @@ Example:
 
 		...
 
-		file->private_data = &my_fh->fh;
-		v4l2_fh_add(&my_fh->fh);
+		v4l2_fh_add(&my_fh->fh, file);
 		return 0;
 	}
 
@@ -84,7 +80,7 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
   :c:type:`v4l2_file_operations`->open() handler.
 
 :c:func:`v4l2_fh_add <v4l2_fh_add>`
-(:c:type:`fh <v4l2_fh>`)
+(:c:type:`fh <v4l2_fh>`, struct file \*filp)
 
 - Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
   Must be called once the file handle is completely initialized.
@@ -138,6 +134,12 @@ associated device node:
 
 - Same, but it calls v4l2_fh_is_singular with filp->private_data.
 
+.. note::
+        The V4L2 framework knows whether a driver uses :c:type:`v4l2_fh` as its
+        ``file->private_data`` pointer by testing the ``V4L2_FL_USES_V4L2_FH``
+        bit in :c:type:`video_device`->flags. This bit is set whenever
+        :c:func:`v4l2_fh_init` is called.
+
 
 V4L2 fh functions and data structures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^