LXR linux/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
  21struct video_device;
  22struct 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 */
  42struct 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 */
  72void 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 */
  82void 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 */
  93int 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 */
 107void 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 */
 121void 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 */
 135int 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 */
 145int 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 */
 158static 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 */
 164