drivers/media/video/uvc/uvc_queue.c

   1 /*
   2  *      uvc_queue.c  --  USB Video Class driver - Buffers management
   3  *
   4  *      Copyright (C) 2005-2008
   5  *          Laurent Pinchart (laurent.pinchart@skynet.be)
   6  *
   7  *      This program is free software; you can redistribute it and/or modify
   8  *      it under the terms of the GNU General Public License as published by
   9  *      the Free Software Foundation; either version 2 of the License, or
  10  *      (at your option) any later version.
  11  *
  12  */
  13
  14 #include <linux/kernel.h>
  15 #include <linux/version.h>
  16 #include <linux/mm.h>
  17 #include <linux/list.h>
  18 #include <linux/module.h>
  19 #include <linux/usb.h>
  20 #include <linux/videodev2.h>
  21 #include <linux/vmalloc.h>
  22 #include <linux/wait.h>
  23 #include <asm/atomic.h>
  24
  25 #include "uvcvideo.h"
  26
  27 /* ------------------------------------------------------------------------
  28  * Video buffers queue management.
  29  *
  30  * Video queues is initialized by uvc_queue_init(). The function performs
  31  * basic initialization of the uvc_video_queue struct and never fails.
  32  *
  33  * Video buffer allocation and freeing are performed by uvc_alloc_buffers and
  34  * uvc_free_buffers respectively. The former acquires the video queue lock,
  35  * while the later must be called with the lock held (so that allocation can
  36  * free previously allocated buffers). Trying to free buffers that are mapped
  37  * to user space will return -EBUSY.
  38  *
  39  * Video buffers are managed using two queues. However, unlike most USB video
  40  * drivers which use an in queue and an out queue, we use a main queue which
  41  * holds all queued buffers (both 'empty' and 'done' buffers), and an irq
  42  * queue which holds empty buffers. This design (copied from video-buf)
  43  * minimizes locking in interrupt, as only one queue is shared between
  44  * interrupt and user contexts.
  45  *
  46  * Use cases
  47  * ---------
  48  *
  49  * Unless stated otherwise, all operations which modify the irq buffers queue
  50  * are protected by the irq spinlock.
  51  *
  52  * 1. The user queues the buffers, starts streaming and dequeues a buffer.
  53  *
  54  *    The buffers are added to the main and irq queues. Both operations are
  55  *    protected by the queue lock, and the latert is protected by the irq
  56  *    spinlock as well.
  57  *
  58  *    The completion handler fetches a buffer from the irq queue and fills it
  59  *    with video data. If no buffer is available (irq queue empty), the handler
  60  *    returns immediately.
  61  *
  62  *    When the buffer is full, the completion handler removes it from the irq
  63  *    queue, marks it as ready (UVC_BUF_STATE_DONE) and wake its wait queue.
  64  *    At that point, any process waiting on the buffer will be woken up. If a
  65  *    process tries to dequeue a buffer after it has been marked ready, the
  66  *    dequeing will succeed immediately.
  67  *
  68  * 2. Buffers are queued, user is waiting on a buffer and the device gets
  69  *    disconnected.
  70  *
  71  *    When the device is disconnected, the kernel calls the completion handler
  72  *    with an appropriate status code. The handler marks all buffers in the
  73  *    irq queue as being erroneous (UVC_BUF_STATE_ERROR) and wakes them up so
  74  *    that any process waiting on a buffer gets woken up.
  75  *
  76  *    Waking up up the first buffer on the irq list is not enough, as the
  77  *    process waiting on the buffer might restart the dequeue operation
  78  *    immediately.
  79  *
  80  */
  81
  82 void uvc_queue_init(struct uvc_video_queue *queue, enum v4l2_buf_type type)
  83 {
  84         mutex_init(&queue->mutex);
  85         spin_lock_init(&queue->irqlock);
  86         INIT_LIST_HEAD(&queue->mainqueue);
  87         INIT_LIST_HEAD(&queue->irqqueue);
  88         queue->type = type;
  89 }
  90
  91 /*
  92  * Allocate the video buffers.
  93  *
  94  * Pages are reserved to make sure they will not be swaped, as they will be
  95  * filled in URB completion handler.
  96  *
  97  * Buffers will be individually mapped, so they must all be page aligned.
  98  */
  99 int uvc_alloc_buffers(struct uvc_video_queue *queue, unsigned int nbuffers,
 100                 unsigned int buflength)
 101 {
 102         unsigned int bufsize = PAGE_ALIGN(buflength);
 103         unsigned int i;
 104         void *mem = NULL;
 105         int ret;
 106
 107         if (nbuffers > UVC_MAX_VIDEO_BUFFERS)
 108                 nbuffers = UVC_MAX_VIDEO_BUFFERS;
 109
 110         mutex_lock(&queue->mutex);
 111
 112         if ((ret = uvc_free_buffers(queue)) < 0)
 113                 goto done;
 114
 115         /* Bail out if no buffers should be allocated. */
 116         if (nbuffers == 0)
 117                 goto done;
 118
 119         /* Decrement the number of buffers until allocation succeeds. */
 120         for (; nbuffers > 0; --nbuffers) {
 121                 mem = vmalloc_32(nbuffers * bufsize);
 122                 if (mem != NULL)
 123                         break;
 124         }
 125
 126         if (mem == NULL) {
 127                 ret = -ENOMEM;
 128                 goto done;
 129         }
 130
 131         for (i = 0; i < nbuffers; ++i) {
 132                 memset(&queue->buffer[i], 0, sizeof queue->buffer[i]);
 133                 queue->buffer[i].buf.index = i;
 134                 queue->buffer[i].buf.m.offset = i * bufsize;
 135                 queue->buffer[i].buf.length = buflength;
 136                 queue->buffer[i].buf.type = queue->type;
 137                 queue->buffer[i].buf.sequence = 0;
 138                 queue->buffer[i].buf.field = V4L2_FIELD_NONE;
 139                 queue->buffer[i].buf.memory = V4L2_MEMORY_MMAP;
 140                 queue->buffer[i].buf.flags = 0;
 141                 init_waitqueue_head(&queue->buffer[i].wait);
 142         }
 143
 144         queue->mem = mem;
 145         queue->count = nbuffers;
 146         queue->buf_size = bufsize;
 147         ret = nbuffers;
 148
 149 done:
 150         mutex_unlock(&queue->mutex);
 151         return ret;
 152 }
 153
 154 /*
 155  * Free the video buffers.
 156  *
 157  * This function must be called with the queue lock held.
 158  */
 159 int uvc_free_buffers(struct uvc_video_queue *queue)
 160 {
 161         unsigned int i;
 162
 163         for (i = 0; i < queue->count; ++i) {
 164                 if (queue->buffer[i].vma_use_count != 0)
 165                         return -EBUSY;
 166         }
 167
 168         if (queue->count) {
 169                 vfree(queue->mem);
 170                 queue->count = 0;
 171         }
 172
 173         return 0;
 174 }
 175
 176 static void __uvc_query_buffer(struct uvc_buffer *buf,
 177                 struct v4l2_buffer *v4l2_buf)
 178 {
 179         memcpy(v4l2_buf, &buf->buf, sizeof *v4l2_buf);
 180
 181         if (buf->vma_use_count)
 182                 v4l2_buf->flags |= V4L2_BUF_FLAG_MAPPED;
 183
 184         switch (buf->state) {
 185         case UVC_BUF_STATE_ERROR:
 186         case UVC_BUF_STATE_DONE:
 187                 v4l2_buf->flags |= V4L2_BUF_FLAG_DONE;
 188                 break;
 189         case UVC_BUF_STATE_QUEUED:
 190         case UVC_BUF_STATE_ACTIVE:
 191                 v4l2_buf->flags |= V4L2_BUF_FLAG_QUEUED;
 192                 break;
 193         case UVC_BUF_STATE_IDLE:
 194         default:
 195                 break;
 196         }
 197 }
 198
 199 int uvc_query_buffer(struct uvc_video_queue *queue,
 200                 struct v4l2_buffer *v4l2_buf)
 201 {
 202         int ret = 0;
 203
 204         mutex_lock(&queue->mutex);
 205         if (v4l2_buf->index >= queue->count) {
 206                 ret = -EINVAL;
 207                 goto done;
 208         }
 209
 210         __uvc_query_buffer(&queue->buffer[v4l2_buf->index], v4l2_buf);
 211
 212 done:
 213        mutex_unlock(&queue->mutex);
 214        return ret;
 215 }
 216
 217 /*
 218  * Queue a video buffer. Attempting to queue a buffer that has already been
 219  * queued will return -EINVAL.
 220  */
 221 int uvc_queue_buffer(struct uvc_video_queue *queue,
 222         struct v4l2_buffer *v4l2_buf)
 223 {
 224         struct uvc_buffer *buf;
 225         unsigned long flags;
 226         int ret = 0;
 227
 228         uvc_trace(UVC_TRACE_CAPTURE, "Queuing buffer %u.\n", v4l2_buf->index);
 229
 230         if (v4l2_buf->type != queue->type ||
 231             v4l2_buf->memory != V4L2_MEMORY_MMAP) {
 232                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Invalid buffer type (%u) "
 233                         "and/or memory (%u).\n", v4l2_buf->type,
 234                         v4l2_buf->memory);
 235                 return -EINVAL;
 236         }
 237
 238         mutex_lock(&queue->mutex);
 239         if (v4l2_buf->index >= queue->count)  {
 240                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Out of range index.\n");
 241                 ret = -EINVAL;
 242                 goto done;
 243         }
 244
 245         buf = &queue->buffer[v4l2_buf->index];
 246         if (buf->state != UVC_BUF_STATE_IDLE) {
 247                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Invalid buffer state "
 248                         "(%u).\n", buf->state);
 249                 ret = -EINVAL;
 250                 goto done;
 251         }
 252
 253         if (v4l2_buf->type == V4L2_BUF_TYPE_VIDEO_OUTPUT &&
 254             v4l2_buf->bytesused > buf->buf.length) {
 255                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Bytes used out of bounds.\n");
 256                 ret = -EINVAL;
 257                 goto done;
 258         }
 259
 260         spin_lock_irqsave(&queue->irqlock, flags);
 261         if (queue->flags & UVC_QUEUE_DISCONNECTED) {
 262                 spin_unlock_irqrestore(&queue->irqlock, flags);
 263                 ret = -ENODEV;
 264                 goto done;
 265         }
 266         buf->state = UVC_BUF_STATE_QUEUED;
 267         if (v4l2_buf->type == V4L2_BUF_TYPE_VIDEO_CAPTURE)
 268                 buf->buf.bytesused = 0;
 269         else
 270                 buf->buf.bytesused = v4l2_buf->bytesused;
 271
 272         list_add_tail(&buf->stream, &queue->mainqueue);
 273         list_add_tail(&buf->queue, &queue->irqqueue);
 274         spin_unlock_irqrestore(&queue->irqlock, flags);
 275
 276 done:
 277         mutex_unlock(&queue->mutex);
 278         return ret;
 279 }
 280
 281 static int uvc_queue_waiton(struct uvc_buffer *buf, int nonblocking)
 282 {
 283         if (nonblocking) {
 284                 return (buf->state != UVC_BUF_STATE_QUEUED &&
 285                         buf->state != UVC_BUF_STATE_ACTIVE)
 286                         ? 0 : -EAGAIN;
 287         }
 288
 289         return wait_event_interruptible(buf->wait,
 290                 buf->state != UVC_BUF_STATE_QUEUED &&
 291                 buf->state != UVC_BUF_STATE_ACTIVE);
 292 }
 293
 294 /*
 295  * Dequeue a video buffer. If nonblocking is false, block until a buffer is
 296  * available.
 297  */
 298 int uvc_dequeue_buffer(struct uvc_video_queue *queue,
 299                 struct v4l2_buffer *v4l2_buf, int nonblocking)
 300 {
 301         struct uvc_buffer *buf;
 302         int ret = 0;
 303
 304         if (v4l2_buf->type != queue->type ||
 305             v4l2_buf->memory != V4L2_MEMORY_MMAP) {
 306                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Invalid buffer type (%u) "
 307                         "and/or memory (%u).\n", v4l2_buf->type,
 308                         v4l2_buf->memory);
 309                 return -EINVAL;
 310         }
 311
 312         mutex_lock(&queue->mutex);
 313         if (list_empty(&queue->mainqueue)) {
 314                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Empty buffer queue.\n");
 315                 ret = -EINVAL;
 316                 goto done;
 317         }
 318
 319         buf = list_first_entry(&queue->mainqueue, struct uvc_buffer, stream);
 320         if ((ret = uvc_queue_waiton(buf, nonblocking)) < 0)
 321                 goto done;
 322
 323         uvc_trace(UVC_TRACE_CAPTURE, "Dequeuing buffer %u (%u, %u bytes).\n",
 324                 buf->buf.index, buf->state, buf->buf.bytesused);
 325
 326         switch (buf->state) {
 327         case UVC_BUF_STATE_ERROR:
 328                 uvc_trace(UVC_TRACE_CAPTURE, "[W] Corrupted data "
 329                         "(transmission error).\n");
 330                 ret = -EIO;
 331         case UVC_BUF_STATE_DONE:
 332                 buf->state = UVC_BUF_STATE_IDLE;
 333                 break;
 334
 335         case UVC_BUF_STATE_IDLE:
 336         case UVC_BUF_STATE_QUEUED:
 337         case UVC_BUF_STATE_ACTIVE:
 338         default:
 339                 uvc_trace(UVC_TRACE_CAPTURE, "[E] Invalid buffer state %u "
 340                         "(driver bug?).\n", buf->state);
 341                 ret = -EINVAL;
 342                 goto done;
 343         }
 344
 345         list_del(&buf->stream);
 346         __uvc_query_buffer(buf, v4l2_buf);
 347
 348 done:
 349         mutex_unlock(&queue->mutex);
 350         return ret;
 351 }
 352
 353 /*
 354  * Poll the video queue.
 355  *
 356  * This function implements video queue polling and is intended to be used by
 357  * the device poll handler.
 358  */
 359 unsigned int uvc_queue_poll(struct uvc_video_queue *queue, struct file *file,
 360                 poll_table *wait)
 361 {
 362         struct uvc_buffer *buf;
 363         unsigned int mask = 0;
 364
 365         mutex_lock(&queue->mutex);
 366         if (list_empty(&queue->mainqueue)) {
 367                 mask |= POLLERR;
 368                 goto done;
 369         }
 370         buf = list_first_entry(&queue->mainqueue, struct uvc_buffer, stream);
 371
 372         poll_wait(file, &buf->wait, wait);
 373         if (buf->state == UVC_BUF_STATE_DONE ||
 374             buf->state == UVC_BUF_STATE_ERROR)
 375                 mask |= POLLIN | POLLRDNORM;
 376
 377 done:
 378         mutex_unlock(&queue->mutex);
 379         return mask;
 380 }
 381
 382 /*
 383  * Enable or disable the video buffers queue.
 384  *
 385  * The queue must be enabled before starting video acquisition and must be
 386  * disabled after stopping it. This ensures that the video buffers queue
 387  * state can be properly initialized before buffers are accessed from the
 388  * interrupt handler.
 389  *
 390  * Enabling the video queue initializes parameters (such as sequence number,
 391  * sync pattern, ...). If the queue is already enabled, return -EBUSY.
 392  *
 393  * Disabling the video queue cancels the queue and removes all buffers from
 394  * the main queue.
 395  *
 396  * This function can't be called from interrupt context. Use
 397  * uvc_queue_cancel() instead.
 398  */
 399 int uvc_queue_enable(struct uvc_video_queue *queue, int enable)
 400 {
 401         unsigned int i;
 402         int ret = 0;
 403
 404         mutex_lock(&queue->mutex);
 405         if (enable) {
 406                 if (uvc_queue_streaming(queue)) {
 407                         ret = -EBUSY;
 408                         goto done;
 409                 }
 410                 queue->sequence = 0;
 411                 queue->flags |= UVC_QUEUE_STREAMING;
 412                 queue->buf_used = 0;
 413         } else {
 414                 uvc_queue_cancel(queue, 0);
 415                 INIT_LIST_HEAD(&queue->mainqueue);
 416
 417                 for (i = 0; i < queue->count; ++i)
 418                         queue->buffer[i].state = UVC_BUF_STATE_IDLE;
 419
 420                 queue->flags &= ~UVC_QUEUE_STREAMING;
 421         }
 422
 423 done:
 424         mutex_unlock(&queue->mutex);
 425         return ret;
 426 }
 427
 428 /*
 429  * Cancel the video buffers queue.
 430  *
 431  * Cancelling the queue marks all buffers on the irq queue as erroneous,
 432  * wakes them up and remove them from the queue.
 433  *
 434  * If the disconnect parameter is set, further calls to uvc_queue_buffer will
 435  * fail with -ENODEV.
 436  *
 437  * This function acquires the irq spinlock and can be called from interrupt
 438  * context.
 439  */
 440 void uvc_queue_cancel(struct uvc_video_queue *queue, int disconnect)
 441 {
 442         struct uvc_buffer *buf;
 443         unsigned long flags;
 444
 445         spin_lock_irqsave(&queue->irqlock, flags);
 446         while (!list_empty(&queue->irqqueue)) {
 447                 buf = list_first_entry(&queue->irqqueue, struct uvc_buffer,
 448                                        queue);
 449                 list_del(&buf->queue);
 450                 buf->state = UVC_BUF_STATE_ERROR;
 451                 wake_up(&buf->wait);
 452         }
 453         /* This must be protected by the irqlock spinlock to avoid race
 454          * conditions between uvc_queue_buffer and the disconnection event that
 455          * could result in an interruptible wait in uvc_dequeue_buffer. Do not
 456          * blindly replace this logic by checking for the UVC_DEV_DISCONNECTED
 457          * state outside the queue code.
 458          */
 459         if (disconnect)
 460                 queue->flags |= UVC_QUEUE_DISCONNECTED;
 461         spin_unlock_irqrestore(&queue->irqlock, flags);
 462 }
 463
 464 struct uvc_buffer *uvc_queue_next_buffer(struct uvc_video_queue *queue,
 465                 struct uvc_buffer *buf)
 466 {
 467         struct uvc_buffer *nextbuf;
 468         unsigned long flags;
 469
 470         if ((queue->flags & UVC_QUEUE_DROP_INCOMPLETE) &&
 471             buf->buf.length != buf->buf.bytesused) {
 472                 buf->state = UVC_BUF_STATE_QUEUED;
 473                 buf->buf.bytesused = 0;
 474                 return buf;
 475         }
 476
 477         spin_lock_irqsave(&queue->irqlock, flags);
 478         list_del(&buf->queue);
 479         if (!list_empty(&queue->irqqueue))
 480                 nextbuf = list_first_entry(&queue->irqqueue, struct uvc_buffer,
 481                                            queue);
 482         else
 483                 nextbuf = NULL;
 484         spin_unlock_irqrestore(&queue->irqlock, flags);
 485
 486         buf->buf.sequence = queue->sequence++;
 487         do_gettimeofday(&buf->buf.timestamp);
 488
 489         wake_up(&buf->wait);
 490         return nextbuf;
 491 }
 492