include/media/v4l2-mem2mem.h

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