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 queue
->scratch
= vmalloc_32(bufsize
);
135 if (queue
->scratch
== NULL
) {
140 /* Decrement the number of buffers until allocation succeeds. */
141 for (; nbuffers
>= queue
->min_buffers
; --nbuffers
) {
142 mem
= vmalloc_32(nbuffers
* bufsize
);
143 buffer
= kzalloc(nbuffers
* sizeof(struct microdia_buffer
),
145 if (mem
!= NULL
&& buffer
!= NULL
)
153 if (mem
== NULL
|| buffer
== NULL
) {
155 vfree(queue
->scratch
);
158 queue
->buffer
= buffer
;
160 for (i
= 0; i
< nbuffers
; ++i
) {
161 memset(&queue
->buffer
[i
], 0, sizeof queue
->buffer
[i
]);
162 queue
->buffer
[i
].buf
.index
= i
;
163 queue
->buffer
[i
].buf
.m
.offset
= i
* bufsize
;
164 queue
->buffer
[i
].buf
.length
= buflength
;
165 queue
->buffer
[i
].buf
.type
= V4L2_BUF_TYPE_VIDEO_CAPTURE
;
166 queue
->buffer
[i
].buf
.sequence
= 0;
167 queue
->buffer
[i
].buf
.field
= V4L2_FIELD_NONE
;
168 queue
->buffer
[i
].buf
.memory
= V4L2_MEMORY_MMAP
;
169 queue
->buffer
[i
].buf
.flags
= 0;
170 init_waitqueue_head(&queue
->buffer
[i
].wait
);
174 queue
->count
= nbuffers
;
175 queue
->buf_size
= bufsize
;
179 mutex_unlock(&queue
->mutex
);
184 * @brief Free the video buffers.
188 * This function must be called with the queue lock held.
190 int microdia_free_buffers(struct microdia_video_queue
*queue
)
193 UDIA_INFO("Freeing %d v4l2 buffers\n", queue
->count
);
195 for (i
= 0; i
< queue
->count
; ++i
) {
196 if (queue
->buffer
[i
].vma_use_count
!= 0)
201 #if LINUX_VERSION_CODE < KERNEL_VERSION(2, 6, 15)
202 unsigned long addr
= (unsigned long)queue
->mem
;
203 size_t size
= queue
->count
* queue
->buf_size
;
205 ClearPageReserved(vmalloc_to_page((void *)addr
));
211 vfree(queue
->scratch
);
212 kfree(queue
->buffer
);
213 INIT_LIST_HEAD(&queue
->mainqueue
);
214 INIT_LIST_HEAD(&queue
->irqqueue
);
226 static void __microdia_query_buffer(struct microdia_buffer
*buf
,
227 struct v4l2_buffer
*v4l2_buf
)
229 memcpy(v4l2_buf
, &buf
->buf
, sizeof *v4l2_buf
);
231 if (buf
->vma_use_count
)
232 v4l2_buf
->flags
|= V4L2_BUF_FLAG_MAPPED
;
234 switch (buf
->state
) {
235 case MICRODIA_BUF_STATE_ERROR
:
236 case MICRODIA_BUF_STATE_DONE
:
237 v4l2_buf
->flags
|= V4L2_BUF_FLAG_DONE
;
239 case MICRODIA_BUF_STATE_QUEUED
:
240 case MICRODIA_BUF_STATE_ACTIVE
:
241 v4l2_buf
->flags
|= V4L2_BUF_FLAG_QUEUED
;
243 case MICRODIA_BUF_STATE_IDLE
:
253 * @return 0 or negative error code
256 int microdia_query_buffer(struct microdia_video_queue
*queue
,
257 struct v4l2_buffer
*v4l2_buf
)
261 mutex_lock(&queue
->mutex
);
262 if (v4l2_buf
->index
>= queue
->count
) {
267 __microdia_query_buffer(&queue
->buffer
[v4l2_buf
->index
], v4l2_buf
);
270 mutex_unlock(&queue
->mutex
);
275 * @brief Queue a video buffer.
280 * @return 0 or negative error code
282 * Attempting to queue a buffer that has already been
283 * queued will return -EINVAL.
285 int microdia_queue_buffer(struct microdia_video_queue
*queue
,
286 struct v4l2_buffer
*v4l2_buf
)
288 struct microdia_buffer
*buf
;
292 UDIA_DEBUG("Queuing buffer %u.\n", v4l2_buf
->index
);
294 if (v4l2_buf
->type
!= V4L2_BUF_TYPE_VIDEO_CAPTURE
||
295 v4l2_buf
->memory
!= V4L2_MEMORY_MMAP
) {
296 UDIA_ERROR("[E] Invalid buffer type (%u) "
297 "and/or memory (%u).\n", v4l2_buf
->type
,
302 mutex_lock(&queue
->mutex
);
303 if (v4l2_buf
->index
>= queue
->count
) {
304 UDIA_ERROR("[E] Out of range index.\n");
309 buf
= &queue
->buffer
[v4l2_buf
->index
];
310 if (buf
->state
!= MICRODIA_BUF_STATE_IDLE
) {
311 UDIA_ERROR("[E] Invalid buffer state "
312 "(%u).\n", buf
->state
);
317 buf
->state
= MICRODIA_BUF_STATE_QUEUED
;
318 buf
->buf
.bytesused
= 0;
319 list_add_tail(&buf
->stream
, &queue
->mainqueue
);
320 spin_lock_irqsave(&queue
->irqlock
, flags
);
321 list_add_tail(&buf
->queue
, &queue
->irqqueue
);
322 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
325 mutex_unlock(&queue
->mutex
);
334 static int microdia_queue_waiton(struct microdia_buffer
*buf
, int nonblocking
)
337 return (buf
->state
!= MICRODIA_BUF_STATE_QUEUED
&&
338 buf
->state
!= MICRODIA_BUF_STATE_ACTIVE
)
342 return wait_event_interruptible(buf
->wait
,
343 buf
->state
!= MICRODIA_BUF_STATE_QUEUED
&&
344 buf
->state
!= MICRODIA_BUF_STATE_ACTIVE
);
348 * @brief Dequeue a video buffer.
354 * @return 0 or negative error code
356 * If nonblocking is false, block until a buffer is
359 int microdia_dequeue_buffer(struct microdia_video_queue
*queue
,
360 struct v4l2_buffer
*v4l2_buf
, int nonblocking
)
362 struct microdia_buffer
*buf
;
365 if (v4l2_buf
->type
!= V4L2_BUF_TYPE_VIDEO_CAPTURE
||
366 v4l2_buf
->memory
!= V4L2_MEMORY_MMAP
) {
367 UDIA_ERROR("[E] Invalid buffer type (%u) "
368 "and/or memory (%u).\n", v4l2_buf
->type
,
373 mutex_lock(&queue
->mutex
);
374 if (list_empty(&queue
->mainqueue
)) {
375 UDIA_ERROR("[E] Empty buffer queue.\n");
380 buf
= list_first_entry(&queue
->mainqueue
, struct microdia_buffer
,
383 ret
= microdia_queue_waiton(buf
, nonblocking
);
387 UDIA_DEBUG("Dequeuing buffer %u (%u, %u bytes).\n",
388 buf
->buf
.index
, buf
->state
, buf
->buf
.bytesused
);
390 switch (buf
->state
) {
391 case MICRODIA_BUF_STATE_ERROR
:
392 UDIA_WARNING("[W] Corrupted data (transmission error).\n");
394 case MICRODIA_BUF_STATE_DONE
:
395 buf
->state
= MICRODIA_BUF_STATE_IDLE
;
398 case MICRODIA_BUF_STATE_IDLE
:
399 case MICRODIA_BUF_STATE_QUEUED
:
400 case MICRODIA_BUF_STATE_ACTIVE
:
402 UDIA_ERROR("[E] Invalid buffer state %u "
403 "(driver bug?).\n", buf
->state
);
408 list_del(&buf
->stream
);
409 __microdia_query_buffer(buf
, v4l2_buf
);
412 mutex_unlock(&queue
->mutex
);
417 * @brief Poll the video queue.
423 * This function implements video queue polling and is intended to be used by
424 * the device poll handler.
426 unsigned int microdia_queue_poll(struct microdia_video_queue
*queue
,
427 struct file
*file
, poll_table
*wait
)
429 struct microdia_buffer
*buf
;
430 unsigned int mask
= 0;
432 mutex_lock(&queue
->mutex
);
433 if (list_empty(&queue
->mainqueue
)) {
437 buf
= list_first_entry(&queue
->mainqueue
, struct microdia_buffer
,
440 poll_wait(file
, &buf
->wait
, wait
);
441 if (buf
->state
== MICRODIA_BUF_STATE_DONE
||
442 buf
->state
== MICRODIA_BUF_STATE_ERROR
)
443 mask
|= POLLIN
| POLLRDNORM
;
446 mutex_unlock(&queue
->mutex
);
451 * @brief Enable or disable the video buffers queue.
456 * @return 0 or negative error code
458 * The queue must be enabled before starting video acquisition and must be
459 * disabled after stopping it. This ensures that the video buffers queue
460 * state can be properly initialized before buffers are accessed from the
463 * Enabling the video queue initializes parameters (such as sequence number,
464 * sync pattern, ...). If the queue is already enabled, return -EBUSY.
466 * Disabling the video queue cancels the queue and removes all buffers from
469 * This function can't be called from interrupt context. Use
470 * microdia_queue_cancel() instead.
472 int microdia_queue_enable(struct microdia_video_queue
*queue
, int enable
)
477 mutex_lock(&queue
->mutex
);
479 if (queue
->streaming
) {
484 queue
->streaming
= 1;
486 microdia_queue_cancel(queue
);
487 INIT_LIST_HEAD(&queue
->mainqueue
);
489 for (i
= 0; i
< queue
->count
; ++i
)
490 queue
->buffer
[i
].state
= MICRODIA_BUF_STATE_IDLE
;
492 queue
->streaming
= 0;
496 mutex_unlock(&queue
->mutex
);
501 * @brief Cancel the video buffers queue.
505 * Cancelling the queue marks all buffers on the irq queue as erroneous,
506 * wakes them up and remove them from the queue.
508 * This function acquires the irq spinlock and can be called from interrupt
511 void microdia_queue_cancel(struct microdia_video_queue
*queue
)
513 struct microdia_buffer
*buf
;
516 spin_lock_irqsave(&queue
->irqlock
, flags
);
517 while (!list_empty(&queue
->irqqueue
)) {
518 buf
= list_first_entry(&queue
->irqqueue
, struct microdia_buffer
,
520 list_del(&buf
->queue
);
521 buf
->state
= MICRODIA_BUF_STATE_ERROR
;
524 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
532 struct microdia_buffer
*microdia_queue_next_buffer(
533 struct microdia_video_queue
*queue
,
534 struct microdia_buffer
*buf
)
536 struct microdia_buffer
*nextbuf
;
539 if (queue
->drop_incomplete
&& queue
->frame_size
!= buf
->buf
.bytesused
) {
540 buf
->state
= MICRODIA_BUF_STATE_QUEUED
;
541 buf
->buf
.bytesused
= 0;
545 spin_lock_irqsave(&queue
->irqlock
, flags
);
546 list_del(&buf
->queue
);
547 if (!list_empty(&queue
->irqqueue
))
548 nextbuf
= list_first_entry(&queue
->irqqueue
,
549 struct microdia_buffer
, queue
);
552 spin_unlock_irqrestore(&queue
->irqlock
, flags
);
554 buf
->buf
.sequence
= queue
->sequence
++;
555 do_gettimeofday(&buf
->buf
.timestamp
);