include/media/v4l2-fh.h

   1 /*
   2  * v4l2-fh.h
   3  *
   4  * V4L2 file handle. Store per file handle data for the V4L2
   5  * framework. Using file handles is optional for the drivers.
   6  *
   7  * Copyright (C) 2009--2010 Nokia Corporation.
   8  *
   9  * Contact: Sakari Ailus <sakari.ailus@iki.fi>
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * version 2 as published by the Free Software Foundation.
  14  *
  15  * This program is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  23  * 02110-1301 USA
  24  */
  25
  26 #ifndef V4L2_FH_H
  27 #define V4L2_FH_H
  28
  29 #include <linux/fs.h>
  30 #include <linux/list.h>
  31 #include <linux/videodev2.h>
  32
  33 struct video_device;
  34 struct v4l2_ctrl_handler;
  35
  36 /**
  37  * struct v4l2_fh - Describes a V4L2 file handler
  38  *
  39  * @list: list of file handlers
  40  * @vdev: pointer to &struct video_device
  41  * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
  42  * @prio: priority of the file handler, as defined by &enum v4l2_priority
  43  *
  44  * @wait: event' s wait queue
  45  * @subscribe_lock: serialise changes to the subscribed list; guarantee that
  46  *                  the add and del event callbacks are orderly called
  47  * @subscribed: list of subscribed events
  48  * @available: list of events waiting to be dequeued
  49  * @navailable: number of available events at @available list
  50  * @sequence: event sequence number
  51  *
  52  * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
  53  */
  54 struct v4l2_fh {
  55         struct list_head        list;
  56         struct video_device     *vdev;
  57         struct v4l2_ctrl_handler *ctrl_handler;
  58         enum v4l2_priority      prio;
  59
  60         /* Events */
  61         wait_queue_head_t       wait;
  62         struct mutex            subscribe_lock;
  63         struct list_head        subscribed;
  64         struct list_head        available;
  65         unsigned int            navailable;
  66         u32                     sequence;
  67
  68 #if IS_ENABLED(CONFIG_V4L2_MEM2MEM_DEV)
  69         struct v4l2_m2m_ctx     *m2m_ctx;
  70 #endif
  71 };
  72
  73 /**
  74  * v4l2_fh_init - Initialise the file handle.
  75  *
  76  * @fh: pointer to &struct v4l2_fh
  77  * @vdev: pointer to &struct video_device
  78  *
  79  * Parts of the V4L2 framework using the
  80  * file handles should be initialised in this function. Must be called
  81  * from driver's v4l2_file_operations->open\(\) handler if the driver
  82  * uses &struct v4l2_fh.
  83  */
  84 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
  85
  86 /**
  87  * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
  88  *
  89  * @fh: pointer to &struct v4l2_fh
  90  *
  91  * .. note::
  92  *    The @fh file handle must be initialised first.
  93  */
  94 void v4l2_fh_add(struct v4l2_fh *fh);
  95
  96 /**
  97  * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
  98  *      of v4l2_file_operations.
  99  *
 100  * @filp: pointer to struct file
 101  *
 102  * It allocates a v4l2_fh and inits and adds it to the &struct video_device
 103  * associated with the file pointer.
 104  */
 105 int v4l2_fh_open(struct file *filp);
 106
 107 /**
 108  * v4l2_fh_del - Remove file handle from the list of file handles.
 109  *
 110  * @fh: pointer to &struct v4l2_fh
 111  *
 112  * On error filp->private_data will be %NULL, otherwise it will point to
 113  * the &struct v4l2_fh.
 114  *
 115  * .. note::
 116  *    Must be called in v4l2_file_operations->release\(\) handler if the driver
 117  *    uses &struct v4l2_fh.
 118  */
 119 void v4l2_fh_del(struct v4l2_fh *fh);
 120
 121 /**
 122  * v4l2_fh_exit - Release resources related to a file handle.
 123  *
 124  * @fh: pointer to &struct v4l2_fh
 125  *
 126  * Parts of the V4L2 framework using the v4l2_fh must release their
 127  * resources here, too.
 128  *
 129  * .. note::
 130  *    Must be called in v4l2_file_operations->release\(\) handler if the
 131  *    driver uses &struct v4l2_fh.
 132  */
 133 void v4l2_fh_exit(struct v4l2_fh *fh);
 134
 135 /**
 136  * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
 137  *      of v4l2_file_operations.
 138  *
 139  * @filp: pointer to struct file
 140  *
 141  * It deletes and exits the v4l2_fh associated with the file pointer and
 142  * frees it. It will do nothing if filp->private_data (the pointer to the
 143  * v4l2_fh struct) is %NULL.
 144  *
 145  * This function always returns 0.
 146  */
 147 int v4l2_fh_release(struct file *filp);
 148
 149 /**
 150  * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
 151  *       opened for the associated video_device.
 152  *
 153  * @fh: pointer to &struct v4l2_fh
 154  *
 155  * If @fh is NULL, then it returns 0.
 156  */
 157 int v4l2_fh_is_singular(struct v4l2_fh *fh);
 158
 159 /**
 160  * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
 161  *      filehandle opened for the associated video_device.
 162  *
 163  * @filp: pointer to struct file
 164  *
 165  * This is a helper function variant of v4l2_fh_is_singular() with uses
 166  * struct file as argument.
 167  *
 168  * If filp->private_data is %NULL, then it will return 0.
 169  */
 170 static inline int v4l2_fh_is_singular_file(struct file *filp)
 171 {
 172         return v4l2_fh_is_singular(filp->private_data);
 173 }
 174
 175 #endif /* V4L2_EVENT_H */