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