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
  21 #ifndef V4L2_FH_H
  22 #define V4L2_FH_H
  23
  24 #include <linux/fs.h>
  25 #include <linux/kconfig.h>
  26 #include <linux/list.h>
  27 #include <linux/videodev2.h>
  28
  29 struct video_device;
  30 struct v4l2_ctrl_handler;
  31
  32 /**
  33  * struct v4l2_fh - Describes a V4L2 file handler
  34  *
  35  * @list: list of file handlers
  36  * @vdev: pointer to &struct video_device
  37  * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
  38  * @prio: priority of the file handler, as defined by &enum v4l2_priority
  39  *
  40  * @wait: event' s wait queue
  41  * @subscribe_lock: serialise changes to the subscribed list; guarantee that
  42  *                  the add and del event callbacks are orderly called
  43  * @subscribed: list of subscribed events
  44  * @available: list of events waiting to be dequeued
  45  * @navailable: number of available events at @available list
  46  * @sequence: event sequence number
  47  *
  48  * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
  49  */
  50 struct v4l2_fh {
  51         struct list_head        list;
  52         struct video_device     *vdev;
  53         struct v4l2_ctrl_handler *ctrl_handler;
  54         enum v4l2_priority      prio;
  55
  56         /* Events */
  57         wait_queue_head_t       wait;
  58         struct mutex            subscribe_lock;
  59         struct list_head        subscribed;
  60         struct list_head        available;
  61         unsigned int            navailable;
  62         u32                     sequence;
  63
  64 #if IS_ENABLED(CONFIG_V4L2_MEM2MEM_DEV)
  65         struct v4l2_m2m_ctx     *m2m_ctx;
  66 #endif
  67 };
  68
  69 /**
  70  * v4l2_fh_init - Initialise the file handle.
  71  *
  72  * @fh: pointer to &struct v4l2_fh
  73  * @vdev: pointer to &struct video_device
  74  *
  75  * Parts of the V4L2 framework using the
  76  * file handles should be initialised in this function. Must be called
  77  * from driver's v4l2_file_operations->open\(\) handler if the driver
  78  * uses &struct v4l2_fh.
  79  */
  80 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
  81
  82 /**
  83  * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
  84  *
  85  * @fh: pointer to &struct v4l2_fh
  86  *
  87  * .. note::
  88  *    The @fh file handle must be initialised first.
  89  */
  90 void v4l2_fh_add(struct v4l2_fh *fh);
  91
  92 /**
  93  * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
  94  *      of v4l2_file_operations.
  95  *
  96  * @filp: pointer to struct file
  97  *
  98  * It allocates a v4l2_fh and inits and adds it to the &struct video_device
  99  * associated with the file pointer.
 100  */
 101 int v4l2_fh_open(struct file *filp);
 102
 103 /**
 104  * v4l2_fh_del - Remove file handle from the list of file handles.
 105  *
 106  * @fh: pointer to &struct v4l2_fh
 107  *
 108  * On error filp->private_data will be %NULL, otherwise it will point to
 109  * the &struct v4l2_fh.
 110  *
 111  * .. note::
 112  *    Must be called in v4l2_file_operations->release\(\) handler if the driver
 113  *    uses &struct v4l2_fh.
 114  */
 115 void v4l2_fh_del(struct v4l2_fh *fh);
 116
 117 /**
 118  * v4l2_fh_exit - Release resources related to a file handle.
 119  *
 120  * @fh: pointer to &struct v4l2_fh
 121  *
 122  * Parts of the V4L2 framework using the v4l2_fh must release their
 123  * resources here, too.
 124  *
 125  * .. note::
 126  *    Must be called in v4l2_file_operations->release\(\) handler if the
 127  *    driver uses &struct v4l2_fh.
 128  */
 129 void v4l2_fh_exit(struct v4l2_fh *fh);
 130
 131 /**
 132  * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
 133  *      of v4l2_file_operations.
 134  *
 135  * @filp: pointer to struct file
 136  *
 137  * It deletes and exits the v4l2_fh associated with the file pointer and
 138  * frees it. It will do nothing if filp->private_data (the pointer to the
 139  * v4l2_fh struct) is %NULL.
 140  *
 141  * This function always returns 0.
 142  */
 143 int v4l2_fh_release(struct file *filp);
 144
 145 /**
 146  * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
 147  *       opened for the associated video_device.
 148  *
 149  * @fh: pointer to &struct v4l2_fh
 150  *
 151  * If @fh is NULL, then it returns 0.
 152  */
 153 int v4l2_fh_is_singular(struct v4l2_fh *fh);
 154
 155 /**
 156  * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
 157  *      filehandle opened for the associated video_device.
 158  *
 159  * @filp: pointer to struct file
 160  *
 161  * This is a helper function variant of v4l2_fh_is_singular() with uses
 162  * struct file as argument.
 163  *
 164  * If filp->private_data is %NULL, then it will return 0.
 165  */
 166 static inline int v4l2_fh_is_singular_file(struct file *filp)
 167 {
 168         return v4l2_fh_is_singular(filp->private_data);
 169 }
 170
 171 #endif /* V4L2_EVENT_H */