The patch number 10623 was added via Jean-Francois Moine <moin...@free.fr>
to http://linuxtv.org/hg/v4l-dvb master development tree.
Kernel patches in this development tree may be modified to be backward
compatible with older kernels. Compatibility modifications will be
removed before inclusion into the mainstream Kernel
If anyone has any objections, please let us know by sending a message to:
Linux Media Mailing List <linux-me...@vger.kernel.org>
------
merge: v4l-dvb
---
linux/Documentation/video4linux/v4l2-framework.txt | 104 ++++++++++++-
1 file changed, 103 insertions(+), 1 deletion(-)
diff -r adcf2edc7a26 -r 51b87cc49125
linux/Documentation/video4linux/v4l2-framework.txt
--- a/linux/Documentation/video4linux/v4l2-framework.txt Sat Feb 14
11:12:43 2009 +0100
+++ b/linux/Documentation/video4linux/v4l2-framework.txt Sun Feb 15
08:21:14 2009 +0100
@@ -47,7 +47,9 @@ 3) Creating V4L2 device nodes (/dev/vide
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,103 @@ You can go from a video_device struct to
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 init functions
+ videobuf_queue_sg_init()
+ Initializes the videobuf infrastructure. This function should be
+ called before any other videobuf function on drivers that uses DMA
+ Scatter/Gather buffers.
+
+ videobuf_queue_dma_contig_init
+ Initializes the videobuf infrastructure. This function should be
+ called before any other videobuf function on drivers that need DMA
+ contiguous buffers.
+
+ videobuf_queue_vmalloc_init()
+ Initializes the videobuf infrastructure. This function should be
+ called before any other videobuf function on USB (and other drivers)
+ that need a vmalloced type of videobuf.
+
+- 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).
---
Patch is available at:
http://linuxtv.org/hg/v4l-dvb/rev/51b87cc49125a91750250b880907e136ded660d2
_______________________________________________
linuxtv-commits mailing list
linuxtv-commits@linuxtv.org
http://www.linuxtv.org/cgi-bin/mailman/listinfo/linuxtv-commits
