include/media/v4l2-fh.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * v4l2-fh.h
0004  *
0005  * V4L2 file handle. Store per file handle data for the V4L2
0006  * framework. Using file handles is optional for the drivers.
0007  *
0008  * Copyright (C) 2009--2010 Nokia Corporation.
0009  *
0010  * Contact: Sakari Ailus <sakari.ailus@iki.fi>
0011  */
0012
0013 #ifndef V4L2_FH_H
0014 #define V4L2_FH_H
0015
0016 #include <linux/fs.h>
0017 #include <linux/kconfig.h>
0018 #include <linux/list.h>
0019 #include <linux/videodev2.h>
0020
0021 struct video_device;
0022 struct v4l2_ctrl_handler;
0023
0024 /**
0025  * struct v4l2_fh - Describes a V4L2 file handler
0026  *
0027  * @list: list of file handlers
0028  * @vdev: pointer to &struct video_device
0029  * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
0030  * @prio: priority of the file handler, as defined by &enum v4l2_priority
0031  *
0032  * @wait: event' s wait queue
0033  * @subscribe_lock: serialise changes to the subscribed list; guarantee that
0034  *          the add and del event callbacks are orderly called
0035  * @subscribed: list of subscribed events
0036  * @available: list of events waiting to be dequeued
0037  * @navailable: number of available events at @available list
0038  * @sequence: event sequence number
0039  *
0040  * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
0041  */
0042 struct v4l2_fh {
0043     struct list_head    list;
0044     struct video_device *vdev;
0045     struct v4l2_ctrl_handler *ctrl_handler;
0046     enum v4l2_priority  prio;
0047
0048     /* Events */
0049     wait_queue_head_t   wait;
0050     struct mutex        subscribe_lock;
0051     struct list_head    subscribed;
0052     struct list_head    available;
0053     unsigned int        navailable;
0054     u32         sequence;
0055
0056     struct v4l2_m2m_ctx *m2m_ctx;
0057 };
0058
0059 /**
0060  * v4l2_fh_init - Initialise the file handle.
0061  *
0062  * @fh: pointer to &struct v4l2_fh
0063  * @vdev: pointer to &struct video_device
0064  *
0065  * Parts of the V4L2 framework using the
0066  * file handles should be initialised in this function. Must be called
0067  * from driver's v4l2_file_operations->open\(\) handler if the driver
0068  * uses &struct v4l2_fh.
0069  */
0070 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
0071
0072 /**
0073  * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
0074  *
0075  * @fh: pointer to &struct v4l2_fh
0076  *
0077  * .. note::
0078  *    The @fh file handle must be initialised first.
0079  */
0080 void v4l2_fh_add(struct v4l2_fh *fh);
0081
0082 /**
0083  * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
0084  *  of v4l2_file_operations.
0085  *
0086  * @filp: pointer to struct file
0087  *
0088  * It allocates a v4l2_fh and inits and adds it to the &struct video_device
0089  * associated with the file pointer.
0090  */
0091 int v4l2_fh_open(struct file *filp);
0092
0093 /**
0094  * v4l2_fh_del - Remove file handle from the list of file handles.
0095  *
0096  * @fh: pointer to &struct v4l2_fh
0097  *
0098  * On error filp->private_data will be %NULL, otherwise it will point to
0099  * the &struct v4l2_fh.
0100  *
0101  * .. note::
0102  *    Must be called in v4l2_file_operations->release\(\) handler if the driver
0103  *    uses &struct v4l2_fh.
0104  */
0105 void v4l2_fh_del(struct v4l2_fh *fh);
0106
0107 /**
0108  * v4l2_fh_exit - Release resources related to a file handle.
0109  *
0110  * @fh: pointer to &struct v4l2_fh
0111  *
0112  * Parts of the V4L2 framework using the v4l2_fh must release their
0113  * resources here, too.
0114  *
0115  * .. note::
0116  *    Must be called in v4l2_file_operations->release\(\) handler if the
0117  *    driver uses &struct v4l2_fh.
0118  */
0119 void v4l2_fh_exit(struct v4l2_fh *fh);
0120
0121 /**
0122  * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
0123  *  of v4l2_file_operations.
0124  *
0125  * @filp: pointer to struct file
0126  *
0127  * It deletes and exits the v4l2_fh associated with the file pointer and
0128  * frees it. It will do nothing if filp->private_data (the pointer to the
0129  * v4l2_fh struct) is %NULL.
0130  *
0131  * This function always returns 0.
0132  */
0133 int v4l2_fh_release(struct file *filp);
0134
0135 /**
0136  * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
0137  *   opened for the associated video_device.
0138  *
0139  * @fh: pointer to &struct v4l2_fh
0140  *
0141  * If @fh is NULL, then it returns 0.
0142  */
0143 int v4l2_fh_is_singular(struct v4l2_fh *fh);
0144
0145 /**
0146  * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
0147  *  filehandle opened for the associated video_device.
0148  *
0149  * @filp: pointer to struct file
0150  *
0151  * This is a helper function variant of v4l2_fh_is_singular() with uses
0152  * struct file as argument.
0153  *
0154  * If filp->private_data is %NULL, then it will return 0.
0155  */
0156 static inline int v4l2_fh_is_singular_file(struct file *filp)
0157 {
0158     return v4l2_fh_is_singular(filp->private_data);
0159 }
0160
0161 #endif /* V4L2_EVENT_H */