Documentation/media/kapi/v4l2-fh.rst

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