summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@redhat.com>2009-02-14 07:29:07 -0300
committerMauro Carvalho Chehab <mchehab@redhat.com>2009-03-30 12:42:48 -0300
commit44061c05ac8dedcc45c439e871f654c9521cc726 (patch)
treebf152bb64b4265ce09f52bc46163bb4c5f6381b1
parent4b10d3b626922ffa2387905a230b12450281a12d (diff)
V4L/DVB (10570): v4l2-framework: documments videobuf usage on drivers
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
-rw-r--r--Documentation/video4linux/v4l2-framework.txt92
1 files changed, 91 insertions, 1 deletions
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index 73f9b642392..8d2db7e09e8 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -47,7 +47,9 @@ All drivers have the following structure:
3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX, /dev/radioX and
/dev/vtxX) and keeping track of device-node specific data.
-4) Filehandle-specific structs containing per-filehandle data.
+4) Filehandle-specific structs containing per-filehandle data;
+
+5) video buffer handling.
This is a rough schematic of how it all relates:
@@ -525,3 +527,91 @@ void *video_drvdata(struct file *file);
You can go from a video_device struct to the v4l2_device struct using:
struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
+
+video buffer helper functions
+-----------------------------
+
+The v4l2 core API provides a standard method for dealing with video
+buffers. Those methods allow a driver to implement read(), mmap() and
+overlay() on a consistent way.
+
+There are currently methods for using video buffers on devices that
+supports DMA with scatter/gather method (videobuf-dma-sg), DMA with
+linear access (videobuf-dma-contig), and vmalloced buffers, mostly
+used on USB drivers (videobuf-vmalloc).
+
+Any driver using videobuf should provide operations (callbacks) for
+four handlers:
+
+ops->buf_setup - calculates the size of the video buffers and avoid they
+ to waste more than some maximum limit of RAM;
+ops->buf_prepare - fills the video buffer structs and calls
+ videobuf_iolock() to alloc and prepare mmaped memory;
+ops->buf_queue - advices the driver that another buffer were
+ requested (by read() or by QBUF);
+ops->buf_release - frees any buffer that were allocated.
+
+In order to use it, the driver need to have a code (generally called at
+interrupt context) that will properly handle the buffer request lists,
+announcing that a new buffer were filled.
+
+The irq handling code should handle the videobuf task lists, in order
+to advice videobuf that a new frame were filled, in order to honor to a
+request. The code is generally like this one:
+ if (list_empty(&dma_q->active))
+ return;
+
+ buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue);
+
+ if (!waitqueue_active(&buf->vb.done))
+ return;
+
+ /* Some logic to handle the buf may be needed here */
+
+ list_del(&buf->vb.queue);
+ do_gettimeofday(&buf->vb.ts);
+ wake_up(&buf->vb.done);
+
+Those are the videobuffer functions used on drivers, implemented on
+videobuf-core:
+
+- videobuf_queue_core_init()
+ Initializes the videobuf infrastructure. This function should be
+ called before any other videobuf function.
+
+- videobuf_iolock()
+ Prepares the videobuf memory for the proper method (read, mmap, overlay).
+
+- videobuf_queue_is_busy()
+ Checks if a videobuf is streaming.
+
+- videobuf_queue_cancel()
+ Stops video handling.
+
+- videobuf_mmap_free()
+ frees mmap buffers.
+
+- videobuf_stop()
+ Stops video handling, ends mmap and frees mmap and other buffers.
+
+- V4L2 api functions. Those functions correspond to VIDIOC_foo ioctls:
+ videobuf_reqbufs(), videobuf_querybuf(), videobuf_qbuf(),
+ videobuf_dqbuf(), videobuf_streamon(), videobuf_streamoff().
+
+- V4L1 api function (corresponds to VIDIOCMBUF ioctl):
+ videobuf_cgmbuf()
+ This function is used to provide backward compatibility with V4L1
+ API.
+
+- Some help functions for read()/poll() operations:
+ videobuf_read_stream()
+ For continuous stream read()
+ videobuf_read_one()
+ For snapshot read()
+ videobuf_poll_stream()
+ polling help function
+
+The better way to understand it is to take a look at vivi driver. One
+of the main reasons for vivi is to be a videobuf usage example. the
+vivi_thread_tick() does the task that the IRQ callback would do on PCI
+drivers (or the irq callback on USB).