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