1 /* 2 * Memory-to-memory device framework for Video for Linux 2. 3 * 4 * Helper functions for devices that use memory buffers for both source 5 * and destination. 6 * 7 * Copyright (c) 2009 Samsung Electronics Co., Ltd. 8 * Pawel Osciak, <pawel@osciak.com> 9 * Marek Szyprowski, <m.szyprowski@samsung.com> 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of the GNU General Public License as published by the 13 * Free Software Foundation; either version 2 of the 14 * License, or (at your option) any later version 15 */ 16 17 #ifndef _MEDIA_V4L2_MEM2MEM_H 18 #define _MEDIA_V4L2_MEM2MEM_H 19 20 #include <media/videobuf2-v4l2.h> 21 22 /** 23 * struct v4l2_m2m_ops - mem-to-mem device driver callbacks 24 * @device_run: required. Begin the actual job (transaction) inside this 25 * callback. 26 * The job does NOT have to end before this callback returns 27 * (and it will be the usual case). When the job finishes, 28 * v4l2_m2m_job_finish() has to be called. 29 * @job_ready: optional. Should return 0 if the driver does not have a job 30 * fully prepared to run yet (i.e. it will not be able to finish a 31 * transaction without sleeping). If not provided, it will be 32 * assumed that one source and one destination buffer are all 33 * that is required for the driver to perform one full transaction. 34 * This method may not sleep. 35 * @job_abort: required. Informs the driver that it has to abort the currently 36 * running transaction as soon as possible (i.e. as soon as it can 37 * stop the device safely; e.g. in the next interrupt handler), 38 * even if the transaction would not have been finished by then. 39 * After the driver performs the necessary steps, it has to call 40 * v4l2_m2m_job_finish() (as if the transaction ended normally). 41 * This function does not have to (and will usually not) wait 42 * until the device enters a state when it can be stopped. 43 * @lock: optional. Define a driver's own lock callback, instead of using 44 * &v4l2_m2m_ctx->q_lock. 45 * @unlock: optional. Define a driver's own unlock callback, instead of 46 * using &v4l2_m2m_ctx->q_lock. 47 */ 48 struct v4l2_m2m_ops { 49 void (*device_run)(void *priv); 50 int (*job_ready)(void *priv); 51 void (*job_abort)(void *priv); 52 void (*lock)(void *priv); 53 void (*unlock)(void *priv); 54 }; 55 56 struct v4l2_m2m_dev; 57 58 /** 59 * struct v4l2_m2m_queue_ctx - represents a queue for buffers ready to be 60 * processed 61 * 62 * @q: pointer to struct &vb2_queue 63 * @rdy_queue: List of V4L2 mem-to-mem queues 64 * @rdy_spinlock: spin lock to protect the struct usage 65 * @num_rdy: number of buffers ready to be processed 66 * @buffered: is the queue buffered? 67 * 68 * Queue for buffers ready to be processed as soon as this 69 * instance receives access to the device. 70 */ 71 72 struct v4l2_m2m_queue_ctx { 73 struct vb2_queue q; 74 75 struct list_head rdy_queue; 76 spinlock_t rdy_spinlock; 77 u8 num_rdy; 78 bool buffered; 79 }; 80 81 /** 82 * struct v4l2_m2m_ctx - Memory to memory context structure 83 * 84 * @q_lock: struct &mutex lock 85 * @m2m_dev: opaque pointer to the internal data to handle M2M context 86 * @cap_q_ctx: Capture (output to memory) queue context 87 * @out_q_ctx: Output (input from memory) queue context 88 * @queue: List of memory to memory contexts 89 * @job_flags: Job queue flags, used internally by v4l2-mem2mem.c: 90 * %TRANS_QUEUED, %TRANS_RUNNING and %TRANS_ABORT. 91 * @finished: Wait queue used to signalize when a job queue finished. 92 * @priv: Instance private data 93 */ 94 struct v4l2_m2m_ctx { 95 /* optional cap/out vb2 queues lock */ 96 struct mutex *q_lock; 97 98 /* internal use only */ 99 struct v4l2_m2m_dev *m2m_dev; 100 101 struct v4l2_m2m_queue_ctx cap_q_ctx; 102 103 struct v4l2_m2m_queue_ctx out_q_ctx; 104 105 /* For device job queue */ 106 struct list_head queue; 107 unsigned long job_flags; 108 wait_queue_head_t finished; 109 110 void *priv; 111 }; 112 113 /** 114 * struct v4l2_m2m_buffer - Memory to memory buffer 115 * 116 * @vb: pointer to struct &vb2_v4l2_buffer 117 * @list: list of m2m buffers 118 */ 119 struct v4l2_m2m_buffer { 120 struct vb2_v4l2_buffer vb; 121 struct list_head list; 122 }; 123 124 /** 125 * v4l2_m2m_get_curr_priv() - return driver private data for the currently 126 * running instance or NULL if no instance is running 127 * 128 * @m2m_dev: opaque pointer to the internal data to handle M2M context 129 */ 130 void *v4l2_m2m_get_curr_priv(struct v4l2_m2m_dev *m2m_dev); 131 132 /** 133 * v4l2_m2m_get_vq() - return vb2_queue for the given type 134 * 135 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 136 * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type 137 */ 138 struct vb2_queue *v4l2_m2m_get_vq(struct v4l2_m2m_ctx *m2m_ctx, 139 enum v4l2_buf_type type); 140 141 /** 142 * v4l2_m2m_try_schedule() - check whether an instance is ready to be added to 143 * the pending job queue and add it if so. 144 * 145 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 146 * 147 * There are three basic requirements an instance has to meet to be able to run: 148 * 1) at least one source buffer has to be queued, 149 * 2) at least one destination buffer has to be queued, 150 * 3) streaming has to be on. 151 * 152 * If a queue is buffered (for example a decoder hardware ringbuffer that has 153 * to be drained before doing streamoff), allow scheduling without v4l2 buffers 154 * on that queue. 155 * 156 * There may also be additional, custom requirements. In such case the driver 157 * should supply a custom callback (job_ready in v4l2_m2m_ops) that should 158 * return 1 if the instance is ready. 159 * An example of the above could be an instance that requires more than one 160 * src/dst buffer per transaction. 161 */ 162 void v4l2_m2m_try_schedule(struct v4l2_m2m_ctx *m2m_ctx); 163 164 /** 165 * v4l2_m2m_job_finish() - inform the framework that a job has been finished 166 * and have it clean up 167 * 168 * @m2m_dev: opaque pointer to the internal data to handle M2M context 169 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 170 * 171 * Called by a driver to yield back the device after it has finished with it. 172 * Should be called as soon as possible after reaching a state which allows 173 * other instances to take control of the device. 174 * 175 * This function has to be called only after &v4l2_m2m_ops->device_run 176 * callback has been called on the driver. To prevent recursion, it should 177 * not be called directly from the &v4l2_m2m_ops->device_run callback though. 178 */ 179 void v4l2_m2m_job_finish(struct v4l2_m2m_dev *m2m_dev, 180 struct v4l2_m2m_ctx *m2m_ctx); 181 182 static inline void 183 v4l2_m2m_buf_done(struct vb2_v4l2_buffer *buf, enum vb2_buffer_state state) 184 { 185 vb2_buffer_done(&buf->vb2_buf, state); 186 } 187 188 /** 189 * v4l2_m2m_reqbufs() - multi-queue-aware REQBUFS multiplexer 190 * 191 * @file: pointer to struct &file 192 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 193 * @reqbufs: pointer to struct &v4l2_requestbuffers 194 */ 195 int v4l2_m2m_reqbufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 196 struct v4l2_requestbuffers *reqbufs); 197 198 /** 199 * v4l2_m2m_querybuf() - multi-queue-aware QUERYBUF multiplexer 200 * 201 * @file: pointer to struct &file 202 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 203 * @buf: pointer to struct &v4l2_buffer 204 * 205 * See v4l2_m2m_mmap() documentation for details. 206 */ 207 int v4l2_m2m_querybuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 208 struct v4l2_buffer *buf); 209 210 /** 211 * v4l2_m2m_qbuf() - enqueue a source or destination buffer, depending on 212 * the type 213 * 214 * @file: pointer to struct &file 215 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 216 * @buf: pointer to struct &v4l2_buffer 217 */ 218 int v4l2_m2m_qbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 219 struct v4l2_buffer *buf); 220 221 /** 222 * v4l2_m2m_dqbuf() - dequeue a source or destination buffer, depending on 223 * the type 224 * 225 * @file: pointer to struct &file 226 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 227 * @buf: pointer to struct &v4l2_buffer 228 */ 229 int v4l2_m2m_dqbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 230 struct v4l2_buffer *buf); 231 232 /** 233 * v4l2_m2m_prepare_buf() - prepare a source or destination buffer, depending on 234 * the type 235 * 236 * @file: pointer to struct &file 237 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 238 * @buf: pointer to struct &v4l2_buffer 239 */ 240 int v4l2_m2m_prepare_buf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 241 struct v4l2_buffer *buf); 242 243 /** 244 * v4l2_m2m_create_bufs() - create a source or destination buffer, depending 245 * on the type 246 * 247 * @file: pointer to struct &file 248 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 249 * @create: pointer to struct &v4l2_create_buffers 250 */ 251 int v4l2_m2m_create_bufs(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 252 struct v4l2_create_buffers *create); 253 254 /** 255 * v4l2_m2m_expbuf() - export a source or destination buffer, depending on 256 * the type 257 * 258 * @file: pointer to struct &file 259 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 260 * @eb: pointer to struct &v4l2_exportbuffer 261 */ 262 int v4l2_m2m_expbuf(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 263 struct v4l2_exportbuffer *eb); 264 265 /** 266 * v4l2_m2m_streamon() - turn on streaming for a video queue 267 * 268 * @file: pointer to struct &file 269 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 270 * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type 271 */ 272 int v4l2_m2m_streamon(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 273 enum v4l2_buf_type type); 274 275 /** 276 * v4l2_m2m_streamoff() - turn off streaming for a video queue 277 * 278 * @file: pointer to struct &file 279 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 280 * @type: type of the V4L2 buffer, as defined by enum &v4l2_buf_type 281 */ 282 int v4l2_m2m_streamoff(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 283 enum v4l2_buf_type type); 284 285 /** 286 * v4l2_m2m_poll() - poll replacement, for destination buffers only 287 * 288 * @file: pointer to struct &file 289 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 290 * @wait: pointer to struct &poll_table_struct 291 * 292 * Call from the driver's poll() function. Will poll both queues. If a buffer 293 * is available to dequeue (with dqbuf) from the source queue, this will 294 * indicate that a non-blocking write can be performed, while read will be 295 * returned in case of the destination queue. 296 */ 297 unsigned int v4l2_m2m_poll(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 298 struct poll_table_struct *wait); 299 300 /** 301 * v4l2_m2m_mmap() - source and destination queues-aware mmap multiplexer 302 * 303 * @file: pointer to struct &file 304 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 305 * @vma: pointer to struct &vm_area_struct 306 * 307 * Call from driver's mmap() function. Will handle mmap() for both queues 308 * seamlessly for videobuffer, which will receive normal per-queue offsets and 309 * proper videobuf queue pointers. The differentiation is made outside videobuf 310 * by adding a predefined offset to buffers from one of the queues and 311 * subtracting it before passing it back to videobuf. Only drivers (and 312 * thus applications) receive modified offsets. 313 */ 314 int v4l2_m2m_mmap(struct file *file, struct v4l2_m2m_ctx *m2m_ctx, 315 struct vm_area_struct *vma); 316 317 /** 318 * v4l2_m2m_init() - initialize per-driver m2m data 319 * 320 * @m2m_ops: pointer to struct v4l2_m2m_ops 321 * 322 * Usually called from driver's ``probe()`` function. 323 * 324 * Return: returns an opaque pointer to the internal data to handle M2M context 325 */ 326 struct v4l2_m2m_dev *v4l2_m2m_init(const struct v4l2_m2m_ops *m2m_ops); 327 328 /** 329 * v4l2_m2m_release() - cleans up and frees a m2m_dev structure 330 * 331 * @m2m_dev: opaque pointer to the internal data to handle M2M context 332 * 333 * Usually called from driver's ``remove()`` function. 334 */ 335 void v4l2_m2m_release(struct v4l2_m2m_dev *m2m_dev); 336 337 /** 338 * v4l2_m2m_ctx_init() - allocate and initialize a m2m context 339 * 340 * @m2m_dev: opaque pointer to the internal data to handle M2M context 341 * @drv_priv: driver's instance private data 342 * @queue_init: a callback for queue type-specific initialization function 343 * to be used for initializing videobuf_queues 344 * 345 * Usually called from driver's ``open()`` function. 346 */ 347 struct v4l2_m2m_ctx *v4l2_m2m_ctx_init(struct v4l2_m2m_dev *m2m_dev, 348 void *drv_priv, 349 int (*queue_init)(void *priv, struct vb2_queue *src_vq, struct vb2_queue *dst_vq)); 350 351 static inline void v4l2_m2m_set_src_buffered(struct v4l2_m2m_ctx *m2m_ctx, 352 bool buffered) 353 { 354 m2m_ctx->out_q_ctx.buffered = buffered; 355 } 356 357 static inline void v4l2_m2m_set_dst_buffered(struct v4l2_m2m_ctx *m2m_ctx, 358 bool buffered) 359 { 360 m2m_ctx->cap_q_ctx.buffered = buffered; 361 } 362 363 /** 364 * v4l2_m2m_ctx_release() - release m2m context 365 * 366 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 367 * 368 * Usually called from driver's release() function. 369 */ 370 void v4l2_m2m_ctx_release(struct v4l2_m2m_ctx *m2m_ctx); 371 372 /** 373 * v4l2_m2m_buf_queue() - add a buffer to the proper ready buffers list. 374 * 375 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 376 * @vbuf: pointer to struct &vb2_v4l2_buffer 377 * 378 * Call from videobuf_queue_ops->ops->buf_queue, videobuf_queue_ops callback. 379 */ 380 void v4l2_m2m_buf_queue(struct v4l2_m2m_ctx *m2m_ctx, 381 struct vb2_v4l2_buffer *vbuf); 382 383 /** 384 * v4l2_m2m_num_src_bufs_ready() - return the number of source buffers ready for 385 * use 386 * 387 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 388 */ 389 static inline 390 unsigned int v4l2_m2m_num_src_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) 391 { 392 return m2m_ctx->out_q_ctx.num_rdy; 393 } 394 395 /** 396 * v4l2_m2m_num_dst_bufs_ready() - return the number of destination buffers 397 * ready for use 398 * 399 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 400 */ 401 static inline 402 unsigned int v4l2_m2m_num_dst_bufs_ready(struct v4l2_m2m_ctx *m2m_ctx) 403 { 404 return m2m_ctx->cap_q_ctx.num_rdy; 405 } 406 407 /** 408 * v4l2_m2m_next_buf() - return next buffer from the list of ready buffers 409 * 410 * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx 411 */ 412 void *v4l2_m2m_next_buf(struct v4l2_m2m_queue_ctx *q_ctx); 413 414 /** 415 * v4l2_m2m_next_src_buf() - return next source buffer from the list of ready 416 * buffers 417 * 418 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 419 */ 420 static inline void *v4l2_m2m_next_src_buf(struct v4l2_m2m_ctx *m2m_ctx) 421 { 422 return v4l2_m2m_next_buf(&m2m_ctx->out_q_ctx); 423 } 424 425 /** 426 * v4l2_m2m_next_dst_buf() - return next destination buffer from the list of 427 * ready buffers 428 * 429 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 430 */ 431 static inline void *v4l2_m2m_next_dst_buf(struct v4l2_m2m_ctx *m2m_ctx) 432 { 433 return v4l2_m2m_next_buf(&m2m_ctx->cap_q_ctx); 434 } 435 436 /** 437 * v4l2_m2m_get_src_vq() - return vb2_queue for source buffers 438 * 439 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 440 */ 441 static inline 442 struct vb2_queue *v4l2_m2m_get_src_vq(struct v4l2_m2m_ctx *m2m_ctx) 443 { 444 return &m2m_ctx->out_q_ctx.q; 445 } 446 447 /** 448 * v4l2_m2m_get_dst_vq() - return vb2_queue for destination buffers 449 * 450 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 451 */ 452 static inline 453 struct vb2_queue *v4l2_m2m_get_dst_vq(struct v4l2_m2m_ctx *m2m_ctx) 454 { 455 return &m2m_ctx->cap_q_ctx.q; 456 } 457 458 /** 459 * v4l2_m2m_buf_remove() - take off a buffer from the list of ready buffers and 460 * return it 461 * 462 * @q_ctx: pointer to struct @v4l2_m2m_queue_ctx 463 */ 464 void *v4l2_m2m_buf_remove(struct v4l2_m2m_queue_ctx *q_ctx); 465 466 /** 467 * v4l2_m2m_src_buf_remove() - take off a source buffer from the list of ready 468 * buffers and return it 469 * 470 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 471 */ 472 static inline void *v4l2_m2m_src_buf_remove(struct v4l2_m2m_ctx *m2m_ctx) 473 { 474 return v4l2_m2m_buf_remove(&m2m_ctx->out_q_ctx); 475 } 476 477 /** 478 * v4l2_m2m_dst_buf_remove() - take off a destination buffer from the list of 479 * ready buffers and return it 480 * 481 * @m2m_ctx: m2m context assigned to the instance given by struct &v4l2_m2m_ctx 482 */ 483 static inline void *v4l2_m2m_dst_buf_remove(struct v4l2_m2m_ctx *m2m_ctx) 484 { 485 return v4l2_m2m_buf_remove(&m2m_ctx->cap_q_ctx); 486 } 487 488 /* v4l2 ioctl helpers */ 489 490 int v4l2_m2m_ioctl_reqbufs(struct file *file, void *priv, 491 struct v4l2_requestbuffers *rb); 492 int v4l2_m2m_ioctl_create_bufs(struct file *file, void *fh, 493 struct v4l2_create_buffers *create); 494 int v4l2_m2m_ioctl_querybuf(struct file *file, void *fh, 495 struct v4l2_buffer *buf); 496 int v4l2_m2m_ioctl_expbuf(struct file *file, void *fh, 497 struct v4l2_exportbuffer *eb); 498 int v4l2_m2m_ioctl_qbuf(struct file *file, void *fh, 499 struct v4l2_buffer *buf); 500 int v4l2_m2m_ioctl_dqbuf(struct file *file, void *fh, 501 struct v4l2_buffer *buf); 502 int v4l2_m2m_ioctl_prepare_buf(struct file *file, void *fh, 503 struct v4l2_buffer *buf); 504 int v4l2_m2m_ioctl_streamon(struct file *file, void *fh, 505 enum v4l2_buf_type type); 506 int v4l2_m2m_ioctl_streamoff(struct file *file, void *fh, 507 enum v4l2_buf_type type); 508 int v4l2_m2m_fop_mmap(struct file *file, struct vm_area_struct *vma); 509 unsigned int v4l2_m2m_fop_poll(struct file *file, poll_table *wait); 510 511 #endif /* _MEDIA_V4L2_MEM2MEM_H */ 512 513