2 * @file microdia-queue.c
3 * @author Brian Johnson
5 * @brief Buffer management
7 * @note Original code from UVC webcam driver
8 * @note Copyright (C) 2005-2008 Laurent Pinchart (laurent.pinchart@skynet.be)
9 * @note Copyright (C) 2008 Brian Johnson (brijohn@gmail.com)
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
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * ------------------------------------------------------------------------
18 * Video buffers queue management.
20 * Video queues is initialized by microdia_queue_init(). The function performs
21 * basic initialization of the microdia_video_queue struct and never fails.
23 * Video buffer allocation and freeing are performed by microdia_alloc_buffers()
24 * and microdia_free_buffers() respectively. The former acquires the video queue
25 * lock, while the later must be called with the lock held (so that allocation
26 * can free previously allocated buffers). Trying to free buffers that are
27 * mapped to user space will return -EBUSY.
29 * Video buffers are managed using two queues. However, unlike most USB video
30 * drivers which use an in queue and an out queue, we use a main queue which
31 * holds all queued buffers (both 'empty' and 'done' buffers), and an irq
32 * queue which holds empty buffers. This design (copied from video-buf)
33 * minimizes locking in interrupt, as only one queue is shared between
34 * interrupt and user contexts.
39 * Unless stated otherwise, all operations which modify the irq buffers queue
40 * are protected by the irq spinlock.
42 * 1. The user queues the buffers, starts streaming and dequeues a buffer.
44 * The buffers are added to the main and irq queues. Both operations are
45 * protected by the queue lock, and the latert is protected by the irq
48 * The completion handler fetches a buffer from the irq queue and fills it
49 * with video data. If no buffer is available (irq queue empty), the handler
50 * returns immediately.
52 * When the buffer is full, the completion handler removes it from the irq
53 * queue, marks it as ready (MICRODIA_BUF_STATE_DONE) and wake its wait
54 * queue. At that point, any process waiting on the buffer will be woken up.
55 * If a process tries to dequeue a buffer after it has been marked ready,
56 * the dequeing will succeed immediately.
58 * 2. Buffers are queued, user is waiting on a buffer and the device gets
61 * When the device is disconnected, the kernel calls the completion handler
62 * with an appropriate status code. The handler marks all buffers in the
63 * irq queue as being erroneous (MICRODIA_BUF_STATE_ERROR) and wakes them up
64 * so that any process waiting on a buffer gets woken up.
66 * Waking up up the first buffer on the irq list is not enough, as the
67 * process waiting on the buffer might restart the dequeue operation
72 #include <linux/kernel.h>
73 #include <linux/version.h>
74 #include <linux/list.h>
75 #include <linux/module.h>
76 #include <linux/usb.h>
77 #include <linux/videodev.h>
78 #include <linux/vmalloc.h>
79 #include <linux/wait.h>
81 #include <asm/atomic.h>
89 void microdia_queue_init(struct microdia_video_queue
*queue
)
91 mutex_init(&queue
->mutex
);
92 spin_lock_init(&queue
->irqlock
);
93 INIT_LIST_HEAD(&queue
->mainqueue
);
94 INIT_LIST_HEAD(&queue
->irqqueue
);
98 * @brief Allocate the video buffers.
104 * Pages are reserved to make sure they will not be swaped, as they will be
105 * filled in URB completion handler.
107 * Buffers will be individually mapped, so they must all be page aligned.
109 int microdia_alloc_buffers(struct microdia_video_queue
*queue
,
110 unsigned int nbuffers
, unsigned int buflength
)
112 unsigned int bufsize
= PAGE_ALIGN(buflength
);
118 mutex_lock(&queue
->mutex
);
120 ret
= microdia_free_buffers(queue
);
124 /* Bail out if no buffers should be allocated. */
128 if (nbuffers
< queue
->min_buffers
)
129 nbuffers
= queue
->min_buffers
;
130 else if (nbuffers
> queue
->max_buffers
)
131 nbuffers
= queue
->max_buffers
;
133 /* Decrement the number of buffers until allocation succeeds. */
134 for (; nbuffers
>= queue
->min_buffers
; --nbuffers
) {
135 mem
= vmalloc_32(nbuffers
* bufsize
);
136 buffer
= kzalloc(nbuffers
* sizeof(struct microdia_buffer
),
138 if (mem
!= NULL
&& buffer
!= NULL
)
146 if (mem
== NULL
|| buffer
== NULL
) {
150 queue
->buffer
= buffer
;
152 for (i
= 0; i
< nbuffers
; ++i
) {
153 memset(&queue
->buffer
[i
], 0, sizeof queue
->buffer
[i
]);
154 queue
->buffer
[i
].buf
.index
= i
;
155 queue
->buffer
[i
].buf
.m
.offset
= i
* bufsize
;
156 queue
->buffer
[i
].buf
.length
= buflength
;
157 queue
->buffer
[i
].buf
.type
= V4L2_BUF_TYPE_VIDEO_CAPTURE
;
158 queue
->buffer
[i
].buf
.sequence
= 0;
159 queue
->buffer
[i
].buf
.field
= V4L2_FIELD_NONE
;
160 queue
->buffer
[i
].buf
.memory
= V4L2_MEMORY_MMAP
;
161 queue
->buffer
[i
].buf
.flags
= 0;
162 init_waitqueue_head(&queue
->buffer
[i
].wait
);
166 queue
->count
= nbuffers
;
167 queue
->buf_size
= bufsize
;
171 mutex_unlock(&queue
->mutex
);
176 * @brief Free the video buffers.
180 * This function must be called with the queue lock held.
182 int microdia_free_buffers(struct microdia_video_queue
*queue
)
185 UDIA_INFO("Freeing %d v4l2 buffers\n", queue
->count
);
187 for (i
= 0; i
< queue
->count
; ++i
) {
188 if (queue
->buffer
[i
].vma_use_count
!= 0)
193 #if LINUX_VERSION_CODE < KERNEL_VERSION(2, 6, 15)
194 unsigned long addr
= (unsigned long)queue
->mem
;
195 size_t size
= queue
->count
* queue
->buf_size
;
197 ClearPageReserved(vmalloc_to_page((void *)addr
));
203 kfree(queue
->buffer
);
204 INIT_LIST_HEAD(&queue
->mainqueue
);
205 INIT_LIST_HEAD(&queue
->irqqueue
);
217 static void __microdia_query_buffer(struct microdia_buffer
*buf
,
218 struct v4l2_buffer
*v4l2_buf
)
220 memcpy(v4l2_buf
, &buf
->buf
, sizeof *v4l2_buf
);
222 if (buf
->vma_use_count
)
223 v4l2_buf
->flags
|= V4L2_BUF_FLAG_MAPPED
;
225 switch (buf
->state
) {
226 case MICRODIA_BUF_STATE_ERROR
:
227 case MICRODIA_BUF_STATE_DONE
:
228 v4l2_buf
->flags
|= V4L2_BUF_FLAG_DONE
;
230 case MICRODIA_BUF_STATE_QUEUED
:
231 case MICRODIA_BUF_STATE_ACTIVE
:
232 v4l2_buf
->flags
|= V4L2_BUF_FLAG_QUEUED
;
234 case MICRODIA_BUF_STATE_IDLE
:
244 * @return 0 or negative error code
247 int microdia_query_buffer(struct microdia_video_queue
*queue
,
248 struct v4l2_buffer
*v4l2_buf
)
252 mutex_lock(&queue
->mutex
);
253 if (v4l2_buf
->index
>= queue
->count
) {
258 __microdia_query_buffer(&queue
->buffer
[v4l2_buf
->index
], v4l2_buf
);
261 mutex_unlock(&queue
->mutex
);
266 * @brief Queue a video buffer.
271 * @return 0 or negative error code
273 * Attempting to queue a buffer that has already been
274 * queued will return -EINVAL.
276 int microdia_queue_buffer(struct microdia_video_queue
*queue
,
277 struct v4l2_buffer
*v4l2_buf
)
279 struct microdia_buffer
*buf
;
283 UDIA_DEBUG("Queuing buffer %u.\n", v4l2_buf
->index
);
285 if (v4l2_buf
->type
!= V4L2_BUF_TYPE_VIDEO_CAPTURE
||
286 v4l2_buf
->memory
!= V4L2_MEMORY_MMAP
) {
287 UDIA_ERROR("[E] Invalid buffer type (%u) "
288 "and/or memory (%u).\n", v4l2_buf
->type
,
293 mutex_lock(&queue
->mutex
);
294 if (v4l2_buf
->index
>= queue
->count
) {
295 UDIA_ERROR("[E] Out of range index.\n");
300 buf
= &queue
->buffer
[v4l2_buf
->index
];
301 if (buf
->state
!= MICRODIA_BUF_STATE_IDLE
) {
302 UDIA_ERROR("[E] Invalid buffer state "
303 "(%u).\n", buf
->state
);
308 spin_lock_irqsave(&queue
->irqlock
, flags
);
309 if (queue
->flags
& MICRODIA_QUEUE_DISCONNECTED
) {
310 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
315 buf
->state
= MICRODIA_BUF_STATE_QUEUED
;
316 buf
->buf
.bytesused
= 0;
317 list_add_tail(&buf
->stream
, &queue
->mainqueue
);
318 list_add_tail(&buf
->queue
, &queue
->irqqueue
);
319 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
322 mutex_unlock(&queue
->mutex
);
331 static int microdia_queue_waiton(struct microdia_buffer
*buf
, int nonblocking
)
334 return (buf
->state
!= MICRODIA_BUF_STATE_QUEUED
&&
335 buf
->state
!= MICRODIA_BUF_STATE_ACTIVE
)
339 return wait_event_interruptible(buf
->wait
,
340 buf
->state
!= MICRODIA_BUF_STATE_QUEUED
&&
341 buf
->state
!= MICRODIA_BUF_STATE_ACTIVE
);
345 * @brief Dequeue a video buffer.
351 * @return 0 or negative error code
353 * If nonblocking is false, block until a buffer is
356 int microdia_dequeue_buffer(struct microdia_video_queue
*queue
,
357 struct v4l2_buffer
*v4l2_buf
, int nonblocking
)
359 struct microdia_buffer
*buf
;
362 if (v4l2_buf
->type
!= V4L2_BUF_TYPE_VIDEO_CAPTURE
||
363 v4l2_buf
->memory
!= V4L2_MEMORY_MMAP
) {
364 UDIA_ERROR("[E] Invalid buffer type (%u) "
365 "and/or memory (%u).\n", v4l2_buf
->type
,
370 mutex_lock(&queue
->mutex
);
371 if (list_empty(&queue
->mainqueue
)) {
372 UDIA_ERROR("[E] Empty buffer queue.\n");
377 buf
= list_first_entry(&queue
->mainqueue
, struct microdia_buffer
,
380 ret
= microdia_queue_waiton(buf
, nonblocking
);
384 UDIA_DEBUG("Dequeuing buffer %u (%u, %u bytes).\n",
385 buf
->buf
.index
, buf
->state
, buf
->buf
.bytesused
);
387 switch (buf
->state
) {
388 case MICRODIA_BUF_STATE_ERROR
:
389 UDIA_WARNING("[W] Corrupted data (transmission error).\n");
391 case MICRODIA_BUF_STATE_DONE
:
392 buf
->state
= MICRODIA_BUF_STATE_IDLE
;
395 case MICRODIA_BUF_STATE_IDLE
:
396 case MICRODIA_BUF_STATE_QUEUED
:
397 case MICRODIA_BUF_STATE_ACTIVE
:
399 UDIA_ERROR("[E] Invalid buffer state %u "
400 "(driver bug?).\n", buf
->state
);
405 list_del(&buf
->stream
);
406 __microdia_query_buffer(buf
, v4l2_buf
);
409 mutex_unlock(&queue
->mutex
);
414 * @brief Poll the video queue.
420 * This function implements video queue polling and is intended to be used by
421 * the device poll handler.
423 unsigned int microdia_queue_poll(struct microdia_video_queue
*queue
,
424 struct file
*file
, poll_table
*wait
)
426 struct microdia_buffer
*buf
;
427 unsigned int mask
= 0;
429 mutex_lock(&queue
->mutex
);
430 if (list_empty(&queue
->mainqueue
)) {
434 buf
= list_first_entry(&queue
->mainqueue
, struct microdia_buffer
,
437 poll_wait(file
, &buf
->wait
, wait
);
438 if (buf
->state
== MICRODIA_BUF_STATE_DONE
||
439 buf
->state
== MICRODIA_BUF_STATE_ERROR
)
440 mask
|= POLLIN
| POLLRDNORM
;
443 mutex_unlock(&queue
->mutex
);
448 * @brief Enable or disable the video buffers queue.
453 * @return 0 or negative error code
455 * The queue must be enabled before starting video acquisition and must be
456 * disabled after stopping it. This ensures that the video buffers queue
457 * state can be properly initialized before buffers are accessed from the
460 * Enabling the video queue initializes parameters (such as sequence number,
461 * sync pattern, ...). If the queue is already enabled, return -EBUSY.
463 * Disabling the video queue cancels the queue and removes all buffers from
466 * This function can't be called from interrupt context. Use
467 * microdia_queue_cancel() instead.
469 int microdia_queue_enable(struct microdia_video_queue
*queue
, int enable
)
474 mutex_lock(&queue
->mutex
);
476 if (microdia_queue_streaming(queue
)) {
481 queue
->flags
|= MICRODIA_QUEUE_STREAMING
;
483 microdia_queue_cancel(queue
, 0);
484 INIT_LIST_HEAD(&queue
->mainqueue
);
486 for (i
= 0; i
< queue
->count
; ++i
)
487 queue
->buffer
[i
].state
= MICRODIA_BUF_STATE_IDLE
;
489 queue
->flags
&= ~MICRODIA_QUEUE_STREAMING
;
493 mutex_unlock(&queue
->mutex
);
498 * @brief Cancel the video buffers queue.
504 * Cancelling the queue marks all buffers on the irq queue as erroneous,
505 * wakes them up and remove them from the queue.
507 * If the disconnect parameter is set, further calls to uvc_queue_buffer will
510 * This function acquires the irq spinlock and can be called from interrupt
513 void microdia_queue_cancel(struct microdia_video_queue
*queue
, int disconnect
)
515 struct microdia_buffer
*buf
;
518 spin_lock_irqsave(&queue
->irqlock
, flags
);
519 while (!list_empty(&queue
->irqqueue
)) {
520 buf
= list_first_entry(&queue
->irqqueue
, struct microdia_buffer
,
522 list_del(&buf
->queue
);
523 buf
->state
= MICRODIA_BUF_STATE_ERROR
;
526 /* This must be protected by the irqlock spinlock to avoid race
527 * conditions between microdia_queue_buffer and the disconnection
528 * event that could result in an interruptible wait in
529 * microdia_dequeue_buffer. Do not blindly replace this logic by
530 * checking for the MICRODIA_DEV_DISCONNECTED state outside the
534 queue
->flags
|= MICRODIA_QUEUE_DISCONNECTED
;
535 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
543 struct microdia_buffer
*microdia_queue_next_buffer(
544 struct microdia_video_queue
*queue
,
545 struct microdia_buffer
*buf
)
547 struct microdia_buffer
*nextbuf
;
550 if ((queue
->flags
& MICRODIA_QUEUE_DROP_INCOMPLETE
) &&
551 buf
->buf
.length
!= buf
->buf
.bytesused
) {
552 buf
->state
= MICRODIA_BUF_STATE_QUEUED
;
553 buf
->buf
.bytesused
= 0;
557 spin_lock_irqsave(&queue
->irqlock
, flags
);
558 list_del(&buf
->queue
);
559 if (!list_empty(&queue
->irqqueue
))
560 nextbuf
= list_first_entry(&queue
->irqqueue
,
561 struct microdia_buffer
, queue
);
564 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
566 buf
->buf
.sequence
= queue
->sequence
++;
567 do_gettimeofday(&buf
->buf
.timestamp
);