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