From 44061c05ac8dedcc45c439e871f654c9521cc726 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 14 Feb 2009 07:29:07 -0300 Subject: [PATCH] V4L/DVB (10570): v4l2-framework: documments videobuf usage on drivers Signed-off-by: Mauro Carvalho Chehab --- Documentation/video4linux/v4l2-framework.txt | 92 +++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index 73f9b642392b..8d2db7e09e89 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). -- 2.39.5