[deliverable/linux.git] / include / media / video-buf.h

/*
 *
 * generic helper functions for video4linux capture buffers, to handle
 * memory management and PCI DMA.
 * Right now, bttv, saa7134, saa7146 and cx88 use it.
 *
 * The functions expect the hardware being able to scatter gatter
 * (i.e. the buffers are not linear in physical memory, but fragmented
 * into PAGE_SIZE chunks).  They also assume the driver does not need
 * to touch the video data.
 *
 * device specific map/unmap/sync stuff now are mapped as file operations
 * to allow its usage by USB and virtual devices.
 *
 * (c) 2001,02 Gerd Knorr <kraxel@bytesex.org>
 * (c) 2006 Mauro Carvalho Chehab, <mchehab@infradead.org>
 * (c) 2006 Ted Walther and John Sokol
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 */

#include <linux/videodev2.h>

#define UNSET (-1U)

/* --------------------------------------------------------------------- */

/*
 * Return a scatterlist for some page-aligned vmalloc()'ed memory
 * block (NULL on errors).  Memory for the scatterlist is allocated
 * using kmalloc.  The caller must free the memory.
 */
struct scatterlist* videobuf_vmalloc_to_sg(unsigned char *virt, int nr_pages);

/*
 * Return a scatterlist for a an array of userpages (NULL on errors).
 * Memory for the scatterlist is allocated using kmalloc.  The caller
 * must free the memory.
 */
struct scatterlist* videobuf_pages_to_sg(struct page **pages, int nr_pages,
					 int offset);

struct videobuf_buffer;
struct videobuf_queue;

/* --------------------------------------------------------------------- */

/*
 * A small set of helper functions to manage buffers (both userland
 * and kernel) for DMA.
 *
 * videobuf_dma_init_*()
 *	creates a buffer.  The userland version takes a userspace
 *	pointer + length.  The kernel version just wants the size and
 *	does memory allocation too using vmalloc_32().
 *
 * videobuf_dma_*()
 *	see Documentation/DMA-mapping.txt, these functions to
 *	basically the same.  The map function does also build a
 *	scatterlist for the buffer (and unmap frees it ...)
 *
 * videobuf_dma_free()
 *	no comment ...
 *
 */

struct videobuf_dmabuf {
	u32                 magic;

	/* for userland buffer */
	int                 offset;
	struct page         **pages;

	/* for kernel buffers */
	void                *vmalloc;

	/* for overlay buffers (pci-pci dma) */
	dma_addr_t          bus_addr;

	/* common */
	struct scatterlist  *sglist;
	int                 sglen;
	int                 nr_pages;
	int                 direction;
};

void videobuf_dma_init(struct videobuf_dmabuf *dma);
int videobuf_dma_init_user(struct videobuf_dmabuf *dma, int direction,
			   unsigned long data, unsigned long size);
int videobuf_dma_init_kernel(struct videobuf_dmabuf *dma, int direction,
			     int nr_pages);
int videobuf_dma_init_overlay(struct videobuf_dmabuf *dma, int direction,
			      dma_addr_t addr, int nr_pages);
int videobuf_dma_free(struct videobuf_dmabuf *dma);

int videobuf_dma_map(struct videobuf_queue* q,struct videobuf_dmabuf *dma);
int videobuf_dma_sync(struct videobuf_queue* q,struct videobuf_dmabuf *dma);
int videobuf_dma_unmap(struct videobuf_queue* q,struct videobuf_dmabuf *dma);

	/*FIXME: these variants are used only on *-alsa code, where videobuf is
	 * used without queue
	 */
int videobuf_pci_dma_map(struct pci_dev *pci,struct videobuf_dmabuf *dma);
int videobuf_pci_dma_unmap(struct pci_dev *pci,struct videobuf_dmabuf *dma);

/* --------------------------------------------------------------------- */

/*
 * A small set of helper functions to manage video4linux buffers.
 *
 * struct videobuf_buffer holds the data structures used by the helper
 * functions, additionally some commonly used fields for v4l buffers
 * (width, height, lists, waitqueue) are in there.  That struct should
 * be used as first element in the drivers buffer struct.
 *
 * about the mmap helpers (videobuf_mmap_*):
 *
 * The mmaper function allows to map any subset of contingous buffers.
 * This includes one mmap() call for all buffers (which the original
 * video4linux API uses) as well as one mmap() for every single buffer
 * (which v4l2 uses).
 *
 * If there is a valid mapping for a buffer, buffer->baddr/bsize holds
 * userspace address + size which can be feeded into the
 * videobuf_dma_init_user function listed above.
 *
 */

struct videobuf_mapping {
	unsigned int count;
	unsigned long start;
	unsigned long end;
	struct videobuf_queue *q;
};

enum videobuf_state {
	STATE_NEEDS_INIT = 0,
	STATE_PREPARED   = 1,
	STATE_QUEUED     = 2,
	STATE_ACTIVE     = 3,
	STATE_DONE       = 4,
	STATE_ERROR      = 5,
	STATE_IDLE       = 6,
};

struct videobuf_buffer {
	unsigned int            i;
	u32                     magic;

	/* info about the buffer */
	unsigned int            width;
	unsigned int            height;
	unsigned int            bytesperline; /* use only if != 0 */
	unsigned long           size;
	unsigned int            input;
	enum v4l2_field         field;
	enum videobuf_state     state;
	struct videobuf_dmabuf  dma;
	struct list_head        stream;  /* QBUF/DQBUF list */

	/* for mmap'ed buffers */
	enum v4l2_memory        memory;
	size_t                  boff;    /* buffer offset (mmap + overlay) */
	size_t                  bsize;   /* buffer size */
	unsigned long           baddr;   /* buffer addr (userland ptr!) */
	struct videobuf_mapping *map;

	/* touched by irq handler */
	struct list_head        queue;
	wait_queue_head_t       done;
	unsigned int            field_count;
	struct timeval          ts;
};

typedef int (vb_map_sg_t)(void *dev,struct scatterlist *sglist,int nr_pages,
					int direction);


struct videobuf_queue_ops {
	int (*buf_setup)(struct videobuf_queue *q,
			 unsigned int *count, unsigned int *size);
	int (*buf_prepare)(struct videobuf_queue *q,
			   struct videobuf_buffer *vb,
			   enum v4l2_field field);
	void (*buf_queue)(struct videobuf_queue *q,
			  struct videobuf_buffer *vb);
	void (*buf_release)(struct videobuf_queue *q,
			    struct videobuf_buffer *vb);

	/* Helper operations - device dependent.
	 * If null, videobuf_init defaults all to PCI handling
	 */

	vb_map_sg_t	*vb_map_sg;
	vb_map_sg_t	*vb_dma_sync_sg;
	vb_map_sg_t	*vb_unmap_sg;
};

struct videobuf_queue {
	struct mutex               lock;
	spinlock_t                 *irqlock;
	void			   *dev; /* on pci, points to struct pci_dev */

	enum v4l2_buf_type         type;
	unsigned int               inputs; /* for V4L2_BUF_FLAG_INPUT */
	unsigned int               msize;
	enum v4l2_field            field;
	enum v4l2_field            last;   /* for field=V4L2_FIELD_ALTERNATE */
	struct videobuf_buffer     *bufs[VIDEO_MAX_FRAME];
	struct videobuf_queue_ops  *ops;

	/* capture via mmap() + ioctl(QBUF/DQBUF) */
	unsigned int               streaming;
	struct list_head           stream;

	/* capture via read() */
	unsigned int               reading;
	unsigned int               read_off;
	struct videobuf_buffer     *read_buf;

	/* driver private data */
	void                       *priv_data;
};

void* videobuf_alloc(unsigned int size);
int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr);
int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb,
		struct v4l2_framebuffer *fbuf);

/* Maps fops to PCI stuff */
void videobuf_queue_pci(struct videobuf_queue* q);

void videobuf_queue_init(struct videobuf_queue *q,
			 struct videobuf_queue_ops *ops,
			 void *dev,
			 spinlock_t *irqlock,
			 enum v4l2_buf_type type,
			 enum v4l2_field field,
			 unsigned int msize,
			 void *priv);
int  videobuf_queue_is_busy(struct videobuf_queue *q);
void videobuf_queue_cancel(struct videobuf_queue *q);

enum v4l2_field videobuf_next_field(struct videobuf_queue *q);
void videobuf_status(struct v4l2_buffer *b, struct videobuf_buffer *vb,
		     enum v4l2_buf_type type);
int videobuf_reqbufs(struct videobuf_queue *q,
		     struct v4l2_requestbuffers *req);
int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
int videobuf_qbuf(struct videobuf_queue *q,
		  struct v4l2_buffer *b);
int videobuf_dqbuf(struct videobuf_queue *q,
		   struct v4l2_buffer *b, int nonblocking);
int videobuf_streamon(struct videobuf_queue *q);
int videobuf_streamoff(struct videobuf_queue *q);

int videobuf_read_start(struct videobuf_queue *q);
void videobuf_read_stop(struct videobuf_queue *q);
ssize_t videobuf_read_stream(struct videobuf_queue *q,
			     char __user *data, size_t count, loff_t *ppos,
			     int vbihack, int nonblocking);
ssize_t videobuf_read_one(struct videobuf_queue *q,
			  char __user *data, size_t count, loff_t *ppos,
			  int nonblocking);
unsigned int videobuf_poll_stream(struct file *file,
				  struct videobuf_queue *q,
				  poll_table *wait);

int videobuf_mmap_setup(struct videobuf_queue *q,
			unsigned int bcount, unsigned int bsize,
			enum v4l2_memory memory);
int videobuf_mmap_free(struct videobuf_queue *q);
int videobuf_mmap_mapper(struct videobuf_queue *q,
			 struct vm_area_struct *vma);

/* --------------------------------------------------------------------- */

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