include/media/v4l2-fh.h

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