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        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 */
  70void 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 */
  80void 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 */
  91int 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 */
 105void 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 */
 119void 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 */
 133int 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 */
 143int 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 */
 156static 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 */
 162