include/media/video-buf.h

   1 /*
   2  * generic helper functions for video4linux capture buffers, to handle
   3  * memory management and PCI DMA.  Right now bttv + saa7134 use it.
   4  *
   5  * The functions expect the hardware being able to scatter gatter
   6  * (i.e. the buffers are not linear in physical memory, but fragmented
   7  * into PAGE_SIZE chunks).  They also assume the driver does not need
   8  * to touch the video data (thus it is probably not useful for USB as
   9  * data often must be uncompressed by the drivers).
  10  *
  11  * (c) 2001,02 Gerd Knorr <kraxel@bytesex.org>
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  */
  18
  19 #include <linux/videodev.h>
  20
  21 #define UNSET (-1U)
  22
  23 /* --------------------------------------------------------------------- */
  24
  25 /*
  26  * Return a scatterlist for some page-aligned vmalloc()'ed memory
  27  * block (NULL on errors).  Memory for the scatterlist is allocated
  28  * using kmalloc.  The caller must free the memory.
  29  */
  30 struct scatterlist* videobuf_vmalloc_to_sg(unsigned char *virt, int nr_pages);
  31
  32 /*
  33  * Return a scatterlist for a an array of userpages (NULL on errors).
  34  * Memory for the scatterlist is allocated using kmalloc.  The caller
  35  * must free the memory.
  36  */
  37 struct scatterlist* videobuf_pages_to_sg(struct page **pages, int nr_pages,
  38                                          int offset);
  39
  40 /* --------------------------------------------------------------------- */
  41
  42 /*
  43  * A small set of helper functions to manage buffers (both userland
  44  * and kernel) for DMA.
  45  *
  46  * videobuf_dma_init_*()
  47  *      creates a buffer.  The userland version takes a userspace
  48  *      pointer + length.  The kernel version just wants the size and
  49  *      does memory allocation too using vmalloc_32().
  50  *
  51  * videobuf_dma_pci_*()
  52  *      see Documentation/DMA-mapping.txt, these functions to
  53  *      basically the same.  The map function does also build a
  54  *      scatterlist for the buffer (and unmap frees it ...)
  55  *
  56  * videobuf_dma_free()
  57  *      no comment ...
  58  *
  59  */
  60
  61 struct videobuf_dmabuf {
  62         u32                 magic;
  63
  64         /* for userland buffer */
  65         int                 offset;
  66         struct page         **pages;
  67
  68         /* for kernel buffers */
  69         void                *vmalloc;
  70
  71         /* for overlay buffers (pci-pci dma) */
  72         dma_addr_t          bus_addr;
  73
  74         /* common */
  75         struct scatterlist  *sglist;
  76         int                 sglen;
  77         int                 nr_pages;
  78         int                 direction;
  79 };
  80
  81 void videobuf_dma_init(struct videobuf_dmabuf *dma);
  82 int videobuf_dma_init_user(struct videobuf_dmabuf *dma, int direction,
  83                            unsigned long data, unsigned long size);
  84 int videobuf_dma_init_kernel(struct videobuf_dmabuf *dma, int direction,
  85                              int nr_pages);
  86 int videobuf_dma_init_overlay(struct videobuf_dmabuf *dma, int direction,
  87                               dma_addr_t addr, int nr_pages);
  88 int videobuf_dma_pci_map(struct pci_dev *dev, struct videobuf_dmabuf *dma);
  89 int videobuf_dma_pci_sync(struct pci_dev *dev,
  90                           struct videobuf_dmabuf *dma);
  91 int videobuf_dma_pci_unmap(struct pci_dev *dev, struct videobuf_dmabuf *dma);
  92 int videobuf_dma_free(struct videobuf_dmabuf *dma);
  93
  94 /* --------------------------------------------------------------------- */
  95
  96 /*
  97  * A small set of helper functions to manage video4linux buffers.
  98  *
  99  * struct videobuf_buffer holds the data structures used by the helper
 100  * functions, additionally some commonly used fields for v4l buffers
 101  * (width, height, lists, waitqueue) are in there.  That struct should
 102  * be used as first element in the drivers buffer struct.
 103  *
 104  * about the mmap helpers (videobuf_mmap_*):
 105  *
 106  * The mmaper function allows to map any subset of contingous buffers.
 107  * This includes one mmap() call for all buffers (which the original
 108  * video4linux API uses) as well as one mmap() for every single buffer
 109  * (which v4l2 uses).
 110  *
 111  * If there is a valid mapping for a buffer, buffer->baddr/bsize holds
 112  * userspace address + size which can be feeded into the
 113  * videobuf_dma_init_user function listed above.
 114  *
 115  */
 116
 117 struct videobuf_buffer;
 118 struct videobuf_queue;
 119
 120 struct videobuf_mapping {
 121         unsigned int count;
 122         int highmem_ok;
 123         unsigned long start;
 124         unsigned long end;
 125         struct videobuf_queue *q;
 126 };
 127
 128 enum videobuf_state {
 129         STATE_NEEDS_INIT = 0,
 130         STATE_PREPARED   = 1,
 131         STATE_QUEUED     = 2,
 132         STATE_ACTIVE     = 3,
 133         STATE_DONE       = 4,
 134         STATE_ERROR      = 5,
 135         STATE_IDLE       = 6,
 136 };
 137
 138 struct videobuf_buffer {
 139         unsigned int            i;
 140         u32                     magic;
 141
 142         /* info about the buffer */
 143         unsigned int            width;
 144         unsigned int            height;
 145         unsigned int            bytesperline; /* use only if != 0 */
 146         unsigned long           size;
 147         unsigned int            input;
 148         enum v4l2_field         field;
 149         enum videobuf_state     state;
 150         struct videobuf_dmabuf  dma;
 151         struct list_head        stream;  /* QBUF/DQBUF list */
 152
 153         /* for mmap'ed buffers */
 154         enum v4l2_memory        memory;
 155         size_t                  boff;    /* buffer offset (mmap + overlay) */
 156         size_t                  bsize;   /* buffer size */
 157         unsigned long           baddr;   /* buffer addr (userland ptr!) */
 158         struct videobuf_mapping *map;
 159
 160         /* touched by irq handler */
 161         struct list_head        queue;
 162         wait_queue_head_t       done;
 163         unsigned int            field_count;
 164         struct timeval          ts;
 165 };
 166
 167 struct videobuf_queue_ops {
 168         int (*buf_setup)(struct file *file,
 169                          unsigned int *count, unsigned int *size);
 170         int (*buf_prepare)(struct file *file,struct videobuf_buffer *vb,
 171                            enum v4l2_field field);
 172         void (*buf_queue)(struct file *file,struct videobuf_buffer *vb);
 173         void (*buf_release)(struct file *file,struct videobuf_buffer *vb);
 174 };
 175
 176 struct videobuf_queue {
 177         struct semaphore           lock;
 178         spinlock_t                 *irqlock;
 179         struct pci_dev             *pci;
 180
 181         enum v4l2_buf_type         type;
 182         unsigned int               inputs; /* for V4L2_BUF_FLAG_INPUT */
 183         unsigned int               msize;
 184         enum v4l2_field            field;
 185         enum v4l2_field            last;   /* for field=V4L2_FIELD_ALTERNATE */
 186         struct videobuf_buffer     *bufs[VIDEO_MAX_FRAME];
 187         struct videobuf_queue_ops  *ops;
 188
 189         /* capture via mmap() + ioctl(QBUF/DQBUF) */
 190         unsigned int               streaming;
 191         struct list_head           stream;
 192
 193         /* capture via read() */
 194         unsigned int               reading;
 195         unsigned int               read_off;
 196         struct videobuf_buffer     *read_buf;
 197 };
 198
 199 void* videobuf_alloc(unsigned int size);
 200 int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr);
 201 int videobuf_iolock(struct pci_dev *pci, struct videobuf_buffer *vb,
 202                     struct v4l2_framebuffer *fbuf);
 203
 204 void videobuf_queue_init(struct videobuf_queue *q,
 205                          struct videobuf_queue_ops *ops,
 206                          struct pci_dev *pci, spinlock_t *irqlock,
 207                          enum v4l2_buf_type type,
 208                          enum v4l2_field field,
 209                          unsigned int msize);
 210 int  videobuf_queue_is_busy(struct videobuf_queue *q);
 211 void videobuf_queue_cancel(struct file *file, struct videobuf_queue *q);
 212
 213 enum v4l2_field videobuf_next_field(struct videobuf_queue *q);
 214 void videobuf_status(struct v4l2_buffer *b, struct videobuf_buffer *vb,
 215                      enum v4l2_buf_type type);
 216 int videobuf_reqbufs(struct file *file, struct videobuf_queue *q,
 217                      struct v4l2_requestbuffers *req);
 218 int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
 219 int videobuf_qbuf(struct file *file, struct videobuf_queue *q,
 220                   struct v4l2_buffer *b);
 221 int videobuf_dqbuf(struct file *file, struct videobuf_queue *q,
 222                    struct v4l2_buffer *b);
 223 int videobuf_streamon(struct file *file, struct videobuf_queue *q);
 224 int videobuf_streamoff(struct file *file, struct videobuf_queue *q);
 225
 226 int videobuf_read_start(struct file *file, struct videobuf_queue *q);
 227 void videobuf_read_stop(struct file *file, struct videobuf_queue *q);
 228 ssize_t videobuf_read_stream(struct file *file, struct videobuf_queue *q,
 229                              char __user *data, size_t count, loff_t *ppos,
 230                              int vbihack);
 231 ssize_t videobuf_read_one(struct file *file, struct videobuf_queue *q,
 232                           char __user *data, size_t count, loff_t *ppos);
 233 unsigned int videobuf_poll_stream(struct file *file,
 234                                   struct videobuf_queue *q,
 235                                   poll_table *wait);
 236
 237 int videobuf_mmap_setup(struct file *file, struct videobuf_queue *q,
 238                         unsigned int bcount, unsigned int bsize,
 239                         enum v4l2_memory memory);
 240 int videobuf_mmap_free(struct file *file, struct videobuf_queue *q);
 241 int videobuf_mmap_mapper(struct vm_area_struct *vma,
 242                          struct videobuf_queue *q);
 243
 244 /* --------------------------------------------------------------------- */
 245
 246 /*
 247  * Local variables:
 248  * c-basic-offset: 8
 249  * End:
 250  */