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