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