1 /*
2  * videobuf2-v4l2.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_V4L2_H
13 #define _MEDIA_VIDEOBUF2_V4L2_H
14 
15 #include <linux/videodev2.h>
16 #include <media/videobuf2-core.h>
17 
18 #if VB2_MAX_FRAME != VIDEO_MAX_FRAME
19 #error VB2_MAX_FRAME != VIDEO_MAX_FRAME
20 #endif
21 
22 #if VB2_MAX_PLANES != VIDEO_MAX_PLANES
23 #error VB2_MAX_PLANES != VIDEO_MAX_PLANES
24 #endif
25 
26 /**
27  * struct vb2_v4l2_buffer - video buffer information for v4l2.
28  *
29  * @vb2_buf:	embedded struct &vb2_buffer.
30  * @flags:	buffer informational flags.
31  * @field:	field order of the image in the buffer, as defined by
32  *		&enum v4l2_field.
33  * @timecode:	frame timecode.
34  * @sequence:	sequence count of this frame.
35  * @request_fd:	the request_fd associated with this buffer
36  * @planes:	plane information (userptr/fd, length, bytesused, data_offset).
37  *
38  * Should contain enough information to be able to cover all the fields
39  * of &struct v4l2_buffer at ``videodev2.h``.
40  */
41 struct vb2_v4l2_buffer {
42 	struct vb2_buffer	vb2_buf;
43 
44 	__u32			flags;
45 	__u32			field;
46 	struct v4l2_timecode	timecode;
47 	__u32			sequence;
48 	__s32			request_fd;
49 	struct vb2_plane	planes[VB2_MAX_PLANES];
50 };
51 
52 /*
53  * to_vb2_v4l2_buffer() - cast struct vb2_buffer * to struct vb2_v4l2_buffer *
54  */
55 #define to_vb2_v4l2_buffer(vb) \
56 	container_of(vb, struct vb2_v4l2_buffer, vb2_buf)
57 
58 int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b);
59 
60 /**
61  * vb2_reqbufs() - Wrapper for vb2_core_reqbufs() that also verifies
62  * the memory and type values.
63  *
64  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
65  * @req:	&struct v4l2_requestbuffers passed from userspace to
66  *		&v4l2_ioctl_ops->vidioc_reqbufs handler in driver.
67  */
68 int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req);
69 
70 /**
71  * vb2_create_bufs() - Wrapper for vb2_core_create_bufs() that also verifies
72  * the memory and type values.
73  *
74  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
75  * @create:	creation parameters, passed from userspace to
76  *		&v4l2_ioctl_ops->vidioc_create_bufs handler in driver
77  */
78 int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create);
79 
80 /**
81  * vb2_prepare_buf() - Pass ownership of a buffer from userspace to the kernel
82  *
83  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
84  * @mdev:	pointer to &struct media_device, may be NULL.
85  * @b:		buffer structure passed from userspace to
86  *		&v4l2_ioctl_ops->vidioc_prepare_buf handler in driver
87  *
88  * Should be called from &v4l2_ioctl_ops->vidioc_prepare_buf ioctl handler
89  * of a driver.
90  *
91  * This function:
92  *
93  * #) verifies the passed buffer,
94  * #) calls &vb2_ops->buf_prepare callback in the driver (if provided),
95  *    in which driver-specific buffer initialization can be performed.
96  * #) if @b->request_fd is non-zero and @mdev->ops->req_queue is set,
97  *    then bind the prepared buffer to the request.
98  *
99  * The return values from this function are intended to be directly returned
100  * from &v4l2_ioctl_ops->vidioc_prepare_buf handler in driver.
101  */
102 int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev,
103 		    struct v4l2_buffer *b);
104 
105 /**
106  * vb2_qbuf() - Queue a buffer from userspace
107  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
108  * @mdev:	pointer to &struct media_device, may be NULL.
109  * @b:		buffer structure passed from userspace to
110  *		&v4l2_ioctl_ops->vidioc_qbuf handler in driver
111  *
112  * Should be called from &v4l2_ioctl_ops->vidioc_qbuf handler of a driver.
113  *
114  * This function:
115  *
116  * #) verifies the passed buffer;
117  * #) if @b->request_fd is non-zero and @mdev->ops->req_queue is set,
118  *    then bind the buffer to the request.
119  * #) if necessary, calls &vb2_ops->buf_prepare callback in the driver
120  *    (if provided), in which driver-specific buffer initialization can
121  *    be performed;
122  * #) if streaming is on, queues the buffer in driver by the means of
123  *    &vb2_ops->buf_queue callback for processing.
124  *
125  * The return values from this function are intended to be directly returned
126  * from &v4l2_ioctl_ops->vidioc_qbuf handler in driver.
127  */
128 int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev,
129 	     struct v4l2_buffer *b);
130 
131 /**
132  * vb2_expbuf() - Export a buffer as a file descriptor
133  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
134  * @eb:		export buffer structure passed from userspace to
135  *		&v4l2_ioctl_ops->vidioc_expbuf handler in driver
136  *
137  * The return values from this function are intended to be directly returned
138  * from &v4l2_ioctl_ops->vidioc_expbuf handler in driver.
139  */
140 int vb2_expbuf(struct vb2_queue *q, struct v4l2_exportbuffer *eb);
141 
142 /**
143  * vb2_dqbuf() - Dequeue a buffer to the userspace
144  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
145  * @b:		buffer structure passed from userspace to
146  *		&v4l2_ioctl_ops->vidioc_dqbuf handler in driver
147  * @nonblocking: if true, this call will not sleep waiting for a buffer if no
148  *		 buffers ready for dequeuing are present. Normally the driver
149  *		 would be passing (&file->f_flags & %O_NONBLOCK) here
150  *
151  * Should be called from &v4l2_ioctl_ops->vidioc_dqbuf ioctl handler
152  * of a driver.
153  *
154  * This function:
155  *
156  * #) verifies the passed buffer;
157  * #) calls &vb2_ops->buf_finish callback in the driver (if provided), in which
158  *    driver can perform any additional operations that may be required before
159  *    returning the buffer to userspace, such as cache sync;
160  * #) the buffer struct members are filled with relevant information for
161  *    the userspace.
162  *
163  * The return values from this function are intended to be directly returned
164  * from &v4l2_ioctl_ops->vidioc_dqbuf handler in driver.
165  */
166 int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking);
167 
168 /**
169  * vb2_streamon - start streaming
170  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
171  * @type:	type argument passed from userspace to vidioc_streamon handler,
172  *		as defined by &enum v4l2_buf_type.
173  *
174  * Should be called from &v4l2_ioctl_ops->vidioc_streamon handler of a driver.
175  *
176  * This function:
177  *
178  * 1) verifies current state
179  * 2) passes any previously queued buffers to the driver and starts streaming
180  *
181  * The return values from this function are intended to be directly returned
182  * from &v4l2_ioctl_ops->vidioc_streamon handler in the driver.
183  */
184 int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type);
185 
186 /**
187  * vb2_streamoff - stop streaming
188  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
189  * @type:	type argument passed from userspace to vidioc_streamoff handler
190  *
191  * Should be called from vidioc_streamoff handler of a driver.
192  *
193  * This function:
194  *
195  * #) verifies current state,
196  * #) stop streaming and dequeues any queued buffers, including those previously
197  *    passed to the driver (after waiting for the driver to finish).
198  *
199  * This call can be used for pausing playback.
200  * The return values from this function are intended to be directly returned
201  * from vidioc_streamoff handler in the driver
202  */
203 int vb2_streamoff(struct vb2_queue *q, enum v4l2_buf_type type);
204 
205 /**
206  * vb2_queue_init() - initialize a videobuf2 queue
207  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
208  *
209  * The vb2_queue structure should be allocated by the driver. The driver is
210  * responsible of clearing it's content and setting initial values for some
211  * required entries before calling this function.
212  * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
213  * to the struct vb2_queue description in include/media/videobuf2-core.h
214  * for more information.
215  */
216 int __must_check vb2_queue_init(struct vb2_queue *q);
217 
218 /**
219  * vb2_queue_release() - stop streaming, release the queue and free memory
220  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
221  *
222  * This function stops streaming and performs necessary clean ups, including
223  * freeing video buffer memory. The driver is responsible for freeing
224  * the vb2_queue structure itself.
225  */
226 void vb2_queue_release(struct vb2_queue *q);
227 
228 /**
229  * vb2_poll() - implements poll userspace operation
230  * @q:		pointer to &struct vb2_queue with videobuf2 queue.
231  * @file:	file argument passed to the poll file operation handler
232  * @wait:	wait argument passed to the poll file operation handler
233  *
234  * This function implements poll file operation handler for a driver.
235  * For CAPTURE queues, if a buffer is ready to be dequeued, the userspace will
236  * be informed that the file descriptor of a video device is available for
237  * reading.
238  * For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptor
239  * will be reported as available for writing.
240  *
241  * If the driver uses struct v4l2_fh, then vb2_poll() will also check for any
242  * pending events.
243  *
244  * The return values from this function are intended to be directly returned
245  * from poll handler in driver.
246  */
247 __poll_t vb2_poll(struct vb2_queue *q, struct file *file, poll_table *wait);
248 
249 /*
250  * The following functions are not part of the vb2 core API, but are simple
251  * helper functions that you can use in your struct v4l2_file_operations,
252  * struct v4l2_ioctl_ops and struct vb2_ops. They will serialize if vb2_queue->lock
253  * or video_device->lock is set, and they will set and test vb2_queue->owner
254  * to check if the calling filehandle is permitted to do the queuing operation.
255  */
256 
257 /* struct v4l2_ioctl_ops helpers */
258 
259 int vb2_ioctl_reqbufs(struct file *file, void *priv,
260 			  struct v4l2_requestbuffers *p);
261 int vb2_ioctl_create_bufs(struct file *file, void *priv,
262 			  struct v4l2_create_buffers *p);
263 int vb2_ioctl_prepare_buf(struct file *file, void *priv,
264 			  struct v4l2_buffer *p);
265 int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p);
266 int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p);
267 int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p);
268 int vb2_ioctl_streamon(struct file *file, void *priv, enum v4l2_buf_type i);
269 int vb2_ioctl_streamoff(struct file *file, void *priv, enum v4l2_buf_type i);
270 int vb2_ioctl_expbuf(struct file *file, void *priv,
271 	struct v4l2_exportbuffer *p);
272 
273 /* struct v4l2_file_operations helpers */
274 
275 int vb2_fop_mmap(struct file *file, struct vm_area_struct *vma);
276 int vb2_fop_release(struct file *file);
277 int _vb2_fop_release(struct file *file, struct mutex *lock);
278 ssize_t vb2_fop_write(struct file *file, const char __user *buf,
279 		size_t count, loff_t *ppos);
280 ssize_t vb2_fop_read(struct file *file, char __user *buf,
281 		size_t count, loff_t *ppos);
282 __poll_t vb2_fop_poll(struct file *file, poll_table *wait);
283 #ifndef CONFIG_MMU
284 unsigned long vb2_fop_get_unmapped_area(struct file *file, unsigned long addr,
285 		unsigned long len, unsigned long pgoff, unsigned long flags);
286 #endif
287 
288 /**
289  * vb2_ops_wait_prepare - helper function to lock a struct &vb2_queue
290  *
291  * @vq: pointer to &struct vb2_queue
292  *
293  * ..note:: only use if vq->lock is non-NULL.
294  */
295 void vb2_ops_wait_prepare(struct vb2_queue *vq);
296 
297 /**
298  * vb2_ops_wait_finish - helper function to unlock a struct &vb2_queue
299  *
300  * @vq: pointer to &struct vb2_queue
301  *
302  * ..note:: only use if vq->lock is non-NULL.
303  */
304 void vb2_ops_wait_finish(struct vb2_queue *vq);
305 
306 struct media_request;
307 int vb2_request_validate(struct media_request *req);
308 void vb2_request_queue(struct media_request *req);
309 
310 #endif /* _MEDIA_VIDEOBUF2_V4L2_H */
311