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