include/media/videobuf-core.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * generic helper functions for handling video4linux capture buffers
0004  *
0005  * (c) 2007 Mauro Carvalho Chehab, <mchehab@kernel.org>
0006  *
0007  * Highly based on video-buf written originally by:
0008  * (c) 2001,02 Gerd Knorr <kraxel@bytesex.org>
0009  * (c) 2006 Mauro Carvalho Chehab, <mchehab@kernel.org>
0010  * (c) 2006 Ted Walther and John Sokol
0011  */
0012
0013 #ifndef _VIDEOBUF_CORE_H
0014 #define _VIDEOBUF_CORE_H
0015
0016 #include <linux/poll.h>
0017 #include <linux/videodev2.h>
0018
0019 #define UNSET (-1U)
0020
0021
0022 struct videobuf_buffer;
0023 struct videobuf_queue;
0024
0025 /* --------------------------------------------------------------------- */
0026
0027 /*
0028  * A small set of helper functions to manage video4linux buffers.
0029  *
0030  * struct videobuf_buffer holds the data structures used by the helper
0031  * functions, additionally some commonly used fields for v4l buffers
0032  * (width, height, lists, waitqueue) are in there.  That struct should
0033  * be used as first element in the drivers buffer struct.
0034  *
0035  * about the mmap helpers (videobuf_mmap_*):
0036  *
0037  * The mmaper function allows to map any subset of contiguous buffers.
0038  * This includes one mmap() call for all buffers (which the original
0039  * video4linux API uses) as well as one mmap() for every single buffer
0040  * (which v4l2 uses).
0041  *
0042  * If there is a valid mapping for a buffer, buffer->baddr/bsize holds
0043  * userspace address + size which can be fed into the
0044  * videobuf_dma_init_user function listed above.
0045  *
0046  */
0047
0048 struct videobuf_mapping {
0049     unsigned int count;
0050     struct videobuf_queue *q;
0051 };
0052
0053 enum videobuf_state {
0054     VIDEOBUF_NEEDS_INIT = 0,
0055     VIDEOBUF_PREPARED   = 1,
0056     VIDEOBUF_QUEUED     = 2,
0057     VIDEOBUF_ACTIVE     = 3,
0058     VIDEOBUF_DONE       = 4,
0059     VIDEOBUF_ERROR      = 5,
0060     VIDEOBUF_IDLE       = 6,
0061 };
0062
0063 struct videobuf_buffer {
0064     unsigned int            i;
0065     u32                     magic;
0066
0067     /* info about the buffer */
0068     unsigned int            width;
0069     unsigned int            height;
0070     unsigned int            bytesperline; /* use only if != 0 */
0071     unsigned long           size;
0072     enum v4l2_field         field;
0073     enum videobuf_state     state;
0074     struct list_head        stream;  /* QBUF/DQBUF list */
0075
0076     /* touched by irq handler */
0077     struct list_head        queue;
0078     wait_queue_head_t       done;
0079     unsigned int            field_count;
0080     u64         ts;
0081
0082     /* Memory type */
0083     enum v4l2_memory        memory;
0084
0085     /* buffer size */
0086     size_t                  bsize;
0087
0088     /* buffer offset (mmap + overlay) */
0089     size_t                  boff;
0090
0091     /* buffer addr (userland ptr!) */
0092     unsigned long           baddr;
0093
0094     /* for mmap'ed buffers */
0095     struct videobuf_mapping *map;
0096
0097     /* Private pointer to allow specific methods to store their data */
0098     int         privsize;
0099     void                    *priv;
0100 };
0101
0102 struct videobuf_queue_ops {
0103     int (*buf_setup)(struct videobuf_queue *q,
0104              unsigned int *count, unsigned int *size);
0105     int (*buf_prepare)(struct videobuf_queue *q,
0106                struct videobuf_buffer *vb,
0107                enum v4l2_field field);
0108     void (*buf_queue)(struct videobuf_queue *q,
0109               struct videobuf_buffer *vb);
0110     void (*buf_release)(struct videobuf_queue *q,
0111                 struct videobuf_buffer *vb);
0112 };
0113
0114 #define MAGIC_QTYPE_OPS 0x12261003
0115
0116 /* Helper operations - device type dependent */
0117 struct videobuf_qtype_ops {
0118     u32                     magic;
0119
0120     struct videobuf_buffer *(*alloc_vb)(size_t size);
0121     void *(*vaddr)      (struct videobuf_buffer *buf);
0122     int (*iolock)       (struct videobuf_queue *q,
0123                  struct videobuf_buffer *vb,
0124                  struct v4l2_framebuffer *fbuf);
0125     int (*sync)     (struct videobuf_queue *q,
0126                  struct videobuf_buffer *buf);
0127     int (*mmap_mapper)  (struct videobuf_queue *q,
0128                  struct videobuf_buffer *buf,
0129                  struct vm_area_struct *vma);
0130 };
0131
0132 struct videobuf_queue {
0133     struct mutex               vb_lock;
0134     struct mutex               *ext_lock;
0135     spinlock_t                 *irqlock;
0136     struct device          *dev;
0137
0138     wait_queue_head_t      wait; /* wait if queue is empty */
0139
0140     enum v4l2_buf_type         type;
0141     unsigned int               msize;
0142     enum v4l2_field            field;
0143     enum v4l2_field            last;   /* for field=V4L2_FIELD_ALTERNATE */
0144     struct videobuf_buffer     *bufs[VIDEO_MAX_FRAME];
0145     const struct videobuf_queue_ops  *ops;
0146     struct videobuf_qtype_ops  *int_ops;
0147
0148     unsigned int               streaming:1;
0149     unsigned int               reading:1;
0150
0151     /* capture via mmap() + ioctl(QBUF/DQBUF) */
0152     struct list_head           stream;
0153
0154     /* capture via read() */
0155     unsigned int               read_off;
0156     struct videobuf_buffer     *read_buf;
0157
0158     /* driver private data */
0159     void                       *priv_data;
0160 };
0161
0162 static inline void videobuf_queue_lock(struct videobuf_queue *q)
0163 {
0164     if (!q->ext_lock)
0165         mutex_lock(&q->vb_lock);
0166 }
0167
0168 static inline void videobuf_queue_unlock(struct videobuf_queue *q)
0169 {
0170     if (!q->ext_lock)
0171         mutex_unlock(&q->vb_lock);
0172 }
0173
0174 int videobuf_waiton(struct videobuf_queue *q, struct videobuf_buffer *vb,
0175         int non_blocking, int intr);
0176 int videobuf_iolock(struct videobuf_queue *q, struct videobuf_buffer *vb,
0177         struct v4l2_framebuffer *fbuf);
0178
0179 struct videobuf_buffer *videobuf_alloc_vb(struct videobuf_queue *q);
0180
0181 /* Used on videobuf-dvb */
0182 void *videobuf_queue_to_vaddr(struct videobuf_queue *q,
0183                   struct videobuf_buffer *buf);
0184
0185 void videobuf_queue_core_init(struct videobuf_queue *q,
0186              const struct videobuf_queue_ops *ops,
0187              struct device *dev,
0188              spinlock_t *irqlock,
0189              enum v4l2_buf_type type,
0190              enum v4l2_field field,
0191              unsigned int msize,
0192              void *priv,
0193              struct videobuf_qtype_ops *int_ops,
0194              struct mutex *ext_lock);
0195 int  videobuf_queue_is_busy(struct videobuf_queue *q);
0196 void videobuf_queue_cancel(struct videobuf_queue *q);
0197
0198 enum v4l2_field videobuf_next_field(struct videobuf_queue *q);
0199 int videobuf_reqbufs(struct videobuf_queue *q,
0200              struct v4l2_requestbuffers *req);
0201 int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
0202 int videobuf_qbuf(struct videobuf_queue *q,
0203           struct v4l2_buffer *b);
0204 int videobuf_dqbuf(struct videobuf_queue *q,
0205            struct v4l2_buffer *b, int nonblocking);
0206 int videobuf_streamon(struct videobuf_queue *q);
0207 int videobuf_streamoff(struct videobuf_queue *q);
0208
0209 void videobuf_stop(struct videobuf_queue *q);
0210
0211 int videobuf_read_start(struct videobuf_queue *q);
0212 void videobuf_read_stop(struct videobuf_queue *q);
0213 ssize_t videobuf_read_stream(struct videobuf_queue *q,
0214                  char __user *data, size_t count, loff_t *ppos,
0215                  int vbihack, int nonblocking);
0216 ssize_t videobuf_read_one(struct videobuf_queue *q,
0217               char __user *data, size_t count, loff_t *ppos,
0218               int nonblocking);
0219 __poll_t videobuf_poll_stream(struct file *file,
0220                   struct videobuf_queue *q,
0221                   poll_table *wait);
0222
0223 int videobuf_mmap_setup(struct videobuf_queue *q,
0224             unsigned int bcount, unsigned int bsize,
0225             enum v4l2_memory memory);
0226 int __videobuf_mmap_setup(struct videobuf_queue *q,
0227             unsigned int bcount, unsigned int bsize,
0228             enum v4l2_memory memory);
0229 int videobuf_mmap_free(struct videobuf_queue *q);
0230 int videobuf_mmap_mapper(struct videobuf_queue *q,
0231              struct vm_area_struct *vma);
0232
0233 #endif