xref: /linux/include/media/videobuf2-core.h (revision b889fcf63cb62e7fdb7816565e28f44dbe4a76a5)
1 /*
2  * videobuf2-core.h - V4L2 driver helper framework
3  *
4  * Copyright (C) 2010 Samsung Electronics
5  *
6  * Author: Pawel Osciak <pawel@osciak.com>
7  *
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation.
11  */
12 #ifndef _MEDIA_VIDEOBUF2_CORE_H
13 #define _MEDIA_VIDEOBUF2_CORE_H
14 
15 #include <linux/mm_types.h>
16 #include <linux/mutex.h>
17 #include <linux/poll.h>
18 #include <linux/videodev2.h>
19 #include <linux/dma-buf.h>
20 
21 struct vb2_alloc_ctx;
22 struct vb2_fileio_data;
23 
24 /**
25  * struct vb2_mem_ops - memory handling/memory allocator operations
26  * @alloc:	allocate video memory and, optionally, allocator private data,
27  *		return NULL on failure or a pointer to allocator private,
28  *		per-buffer data on success; the returned private structure
29  *		will then be passed as buf_priv argument to other ops in this
30  *		structure
31  * @put:	inform the allocator that the buffer will no longer be used;
32  *		usually will result in the allocator freeing the buffer (if
33  *		no other users of this buffer are present); the buf_priv
34  *		argument is the allocator private per-buffer structure
35  *		previously returned from the alloc callback
36  * @get_userptr: acquire userspace memory for a hardware operation; used for
37  *		 USERPTR memory types; vaddr is the address passed to the
38  *		 videobuf layer when queuing a video buffer of USERPTR type;
39  *		 should return an allocator private per-buffer structure
40  *		 associated with the buffer on success, NULL on failure;
41  *		 the returned private structure will then be passed as buf_priv
42  *		 argument to other ops in this structure
43  * @put_userptr: inform the allocator that a USERPTR buffer will no longer
44  *		 be used
45  * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
46  *		   used for DMABUF memory types; alloc_ctx is the alloc context
47  *		   dbuf is the shared dma_buf; returns NULL on failure;
48  *		   allocator private per-buffer structure on success;
49  *		   this needs to be used for further accesses to the buffer
50  * @detach_dmabuf: inform the exporter of the buffer that the current DMABUF
51  *		   buffer is no longer used; the buf_priv argument is the
52  *		   allocator private per-buffer structure previously returned
53  *		   from the attach_dmabuf callback
54  * @map_dmabuf: request for access to the dmabuf from allocator; the allocator
55  *		of dmabuf is informed that this driver is going to use the
56  *		dmabuf
57  * @unmap_dmabuf: releases access control to the dmabuf - allocator is notified
58  *		  that this driver is done using the dmabuf for now
59  * @prepare:	called every time the buffer is passed from userspace to the
60  *		driver, useful for cache synchronisation, optional
61  * @finish:	called every time the buffer is passed back from the driver
62  *		to the userspace, also optional
63  * @vaddr:	return a kernel virtual address to a given memory buffer
64  *		associated with the passed private structure or NULL if no
65  *		such mapping exists
66  * @cookie:	return allocator specific cookie for a given memory buffer
67  *		associated with the passed private structure or NULL if not
68  *		available
69  * @num_users:	return the current number of users of a memory buffer;
70  *		return 1 if the videobuf layer (or actually the driver using
71  *		it) is the only user
72  * @mmap:	setup a userspace mapping for a given memory buffer under
73  *		the provided virtual memory region
74  *
75  * Required ops for USERPTR types: get_userptr, put_userptr.
76  * Required ops for MMAP types: alloc, put, num_users, mmap.
77  * Required ops for read/write access types: alloc, put, num_users, vaddr
78  * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
79  *				  unmap_dmabuf.
80  */
81 struct vb2_mem_ops {
82 	void		*(*alloc)(void *alloc_ctx, unsigned long size);
83 	void		(*put)(void *buf_priv);
84 	struct dma_buf *(*get_dmabuf)(void *buf_priv);
85 
86 	void		*(*get_userptr)(void *alloc_ctx, unsigned long vaddr,
87 					unsigned long size, int write);
88 	void		(*put_userptr)(void *buf_priv);
89 
90 	void		(*prepare)(void *buf_priv);
91 	void		(*finish)(void *buf_priv);
92 
93 	void		*(*attach_dmabuf)(void *alloc_ctx, struct dma_buf *dbuf,
94 				unsigned long size, int write);
95 	void		(*detach_dmabuf)(void *buf_priv);
96 	int		(*map_dmabuf)(void *buf_priv);
97 	void		(*unmap_dmabuf)(void *buf_priv);
98 
99 	void		*(*vaddr)(void *buf_priv);
100 	void		*(*cookie)(void *buf_priv);
101 
102 	unsigned int	(*num_users)(void *buf_priv);
103 
104 	int		(*mmap)(void *buf_priv, struct vm_area_struct *vma);
105 };
106 
107 struct vb2_plane {
108 	void			*mem_priv;
109 	struct dma_buf		*dbuf;
110 	unsigned int		dbuf_mapped;
111 };
112 
113 /**
114  * enum vb2_io_modes - queue access methods
115  * @VB2_MMAP:		driver supports MMAP with streaming API
116  * @VB2_USERPTR:	driver supports USERPTR with streaming API
117  * @VB2_READ:		driver supports read() style access
118  * @VB2_WRITE:		driver supports write() style access
119  * @VB2_DMABUF:		driver supports DMABUF with streaming API
120  */
121 enum vb2_io_modes {
122 	VB2_MMAP	= (1 << 0),
123 	VB2_USERPTR	= (1 << 1),
124 	VB2_READ	= (1 << 2),
125 	VB2_WRITE	= (1 << 3),
126 	VB2_DMABUF	= (1 << 4),
127 };
128 
129 /**
130  * enum vb2_fileio_flags - flags for selecting a mode of the file io emulator,
131  * by default the 'streaming' style is used by the file io emulator
132  * @VB2_FILEIO_READ_ONCE:	report EOF after reading the first buffer
133  * @VB2_FILEIO_WRITE_IMMEDIATELY:	queue buffer after each write() call
134  */
135 enum vb2_fileio_flags {
136 	VB2_FILEIO_READ_ONCE		= (1 << 0),
137 	VB2_FILEIO_WRITE_IMMEDIATELY	= (1 << 1),
138 };
139 
140 /**
141  * enum vb2_buffer_state - current video buffer state
142  * @VB2_BUF_STATE_DEQUEUED:	buffer under userspace control
143  * @VB2_BUF_STATE_PREPARED:	buffer prepared in videobuf and by the driver
144  * @VB2_BUF_STATE_QUEUED:	buffer queued in videobuf, but not in driver
145  * @VB2_BUF_STATE_ACTIVE:	buffer queued in driver and possibly used
146  *				in a hardware operation
147  * @VB2_BUF_STATE_DONE:		buffer returned from driver to videobuf, but
148  *				not yet dequeued to userspace
149  * @VB2_BUF_STATE_ERROR:	same as above, but the operation on the buffer
150  *				has ended with an error, which will be reported
151  *				to the userspace when it is dequeued
152  */
153 enum vb2_buffer_state {
154 	VB2_BUF_STATE_DEQUEUED,
155 	VB2_BUF_STATE_PREPARED,
156 	VB2_BUF_STATE_QUEUED,
157 	VB2_BUF_STATE_ACTIVE,
158 	VB2_BUF_STATE_DONE,
159 	VB2_BUF_STATE_ERROR,
160 };
161 
162 struct vb2_queue;
163 
164 /**
165  * struct vb2_buffer - represents a video buffer
166  * @v4l2_buf:		struct v4l2_buffer associated with this buffer; can
167  *			be read by the driver and relevant entries can be
168  *			changed by the driver in case of CAPTURE types
169  *			(such as timestamp)
170  * @v4l2_planes:	struct v4l2_planes associated with this buffer; can
171  *			be read by the driver and relevant entries can be
172  *			changed by the driver in case of CAPTURE types
173  *			(such as bytesused); NOTE that even for single-planar
174  *			types, the v4l2_planes[0] struct should be used
175  *			instead of v4l2_buf for filling bytesused - drivers
176  *			should use the vb2_set_plane_payload() function for that
177  * @vb2_queue:		the queue to which this driver belongs
178  * @num_planes:		number of planes in the buffer
179  *			on an internal driver queue
180  * @state:		current buffer state; do not change
181  * @queued_entry:	entry on the queued buffers list, which holds all
182  *			buffers queued from userspace
183  * @done_entry:		entry on the list that stores all buffers ready to
184  *			be dequeued to userspace
185  * @planes:		private per-plane information; do not change
186  */
187 struct vb2_buffer {
188 	struct v4l2_buffer	v4l2_buf;
189 	struct v4l2_plane	v4l2_planes[VIDEO_MAX_PLANES];
190 
191 	struct vb2_queue	*vb2_queue;
192 
193 	unsigned int		num_planes;
194 
195 /* Private: internal use only */
196 	enum vb2_buffer_state	state;
197 
198 	struct list_head	queued_entry;
199 	struct list_head	done_entry;
200 
201 	struct vb2_plane	planes[VIDEO_MAX_PLANES];
202 };
203 
204 /**
205  * struct vb2_ops - driver-specific callbacks
206  *
207  * @queue_setup:	called from VIDIOC_REQBUFS and VIDIOC_CREATE_BUFS
208  *			handlers before memory allocation, or, if
209  *			*num_planes != 0, after the allocation to verify a
210  *			smaller number of buffers. Driver should return
211  *			the required number of buffers in *num_buffers, the
212  *			required number of planes per buffer in *num_planes; the
213  *			size of each plane should be set in the sizes[] array
214  *			and optional per-plane allocator specific context in the
215  *			alloc_ctxs[] array. When called from VIDIOC_REQBUFS,
216  *			fmt == NULL, the driver has to use the currently
217  *			configured format and *num_buffers is the total number
218  *			of buffers, that are being allocated. When called from
219  *			VIDIOC_CREATE_BUFS, fmt != NULL and it describes the
220  *			target frame format. In this case *num_buffers are being
221  *			allocated additionally to q->num_buffers.
222  * @wait_prepare:	release any locks taken while calling vb2 functions;
223  *			it is called before an ioctl needs to wait for a new
224  *			buffer to arrive; required to avoid a deadlock in
225  *			blocking access type
226  * @wait_finish:	reacquire all locks released in the previous callback;
227  *			required to continue operation after sleeping while
228  *			waiting for a new buffer to arrive
229  * @buf_init:		called once after allocating a buffer (in MMAP case)
230  *			or after acquiring a new USERPTR buffer; drivers may
231  *			perform additional buffer-related initialization;
232  *			initialization failure (return != 0) will prevent
233  *			queue setup from completing successfully; optional
234  * @buf_prepare:	called every time the buffer is queued from userspace
235  *			and from the VIDIOC_PREPARE_BUF ioctl; drivers may
236  *			perform any initialization required before each hardware
237  *			operation in this callback; if an error is returned, the
238  *			buffer will not be queued in driver; optional
239  * @buf_finish:		called before every dequeue of the buffer back to
240  *			userspace; drivers may perform any operations required
241  *			before userspace accesses the buffer; optional
242  * @buf_cleanup:	called once before the buffer is freed; drivers may
243  *			perform any additional cleanup; optional
244  * @start_streaming:	called once to enter 'streaming' state; the driver may
245  *			receive buffers with @buf_queue callback before
246  *			@start_streaming is called; the driver gets the number
247  *			of already queued buffers in count parameter; driver
248  *			can return an error if hardware fails or not enough
249  *			buffers has been queued, in such case all buffers that
250  *			have been already given by the @buf_queue callback are
251  *			invalidated.
252  * @stop_streaming:	called when 'streaming' state must be disabled; driver
253  *			should stop any DMA transactions or wait until they
254  *			finish and give back all buffers it got from buf_queue()
255  *			callback; may use vb2_wait_for_all_buffers() function
256  * @buf_queue:		passes buffer vb to the driver; driver may start
257  *			hardware operation on this buffer; driver should give
258  *			the buffer back by calling vb2_buffer_done() function;
259  *			it is allways called after calling STREAMON ioctl;
260  *			might be called before start_streaming callback if user
261  *			pre-queued buffers before calling STREAMON
262  */
263 struct vb2_ops {
264 	int (*queue_setup)(struct vb2_queue *q, const struct v4l2_format *fmt,
265 			   unsigned int *num_buffers, unsigned int *num_planes,
266 			   unsigned int sizes[], void *alloc_ctxs[]);
267 
268 	void (*wait_prepare)(struct vb2_queue *q);
269 	void (*wait_finish)(struct vb2_queue *q);
270 
271 	int (*buf_init)(struct vb2_buffer *vb);
272 	int (*buf_prepare)(struct vb2_buffer *vb);
273 	int (*buf_finish)(struct vb2_buffer *vb);
274 	void (*buf_cleanup)(struct vb2_buffer *vb);
275 
276 	int (*start_streaming)(struct vb2_queue *q, unsigned int count);
277 	int (*stop_streaming)(struct vb2_queue *q);
278 
279 	void (*buf_queue)(struct vb2_buffer *vb);
280 };
281 
282 struct v4l2_fh;
283 
284 /**
285  * struct vb2_queue - a videobuf queue
286  *
287  * @type:	queue type (see V4L2_BUF_TYPE_* in linux/videodev2.h
288  * @io_modes:	supported io methods (see vb2_io_modes enum)
289  * @io_flags:	additional io flags (see vb2_fileio_flags enum)
290  * @lock:	pointer to a mutex that protects the vb2_queue struct. The
291  *		driver can set this to a mutex to let the v4l2 core serialize
292  *		the queuing ioctls. If the driver wants to handle locking
293  *		itself, then this should be set to NULL. This lock is not used
294  *		by the videobuf2 core API.
295  * @owner:	The filehandle that 'owns' the buffers, i.e. the filehandle
296  *		that called reqbufs, create_buffers or started fileio.
297  *		This field is not used by the videobuf2 core API, but it allows
298  *		drivers to easily associate an owner filehandle with the queue.
299  * @ops:	driver-specific callbacks
300  * @mem_ops:	memory allocator specific callbacks
301  * @drv_priv:	driver private data
302  * @buf_struct_size: size of the driver-specific buffer structure;
303  *		"0" indicates the driver doesn't want to use a custom buffer
304  *		structure type, so sizeof(struct vb2_buffer) will is used
305  *
306  * @memory:	current memory type used
307  * @bufs:	videobuf buffer structures
308  * @num_buffers: number of allocated/used buffers
309  * @queued_list: list of buffers currently queued from userspace
310  * @queued_count: number of buffers owned by the driver
311  * @done_list:	list of buffers ready to be dequeued to userspace
312  * @done_lock:	lock to protect done_list list
313  * @done_wq:	waitqueue for processes waiting for buffers ready to be dequeued
314  * @alloc_ctx:	memory type/allocator-specific contexts for each plane
315  * @streaming:	current streaming state
316  * @fileio:	file io emulator internal data, used only if emulator is active
317  */
318 struct vb2_queue {
319 	enum v4l2_buf_type		type;
320 	unsigned int			io_modes;
321 	unsigned int			io_flags;
322 	struct mutex			*lock;
323 	struct v4l2_fh			*owner;
324 
325 	const struct vb2_ops		*ops;
326 	const struct vb2_mem_ops	*mem_ops;
327 	void				*drv_priv;
328 	unsigned int			buf_struct_size;
329 
330 /* private: internal use only */
331 	enum v4l2_memory		memory;
332 	struct vb2_buffer		*bufs[VIDEO_MAX_FRAME];
333 	unsigned int			num_buffers;
334 
335 	struct list_head		queued_list;
336 
337 	atomic_t			queued_count;
338 	struct list_head		done_list;
339 	spinlock_t			done_lock;
340 	wait_queue_head_t		done_wq;
341 
342 	void				*alloc_ctx[VIDEO_MAX_PLANES];
343 	unsigned int			plane_sizes[VIDEO_MAX_PLANES];
344 
345 	unsigned int			streaming:1;
346 
347 	struct vb2_fileio_data		*fileio;
348 };
349 
350 void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
351 void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
352 
353 void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
354 int vb2_wait_for_all_buffers(struct vb2_queue *q);
355 
356 int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
357 int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
358 
359 int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
360 int vb2_prepare_buf(struct vb2_queue *q, struct v4l2_buffer *b);
361 
362 int __must_check vb2_queue_init(struct vb2_queue *q);
363 
364 void vb2_queue_release(struct vb2_queue *q);
365 
366 int vb2_qbuf(struct vb2_queue *q, struct v4l2_buffer *b);
367 int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
368 int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
369 
370 int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
371 int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type);
372 
373 int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
374 #ifndef CONFIG_MMU
375 unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
376 				    unsigned long addr,
377 				    unsigned long len,
378 				    unsigned long pgoff,
379 				    unsigned long flags);
380 #endif
381 unsigned int vb2_poll(struct vb2_queue *q, struct file *file, poll_table *wait);
382 size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
383 		loff_t *ppos, int nonblock);
384 size_t vb2_write(struct vb2_queue *q, char __user *data, size_t count,
385 		loff_t *ppos, int nonblock);
386 
387 /**
388  * vb2_is_streaming() - return streaming status of the queue
389  * @q:		videobuf queue
390  */
391 static inline bool vb2_is_streaming(struct vb2_queue *q)
392 {
393 	return q->streaming;
394 }
395 
396 /**
397  * vb2_is_busy() - return busy status of the queue
398  * @q:		videobuf queue
399  *
400  * This function checks if queue has any buffers allocated.
401  */
402 static inline bool vb2_is_busy(struct vb2_queue *q)
403 {
404 	return (q->num_buffers > 0);
405 }
406 
407 /**
408  * vb2_get_drv_priv() - return driver private data associated with the queue
409  * @q:		videobuf queue
410  */
411 static inline void *vb2_get_drv_priv(struct vb2_queue *q)
412 {
413 	return q->drv_priv;
414 }
415 
416 /**
417  * vb2_set_plane_payload() - set bytesused for the plane plane_no
418  * @vb:		buffer for which plane payload should be set
419  * @plane_no:	plane number for which payload should be set
420  * @size:	payload in bytes
421  */
422 static inline void vb2_set_plane_payload(struct vb2_buffer *vb,
423 				 unsigned int plane_no, unsigned long size)
424 {
425 	if (plane_no < vb->num_planes)
426 		vb->v4l2_planes[plane_no].bytesused = size;
427 }
428 
429 /**
430  * vb2_get_plane_payload() - get bytesused for the plane plane_no
431  * @vb:		buffer for which plane payload should be set
432  * @plane_no:	plane number for which payload should be set
433  * @size:	payload in bytes
434  */
435 static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb,
436 				 unsigned int plane_no)
437 {
438 	if (plane_no < vb->num_planes)
439 		return vb->v4l2_planes[plane_no].bytesused;
440 	return 0;
441 }
442 
443 /**
444  * vb2_plane_size() - return plane size in bytes
445  * @vb:		buffer for which plane size should be returned
446  * @plane_no:	plane number for which size should be returned
447  */
448 static inline unsigned long
449 vb2_plane_size(struct vb2_buffer *vb, unsigned int plane_no)
450 {
451 	if (plane_no < vb->num_planes)
452 		return vb->v4l2_planes[plane_no].length;
453 	return 0;
454 }
455 
456 /*
457  * The following functions are not part of the vb2 core API, but are simple
458  * helper functions that you can use in your struct v4l2_file_operations,
459  * struct v4l2_ioctl_ops and struct vb2_ops. They will serialize if vb2_queue->lock
460  * or video_device->lock is set, and they will set and test vb2_queue->owner
461  * to check if the calling filehandle is permitted to do the queuing operation.
462  */
463 
464 /* struct v4l2_ioctl_ops helpers */
465 
466 int vb2_ioctl_reqbufs(struct file *file, void *priv,
467 			  struct v4l2_requestbuffers *p);
468 int vb2_ioctl_create_bufs(struct file *file, void *priv,
469 			  struct v4l2_create_buffers *p);
470 int vb2_ioctl_prepare_buf(struct file *file, void *priv,
471 			  struct v4l2_buffer *p);
472 int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p);
473 int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p);
474 int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p);
475 int vb2_ioctl_streamon(struct file *file, void *priv, enum v4l2_buf_type i);
476 int vb2_ioctl_streamoff(struct file *file, void *priv, enum v4l2_buf_type i);
477 int vb2_ioctl_expbuf(struct file *file, void *priv,
478 	struct v4l2_exportbuffer *p);
479 
480 /* struct v4l2_file_operations helpers */
481 
482 int vb2_fop_mmap(struct file *file, struct vm_area_struct *vma);
483 int vb2_fop_release(struct file *file);
484 ssize_t vb2_fop_write(struct file *file, char __user *buf,
485 		size_t count, loff_t *ppos);
486 ssize_t vb2_fop_read(struct file *file, char __user *buf,
487 		size_t count, loff_t *ppos);
488 unsigned int vb2_fop_poll(struct file *file, poll_table *wait);
489 #ifndef CONFIG_MMU
490 unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr,
491 		unsigned long len, unsigned long pgoff, unsigned long flags);
492 #endif
493 
494 /* struct vb2_ops helpers, only use if vq->lock is non-NULL. */
495 
496 void vb2_ops_wait_prepare(struct vb2_queue *vq);
497 void vb2_ops_wait_finish(struct vb2_queue *vq);
498 
499 #endif /* _MEDIA_VIDEOBUF2_CORE_H */
500