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