include/media/videobuf2-core.h

   1 /*
   2  * videobuf2-core.h - Video Buffer 2 Core 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_CORE_H
  13 #define _MEDIA_VIDEOBUF2_CORE_H
  14
  15 #include <linux/mm_types.h>
  16 #include <linux/mutex.h>
  17 #include <linux/poll.h>
  18 #include <linux/dma-buf.h>
  19
  20 #define VB2_MAX_FRAME   (32)
  21 #define VB2_MAX_PLANES  (8)
  22
  23 enum vb2_memory {
  24         VB2_MEMORY_UNKNOWN      = 0,
  25         VB2_MEMORY_MMAP         = 1,
  26         VB2_MEMORY_USERPTR      = 2,
  27         VB2_MEMORY_DMABUF       = 4,
  28 };
  29
  30 struct vb2_fileio_data;
  31 struct vb2_threadio_data;
  32
  33 /**
  34  * struct vb2_mem_ops - memory handling/memory allocator operations
  35  * @alloc:      allocate video memory and, optionally, allocator private data,
  36  *              return NULL on failure or a pointer to allocator private,
  37  *              per-buffer data on success; the returned private structure
  38  *              will then be passed as buf_priv argument to other ops in this
  39  *              structure. Additional gfp_flags to use when allocating the
  40  *              are also passed to this operation. These flags are from the
  41  *              gfp_flags field of vb2_queue.
  42  * @put:        inform the allocator that the buffer will no longer be used;
  43  *              usually will result in the allocator freeing the buffer (if
  44  *              no other users of this buffer are present); the buf_priv
  45  *              argument is the allocator private per-buffer structure
  46  *              previously returned from the alloc callback.
  47  * @get_dmabuf: acquire userspace memory for a hardware operation; used for
  48  *               DMABUF memory types.
  49  * @get_userptr: acquire userspace memory for a hardware operation; used for
  50  *               USERPTR memory types; vaddr is the address passed to the
  51  *               videobuf layer when queuing a video buffer of USERPTR type;
  52  *               should return an allocator private per-buffer structure
  53  *               associated with the buffer on success, NULL on failure;
  54  *               the returned private structure will then be passed as buf_priv
  55  *               argument to other ops in this structure.
  56  * @put_userptr: inform the allocator that a USERPTR buffer will no longer
  57  *               be used.
  58  * @attach_dmabuf: attach a shared struct dma_buf for a hardware operation;
  59  *                 used for DMABUF memory types; dev is the alloc device
  60  *                 dbuf is the shared dma_buf; returns NULL on failure;
  61  *                 allocator private per-buffer structure on success;
  62  *                 this needs to be used for further accesses to the buffer.
  63  * @detach_dmabuf: inform the exporter of the buffer that the current DMABUF
  64  *                 buffer is no longer used; the buf_priv argument is the
  65  *                 allocator private per-buffer structure previously returned
  66  *                 from the attach_dmabuf callback.
  67  * @map_dmabuf: request for access to the dmabuf from allocator; the allocator
  68  *              of dmabuf is informed that this driver is going to use the
  69  *              dmabuf.
  70  * @unmap_dmabuf: releases access control to the dmabuf - allocator is notified
  71  *                that this driver is done using the dmabuf for now.
  72  * @prepare:    called every time the buffer is passed from userspace to the
  73  *              driver, useful for cache synchronisation, optional.
  74  * @finish:     called every time the buffer is passed back from the driver
  75  *              to the userspace, also optional.
  76  * @vaddr:      return a kernel virtual address to a given memory buffer
  77  *              associated with the passed private structure or NULL if no
  78  *              such mapping exists.
  79  * @cookie:     return allocator specific cookie for a given memory buffer
  80  *              associated with the passed private structure or NULL if not
  81  *              available.
  82  * @num_users:  return the current number of users of a memory buffer;
  83  *              return 1 if the videobuf layer (or actually the driver using
  84  *              it) is the only user.
  85  * @mmap:       setup a userspace mapping for a given memory buffer under
  86  *              the provided virtual memory region.
  87  *
  88  * Those operations are used by the videobuf2 core to implement the memory
  89  * handling/memory allocators for each type of supported streaming I/O method.
  90  *
  91  * .. note::
  92  *    #) Required ops for USERPTR types: get_userptr, put_userptr.
  93  *
  94  *    #) Required ops for MMAP types: alloc, put, num_users, mmap.
  95  *
  96  *    #) Required ops for read/write access types: alloc, put, num_users, vaddr.
  97  *
  98  *    #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
  99  */
 100 struct vb2_mem_ops {
 101         void            *(*alloc)(struct device *dev, unsigned long attrs,
 102                                   unsigned long size, enum dma_data_direction dma_dir,
 103                                   gfp_t gfp_flags);
 104         void            (*put)(void *buf_priv);
 105         struct dma_buf *(*get_dmabuf)(void *buf_priv, unsigned long flags);
 106
 107         void            *(*get_userptr)(struct device *dev, unsigned long vaddr,
 108                                         unsigned long size,
 109                                         enum dma_data_direction dma_dir);
 110         void            (*put_userptr)(void *buf_priv);
 111
 112         void            (*prepare)(void *buf_priv);
 113         void            (*finish)(void *buf_priv);
 114
 115         void            *(*attach_dmabuf)(struct device *dev, struct dma_buf *dbuf,
 116                                           unsigned long size,
 117                                           enum dma_data_direction dma_dir);
 118         void            (*detach_dmabuf)(void *buf_priv);
 119         int             (*map_dmabuf)(void *buf_priv);
 120         void            (*unmap_dmabuf)(void *buf_priv);
 121
 122         void            *(*vaddr)(void *buf_priv);
 123         void            *(*cookie)(void *buf_priv);
 124
 125         unsigned int    (*num_users)(void *buf_priv);
 126
 127         int             (*mmap)(void *buf_priv, struct vm_area_struct *vma);
 128 };
 129
 130 /**
 131  * struct vb2_plane - plane information
 132  * @mem_priv:   private data with this plane
 133  * @dbuf:       dma_buf - shared buffer object
 134  * @dbuf_mapped:        flag to show whether dbuf is mapped or not
 135  * @bytesused:  number of bytes occupied by data in the plane (payload)
 136  * @length:     size of this plane (NOT the payload) in bytes
 137  * @min_length: minimum required size of this plane (NOT the payload) in bytes.
 138  *              @length is always greater or equal to @min_length.
 139  * @offset:     when memory in the associated struct vb2_buffer is
 140  *              VB2_MEMORY_MMAP, equals the offset from the start of
 141  *              the device memory for this plane (or is a "cookie" that
 142  *              should be passed to mmap() called on the video node)
 143  * @userptr:    when memory is VB2_MEMORY_USERPTR, a userspace pointer
 144  *              pointing to this plane
 145  * @fd:         when memory is VB2_MEMORY_DMABUF, a userspace file
 146  *              descriptor associated with this plane
 147  * @m:          Union with memtype-specific data (@offset, @userptr or
 148  *              @fd).
 149  * @data_offset:        offset in the plane to the start of data; usually 0,
 150  *              unless there is a header in front of the data
 151  * Should contain enough information to be able to cover all the fields
 152  * of struct v4l2_plane at videodev2.h
 153  */
 154 struct vb2_plane {
 155         void                    *mem_priv;
 156         struct dma_buf          *dbuf;
 157         unsigned int            dbuf_mapped;
 158         unsigned int            bytesused;
 159         unsigned int            length;
 160         unsigned int            min_length;
 161         union {
 162                 unsigned int    offset;
 163                 unsigned long   userptr;
 164                 int             fd;
 165         } m;
 166         unsigned int            data_offset;
 167 };
 168
 169 /**
 170  * enum vb2_io_modes - queue access methods
 171  * @VB2_MMAP:           driver supports MMAP with streaming API
 172  * @VB2_USERPTR:        driver supports USERPTR with streaming API
 173  * @VB2_READ:           driver supports read() style access
 174  * @VB2_WRITE:          driver supports write() style access
 175  * @VB2_DMABUF:         driver supports DMABUF with streaming API
 176  */
 177 enum vb2_io_modes {
 178         VB2_MMAP        = (1 << 0),
 179         VB2_USERPTR     = (1 << 1),
 180         VB2_READ        = (1 << 2),
 181         VB2_WRITE       = (1 << 3),
 182         VB2_DMABUF      = (1 << 4),
 183 };
 184
 185 /**
 186  * enum vb2_buffer_state - current video buffer state
 187  * @VB2_BUF_STATE_DEQUEUED:     buffer under userspace control
 188  * @VB2_BUF_STATE_PREPARING:    buffer is being prepared in videobuf
 189  * @VB2_BUF_STATE_PREPARED:     buffer prepared in videobuf and by the driver
 190  * @VB2_BUF_STATE_QUEUED:       buffer queued in videobuf, but not in driver
 191  * @VB2_BUF_STATE_REQUEUEING:   re-queue a buffer to the driver
 192  * @VB2_BUF_STATE_ACTIVE:       buffer queued in driver and possibly used
 193  *                              in a hardware operation
 194  * @VB2_BUF_STATE_DONE:         buffer returned from driver to videobuf, but
 195  *                              not yet dequeued to userspace
 196  * @VB2_BUF_STATE_ERROR:        same as above, but the operation on the buffer
 197  *                              has ended with an error, which will be reported
 198  *                              to the userspace when it is dequeued
 199  */
 200 enum vb2_buffer_state {
 201         VB2_BUF_STATE_DEQUEUED,
 202         VB2_BUF_STATE_PREPARING,
 203         VB2_BUF_STATE_PREPARED,
 204         VB2_BUF_STATE_QUEUED,
 205         VB2_BUF_STATE_REQUEUEING,
 206         VB2_BUF_STATE_ACTIVE,
 207         VB2_BUF_STATE_DONE,
 208         VB2_BUF_STATE_ERROR,
 209 };
 210
 211 struct vb2_queue;
 212
 213 /**
 214  * struct vb2_buffer - represents a video buffer
 215  * @vb2_queue:          the queue to which this driver belongs
 216  * @index:              id number of the buffer
 217  * @type:               buffer type
 218  * @memory:             the method, in which the actual data is passed
 219  * @num_planes:         number of planes in the buffer
 220  *                      on an internal driver queue
 221  * @planes:             private per-plane information; do not change
 222  * @timestamp:          frame timestamp in ns
 223  */
 224 struct vb2_buffer {
 225         struct vb2_queue        *vb2_queue;
 226         unsigned int            index;
 227         unsigned int            type;
 228         unsigned int            memory;
 229         unsigned int            num_planes;
 230         struct vb2_plane        planes[VB2_MAX_PLANES];
 231         u64                     timestamp;
 232
 233         /* private: internal use only
 234          *
 235          * state:               current buffer state; do not change
 236          * queued_entry:        entry on the queued buffers list, which holds
 237          *                      all buffers queued from userspace
 238          * done_entry:          entry on the list that stores all buffers ready
 239          *                      to be dequeued to userspace
 240          */
 241         enum vb2_buffer_state   state;
 242
 243         struct list_head        queued_entry;
 244         struct list_head        done_entry;
 245 #ifdef CONFIG_VIDEO_ADV_DEBUG
 246         /*
 247          * Counters for how often these buffer-related ops are
 248          * called. Used to check for unbalanced ops.
 249          */
 250         u32             cnt_mem_alloc;
 251         u32             cnt_mem_put;
 252         u32             cnt_mem_get_dmabuf;
 253         u32             cnt_mem_get_userptr;
 254         u32             cnt_mem_put_userptr;
 255         u32             cnt_mem_prepare;
 256         u32             cnt_mem_finish;
 257         u32             cnt_mem_attach_dmabuf;
 258         u32             cnt_mem_detach_dmabuf;
 259         u32             cnt_mem_map_dmabuf;
 260         u32             cnt_mem_unmap_dmabuf;
 261         u32             cnt_mem_vaddr;
 262         u32             cnt_mem_cookie;
 263         u32             cnt_mem_num_users;
 264         u32             cnt_mem_mmap;
 265
 266         u32             cnt_buf_init;
 267         u32             cnt_buf_prepare;
 268         u32             cnt_buf_finish;
 269         u32             cnt_buf_cleanup;
 270         u32             cnt_buf_queue;
 271
 272         /* This counts the number of calls to vb2_buffer_done() */
 273         u32             cnt_buf_done;
 274 #endif
 275 };
 276
 277 /**
 278  * struct vb2_ops - driver-specific callbacks
 279  *
 280  * @queue_setup:        called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS
 281  *                      handlers before memory allocation. It can be called
 282  *                      twice: if the original number of requested buffers
 283  *                      could not be allocated, then it will be called a
 284  *                      second time with the actually allocated number of
 285  *                      buffers to verify if that is OK.
 286  *                      The driver should return the required number of buffers
 287  *                      in \*num_buffers, the required number of planes per
 288  *                      buffer in \*num_planes, the size of each plane should be
 289  *                      set in the sizes\[\] array and optional per-plane
 290  *                      allocator specific device in the alloc_devs\[\] array.
 291  *                      When called from %VIDIOC_REQBUFS, \*num_planes == 0, the
 292  *                      driver has to use the currently configured format to
 293  *                      determine the plane sizes and \*num_buffers is the total
 294  *                      number of buffers that are being allocated. When called
 295  *                      from %VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
 296  *                      describes the requested number of planes and sizes\[\]
 297  *                      contains the requested plane sizes. If either
 298  *                      \*num_planes or the requested sizes are invalid callback
 299  *                      must return %-EINVAL. In this case \*num_buffers are
 300  *                      being allocated additionally to q->num_buffers.
 301  * @wait_prepare:       release any locks taken while calling vb2 functions;
 302  *                      it is called before an ioctl needs to wait for a new
 303  *                      buffer to arrive; required to avoid a deadlock in
 304  *                      blocking access type.
 305  * @wait_finish:        reacquire all locks released in the previous callback;
 306  *                      required to continue operation after sleeping while
 307  *                      waiting for a new buffer to arrive.
 308  * @buf_init:           called once after allocating a buffer (in MMAP case)
 309  *                      or after acquiring a new USERPTR buffer; drivers may
 310  *                      perform additional buffer-related initialization;
 311  *                      initialization failure (return != 0) will prevent
 312  *                      queue setup from completing successfully; optional.
 313  * @buf_prepare:        called every time the buffer is queued from userspace
 314  *                      and from the %VIDIOC_PREPARE_BUF ioctl; drivers may
 315  *                      perform any initialization required before each
 316  *                      hardware operation in this callback; drivers can
 317  *                      access/modify the buffer here as it is still synced for
 318  *                      the CPU; drivers that support %VIDIOC_CREATE_BUFS must
 319  *                      also validate the buffer size; if an error is returned,
 320  *                      the buffer will not be queued in driver; optional.
 321  * @buf_finish:         called before every dequeue of the buffer back to
 322  *                      userspace; the buffer is synced for the CPU, so drivers
 323  *                      can access/modify the buffer contents; drivers may
 324  *                      perform any operations required before userspace
 325  *                      accesses the buffer; optional. The buffer state can be
 326  *                      one of the following: %DONE and %ERROR occur while
 327  *                      streaming is in progress, and the %PREPARED state occurs
 328  *                      when the queue has been canceled and all pending
 329  *                      buffers are being returned to their default %DEQUEUED
 330  *                      state. Typically you only have to do something if the
 331  *                      state is %VB2_BUF_STATE_DONE, since in all other cases
 332  *                      the buffer contents will be ignored anyway.
 333  * @buf_cleanup:        called once before the buffer is freed; drivers may
 334  *                      perform any additional cleanup; optional.
 335  * @start_streaming:    called once to enter 'streaming' state; the driver may
 336  *                      receive buffers with @buf_queue callback
 337  *                      before @start_streaming is called; the driver gets the
 338  *                      number of already queued buffers in count parameter;
 339  *                      driver can return an error if hardware fails, in that
 340  *                      case all buffers that have been already given by
 341  *                      the @buf_queue callback are to be returned by the driver
 342  *                      by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\).
 343  *                      If you need a minimum number of buffers before you can
 344  *                      start streaming, then set @min_buffers_needed in the
 345  *                      vb2_queue structure. If that is non-zero then
 346  *                      start_streaming won't be called until at least that
 347  *                      many buffers have been queued up by userspace.
 348  * @stop_streaming:     called when 'streaming' state must be disabled; driver
 349  *                      should stop any DMA transactions or wait until they
 350  *                      finish and give back all buffers it got from &buf_queue
 351  *                      callback by calling @vb2_buffer_done\(\) with either
 352  *                      %VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
 353  *                      vb2_wait_for_all_buffers() function
 354  * @buf_queue:          passes buffer vb to the driver; driver may start
 355  *                      hardware operation on this buffer; driver should give
 356  *                      the buffer back by calling vb2_buffer_done() function;
 357  *                      it is allways called after calling %VIDIOC_STREAMON ioctl;
 358  *                      might be called before start_streaming callback if user
 359  *                      pre-queued buffers before calling %VIDIOC_STREAMON.
 360  */
 361 struct vb2_ops {
 362         int (*queue_setup)(struct vb2_queue *q,
 363                            unsigned int *num_buffers, unsigned int *num_planes,
 364                            unsigned int sizes[], struct device *alloc_devs[]);
 365
 366         void (*wait_prepare)(struct vb2_queue *q);
 367         void (*wait_finish)(struct vb2_queue *q);
 368
 369         int (*buf_init)(struct vb2_buffer *vb);
 370         int (*buf_prepare)(struct vb2_buffer *vb);
 371         void (*buf_finish)(struct vb2_buffer *vb);
 372         void (*buf_cleanup)(struct vb2_buffer *vb);
 373
 374         int (*start_streaming)(struct vb2_queue *q, unsigned int count);
 375         void (*stop_streaming)(struct vb2_queue *q);
 376
 377         void (*buf_queue)(struct vb2_buffer *vb);
 378 };
 379
 380 /**
 381  * struct vb2_ops - driver-specific callbacks
 382  *
 383  * @verify_planes_array: Verify that a given user space structure contains
 384  *                      enough planes for the buffer. This is called
 385  *                      for each dequeued buffer.
 386  * @fill_user_buffer:   given a vb2_buffer fill in the userspace structure.
 387  *                      For V4L2 this is a struct v4l2_buffer.
 388  * @fill_vb2_buffer:    given a userspace structure, fill in the vb2_buffer.
 389  *                      If the userspace structure is invalid, then this op
 390  *                      will return an error.
 391  * @copy_timestamp:     copy the timestamp from a userspace structure to
 392  *                      the vb2_buffer struct.
 393  */
 394 struct vb2_buf_ops {
 395         int (*verify_planes_array)(struct vb2_buffer *vb, const void *pb);
 396         void (*fill_user_buffer)(struct vb2_buffer *vb, void *pb);
 397         int (*fill_vb2_buffer)(struct vb2_buffer *vb, const void *pb,
 398                                 struct vb2_plane *planes);
 399         void (*copy_timestamp)(struct vb2_buffer *vb, const void *pb);
 400 };
 401
 402 /**
 403  * struct vb2_queue - a videobuf queue
 404  *
 405  * @type:       private buffer type whose content is defined by the vb2-core
 406  *              caller. For example, for V4L2, it should match
 407  *              the V4L2_BUF_TYPE_* in include/uapi/linux/videodev2.h
 408  * @io_modes:   supported io methods (see vb2_io_modes enum)
 409  * @dev:        device to use for the default allocation context if the driver
 410  *              doesn't fill in the @alloc_devs array.
 411  * @dma_attrs:  DMA attributes to use for the DMA.
 412  * @fileio_read_once:           report EOF after reading the first buffer
 413  * @fileio_write_immediately:   queue buffer after each write() call
 414  * @allow_zero_bytesused:       allow bytesused == 0 to be passed to the driver
 415  * @quirk_poll_must_check_waiting_for_buffers: Return POLLERR at poll when QBUF
 416  *              has not been called. This is a vb1 idiom that has been adopted
 417  *              also by vb2.
 418  * @lock:       pointer to a mutex that protects the vb2_queue struct. The
 419  *              driver can set this to a mutex to let the v4l2 core serialize
 420  *              the queuing ioctls. If the driver wants to handle locking
 421  *              itself, then this should be set to NULL. This lock is not used
 422  *              by the videobuf2 core API.
 423  * @owner:      The filehandle that 'owns' the buffers, i.e. the filehandle
 424  *              that called reqbufs, create_buffers or started fileio.
 425  *              This field is not used by the videobuf2 core API, but it allows
 426  *              drivers to easily associate an owner filehandle with the queue.
 427  * @ops:        driver-specific callbacks
 428  * @mem_ops:    memory allocator specific callbacks
 429  * @buf_ops:    callbacks to deliver buffer information
 430  *              between user-space and kernel-space
 431  * @drv_priv:   driver private data
 432  * @buf_struct_size: size of the driver-specific buffer structure;
 433  *              "0" indicates the driver doesn't want to use a custom buffer
 434  *              structure type. for example, sizeof(struct vb2_v4l2_buffer)
 435  *              will be used for v4l2.
 436  * @timestamp_flags: Timestamp flags; V4L2_BUF_FLAG_TIMESTAMP_* and
 437  *              V4L2_BUF_FLAG_TSTAMP_SRC_*
 438  * @gfp_flags:  additional gfp flags used when allocating the buffers.
 439  *              Typically this is 0, but it may be e.g. GFP_DMA or __GFP_DMA32
 440  *              to force the buffer allocation to a specific memory zone.
 441  * @min_buffers_needed: the minimum number of buffers needed before
 442  *              start_streaming() can be called. Used when a DMA engine
 443  *              cannot be started unless at least this number of buffers
 444  *              have been queued into the driver.
 445  */
 446 /*
 447  * Private elements (won't appear at the DocBook):
 448  * @mmap_lock:  private mutex used when buffers are allocated/freed/mmapped
 449  * @memory:     current memory type used
 450  * @bufs:       videobuf buffer structures
 451  * @num_buffers: number of allocated/used buffers
 452  * @queued_list: list of buffers currently queued from userspace
 453  * @queued_count: number of buffers queued and ready for streaming.
 454  * @owned_by_drv_count: number of buffers owned by the driver
 455  * @done_list:  list of buffers ready to be dequeued to userspace
 456  * @done_lock:  lock to protect done_list list
 457  * @done_wq:    waitqueue for processes waiting for buffers ready to be dequeued
 458  * @alloc_devs: memory type/allocator-specific per-plane device
 459  * @streaming:  current streaming state
 460  * @start_streaming_called: start_streaming() was called successfully and we
 461  *              started streaming.
 462  * @error:      a fatal error occurred on the queue
 463  * @waiting_for_buffers: used in poll() to check if vb2 is still waiting for
 464  *              buffers. Only set for capture queues if qbuf has not yet been
 465  *              called since poll() needs to return POLLERR in that situation.
 466  * @is_multiplanar: set if buffer type is multiplanar
 467  * @is_output:  set if buffer type is output
 468  * @copy_timestamp: set if vb2-core should set timestamps
 469  * @last_buffer_dequeued: used in poll() and DQBUF to immediately return if the
 470  *              last decoded buffer was already dequeued. Set for capture queues
 471  *              when a buffer with the V4L2_BUF_FLAG_LAST is dequeued.
 472  * @fileio:     file io emulator internal data, used only if emulator is active
 473  * @threadio:   thread io internal data, used only if thread is active
 474  */
 475 struct vb2_queue {
 476         unsigned int                    type;
 477         unsigned int                    io_modes;
 478         struct device                   *dev;
 479         unsigned long                   dma_attrs;
 480         unsigned                        fileio_read_once:1;
 481         unsigned                        fileio_write_immediately:1;
 482         unsigned                        allow_zero_bytesused:1;
 483         unsigned                   quirk_poll_must_check_waiting_for_buffers:1;
 484
 485         struct mutex                    *lock;
 486         void                            *owner;
 487
 488         const struct vb2_ops            *ops;
 489         const struct vb2_mem_ops        *mem_ops;
 490         const struct vb2_buf_ops        *buf_ops;
 491
 492         void                            *drv_priv;
 493         unsigned int                    buf_struct_size;
 494         u32                             timestamp_flags;
 495         gfp_t                           gfp_flags;
 496         u32                             min_buffers_needed;
 497
 498         /* private: internal use only */
 499         struct mutex                    mmap_lock;
 500         unsigned int                    memory;
 501         struct vb2_buffer               *bufs[VB2_MAX_FRAME];
 502         unsigned int                    num_buffers;
 503
 504         struct list_head                queued_list;
 505         unsigned int                    queued_count;
 506
 507         atomic_t                        owned_by_drv_count;
 508         struct list_head                done_list;
 509         spinlock_t                      done_lock;
 510         wait_queue_head_t               done_wq;
 511
 512         struct device                   *alloc_devs[VB2_MAX_PLANES];
 513
 514         unsigned int                    streaming:1;
 515         unsigned int                    start_streaming_called:1;
 516         unsigned int                    error:1;
 517         unsigned int                    waiting_for_buffers:1;
 518         unsigned int                    is_multiplanar:1;
 519         unsigned int                    is_output:1;
 520         unsigned int                    copy_timestamp:1;
 521         unsigned int                    last_buffer_dequeued:1;
 522
 523         struct vb2_fileio_data          *fileio;
 524         struct vb2_threadio_data        *threadio;
 525
 526 #ifdef CONFIG_VIDEO_ADV_DEBUG
 527         /*
 528          * Counters for how often these queue-related ops are
 529          * called. Used to check for unbalanced ops.
 530          */
 531         u32                             cnt_queue_setup;
 532         u32                             cnt_wait_prepare;
 533         u32                             cnt_wait_finish;
 534         u32                             cnt_start_streaming;
 535         u32                             cnt_stop_streaming;
 536 #endif
 537 };
 538
 539 void *vb2_plane_vaddr(struct vb2_buffer *vb, unsigned int plane_no);
 540 void *vb2_plane_cookie(struct vb2_buffer *vb, unsigned int plane_no);
 541
 542 void vb2_buffer_done(struct vb2_buffer *vb, enum vb2_buffer_state state);
 543 void vb2_discard_done(struct vb2_queue *q);
 544 int vb2_wait_for_all_buffers(struct vb2_queue *q);
 545
 546 void vb2_core_querybuf(struct vb2_queue *q, unsigned int index, void *pb);
 547 int vb2_core_reqbufs(struct vb2_queue *q, enum vb2_memory memory,
 548                 unsigned int *count);
 549 int vb2_core_create_bufs(struct vb2_queue *q, enum vb2_memory memory,
 550                 unsigned int *count, unsigned requested_planes,
 551                 const unsigned int requested_sizes[]);
 552 int vb2_core_prepare_buf(struct vb2_queue *q, unsigned int index, void *pb);
 553 int vb2_core_qbuf(struct vb2_queue *q, unsigned int index, void *pb);
 554 int vb2_core_dqbuf(struct vb2_queue *q, unsigned int *pindex, void *pb,
 555                    bool nonblocking);
 556
 557 int vb2_core_streamon(struct vb2_queue *q, unsigned int type);
 558 int vb2_core_streamoff(struct vb2_queue *q, unsigned int type);
 559
 560 int vb2_core_expbuf(struct vb2_queue *q, int *fd, unsigned int type,
 561                 unsigned int index, unsigned int plane, unsigned int flags);
 562
 563 int vb2_core_queue_init(struct vb2_queue *q);
 564 void vb2_core_queue_release(struct vb2_queue *q);
 565
 566 void vb2_queue_error(struct vb2_queue *q);
 567
 568 int vb2_mmap(struct vb2_queue *q, struct vm_area_struct *vma);
 569 #ifndef CONFIG_MMU
 570 unsigned long vb2_get_unmapped_area(struct vb2_queue *q,
 571                                     unsigned long addr,
 572                                     unsigned long len,
 573                                     unsigned long pgoff,
 574                                     unsigned long flags);
 575 #endif
 576 unsigned int vb2_core_poll(struct vb2_queue *q, struct file *file,
 577                 poll_table *wait);
 578 size_t vb2_read(struct vb2_queue *q, char __user *data, size_t count,
 579                 loff_t *ppos, int nonblock);
 580 size_t vb2_write(struct vb2_queue *q, const char __user *data, size_t count,
 581                 loff_t *ppos, int nonblock);
 582
 583 /*
 584  * vb2_thread_fnc - callback function for use with vb2_thread
 585  *
 586  * This is called whenever a buffer is dequeued in the thread.
 587  */
 588 typedef int (*vb2_thread_fnc)(struct vb2_buffer *vb, void *priv);
 589
 590 /**
 591  * vb2_thread_start() - start a thread for the given queue.
 592  * @q:          videobuf queue
 593  * @fnc:        callback function
 594  * @priv:       priv pointer passed to the callback function
 595  * @thread_name:the name of the thread. This will be prefixed with "vb2-".
 596  *
 597  * This starts a thread that will queue and dequeue until an error occurs
 598  * or @vb2_thread_stop is called.
 599  *
 600  * This function should not be used for anything else but the videobuf2-dvb
 601  * support. If you think you have another good use-case for this, then please
 602  * contact the linux-media mailinglist first.
 603  */
 604 int vb2_thread_start(struct vb2_queue *q, vb2_thread_fnc fnc, void *priv,
 605                      const char *thread_name);
 606
 607 /**
 608  * vb2_thread_stop() - stop the thread for the given queue.
 609  * @q:          videobuf queue
 610  */
 611 int vb2_thread_stop(struct vb2_queue *q);
 612
 613 /**
 614  * vb2_is_streaming() - return streaming status of the queue
 615  * @q:          videobuf queue
 616  */
 617 static inline bool vb2_is_streaming(struct vb2_queue *q)
 618 {
 619         return q->streaming;
 620 }
 621
 622 /**
 623  * vb2_fileio_is_active() - return true if fileio is active.
 624  * @q:          videobuf queue
 625  *
 626  * This returns true if read() or write() is used to stream the data
 627  * as opposed to stream I/O. This is almost never an important distinction,
 628  * except in rare cases. One such case is that using read() or write() to
 629  * stream a format using V4L2_FIELD_ALTERNATE is not allowed since there
 630  * is no way you can pass the field information of each buffer to/from
 631  * userspace. A driver that supports this field format should check for
 632  * this in the queue_setup op and reject it if this function returns true.
 633  */
 634 static inline bool vb2_fileio_is_active(struct vb2_queue *q)
 635 {
 636         return q->fileio;
 637 }
 638
 639 /**
 640  * vb2_is_busy() - return busy status of the queue
 641  * @q:          videobuf queue
 642  *
 643  * This function checks if queue has any buffers allocated.
 644  */
 645 static inline bool vb2_is_busy(struct vb2_queue *q)
 646 {
 647         return (q->num_buffers > 0);
 648 }
 649
 650 /**
 651  * vb2_get_drv_priv() - return driver private data associated with the queue
 652  * @q:          videobuf queue
 653  */
 654 static inline void *vb2_get_drv_priv(struct vb2_queue *q)
 655 {
 656         return q->drv_priv;
 657 }
 658
 659 /**
 660  * vb2_set_plane_payload() - set bytesused for the plane plane_no
 661  * @vb:         buffer for which plane payload should be set
 662  * @plane_no:   plane number for which payload should be set
 663  * @size:       payload in bytes
 664  */
 665 static inline void vb2_set_plane_payload(struct vb2_buffer *vb,
 666                                  unsigned int plane_no, unsigned long size)
 667 {
 668         if (plane_no < vb->num_planes)
 669                 vb->planes[plane_no].bytesused = size;
 670 }
 671
 672 /**
 673  * vb2_get_plane_payload() - get bytesused for the plane plane_no
 674  * @vb:         buffer for which plane payload should be set
 675  * @plane_no:   plane number for which payload should be set
 676  */
 677 static inline unsigned long vb2_get_plane_payload(struct vb2_buffer *vb,
 678                                  unsigned int plane_no)
 679 {
 680         if (plane_no < vb->num_planes)
 681                 return vb->planes[plane_no].bytesused;
 682         return 0;
 683 }
 684
 685 /**
 686  * vb2_plane_size() - return plane size in bytes
 687  * @vb:         buffer for which plane size should be returned
 688  * @plane_no:   plane number for which size should be returned
 689  */
 690 static inline unsigned long
 691 vb2_plane_size(struct vb2_buffer *vb, unsigned int plane_no)
 692 {
 693         if (plane_no < vb->num_planes)
 694                 return vb->planes[plane_no].length;
 695         return 0;
 696 }
 697
 698 /**
 699  * vb2_start_streaming_called() - return streaming status of driver
 700  * @q:          videobuf queue
 701  */
 702 static inline bool vb2_start_streaming_called(struct vb2_queue *q)
 703 {
 704         return q->start_streaming_called;
 705 }
 706
 707 /**
 708  * vb2_clear_last_buffer_dequeued() - clear last buffer dequeued flag of queue
 709  * @q:          videobuf queue
 710  */
 711 static inline void vb2_clear_last_buffer_dequeued(struct vb2_queue *q)
 712 {
 713         q->last_buffer_dequeued = false;
 714 }
 715
 716 /*
 717  * The following functions are not part of the vb2 core API, but are useful
 718  * functions for videobuf2-*.
 719  */
 720 bool vb2_buffer_in_use(struct vb2_queue *q, struct vb2_buffer *vb);
 721 int vb2_verify_memory_type(struct vb2_queue *q,
 722                 enum vb2_memory memory, unsigned int type);
 723 #endif /* _MEDIA_VIDEOBUF2_CORE_H */