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