aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@redhat.com>2009-02-14 05:29:07 -0500
committerMauro Carvalho Chehab <mchehab@redhat.com>2009-03-30 11:42:48 -0400
commit44061c05ac8dedcc45c439e871f654c9521cc726 (patch)
treebf152bb64b4265ce09f52bc46163bb4c5f6381b1 /Documentation/video4linux
parent4b10d3b626922ffa2387905a230b12450281a12d (diff)
V4L/DVB (10570): v4l2-framework: documments videobuf usage on drivers
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/video4linux')
-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:
473) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX, /dev/radioX and 473) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX, /dev/radioX and
48 /dev/vtxX) and keeping track of device-node specific data. 48 /dev/vtxX) and keeping track of device-node specific data.
49 49
504) Filehandle-specific structs containing per-filehandle data. 504) Filehandle-specific structs containing per-filehandle data;
51
525) video buffer handling.
51 53
52This is a rough schematic of how it all relates: 54This is a rough schematic of how it all relates:
53 55
@@ -525,3 +527,91 @@ void *video_drvdata(struct file *file);
525You can go from a video_device struct to the v4l2_device struct using: 527You can go from a video_device struct to the v4l2_device struct using:
526 528
527struct v4l2_device *v4l2_dev = vdev->v4l2_dev; 529struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
530
531video buffer helper functions
532-----------------------------
533
534The v4l2 core API provides a standard method for dealing with video
535buffers. Those methods allow a driver to implement read(), mmap() and
536overlay() on a consistent way.
537
538There are currently methods for using video buffers on devices that
539supports DMA with scatter/gather method (videobuf-dma-sg), DMA with
540linear access (videobuf-dma-contig), and vmalloced buffers, mostly
541used on USB drivers (videobuf-vmalloc).
542
543Any driver using videobuf should provide operations (callbacks) for
544four handlers:
545
546ops->buf_setup - calculates the size of the video buffers and avoid they
547 to waste more than some maximum limit of RAM;
548ops->buf_prepare - fills the video buffer structs and calls
549 videobuf_iolock() to alloc and prepare mmaped memory;
550ops->buf_queue - advices the driver that another buffer were
551 requested (by read() or by QBUF);
552ops->buf_release - frees any buffer that were allocated.
553
554In order to use it, the driver need to have a code (generally called at
555interrupt context) that will properly handle the buffer request lists,
556announcing that a new buffer were filled.
557
558The irq handling code should handle the videobuf task lists, in order
559to advice videobuf that a new frame were filled, in order to honor to a
560request. The code is generally like this one:
561 if (list_empty(&dma_q->active))
562 return;
563
564 buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue);
565
566 if (!waitqueue_active(&buf->vb.done))
567 return;
568
569 /* Some logic to handle the buf may be needed here */
570
571 list_del(&buf->vb.queue);
572 do_gettimeofday(&buf->vb.ts);
573 wake_up(&buf->vb.done);
574
575Those are the videobuffer functions used on drivers, implemented on
576videobuf-core:
577
578- videobuf_queue_core_init()
579 Initializes the videobuf infrastructure. This function should be
580 called before any other videobuf function.
581
582- videobuf_iolock()
583 Prepares the videobuf memory for the proper method (read, mmap, overlay).
584
585- videobuf_queue_is_busy()
586 Checks if a videobuf is streaming.
587
588- videobuf_queue_cancel()
589 Stops video handling.
590
591- videobuf_mmap_free()
592 frees mmap buffers.
593
594- videobuf_stop()
595 Stops video handling, ends mmap and frees mmap and other buffers.
596
597- V4L2 api functions. Those functions correspond to VIDIOC_foo ioctls:
598 videobuf_reqbufs(), videobuf_querybuf(), videobuf_qbuf(),
599 videobuf_dqbuf(), videobuf_streamon(), videobuf_streamoff().
600
601- V4L1 api function (corresponds to VIDIOCMBUF ioctl):
602 videobuf_cgmbuf()
603 This function is used to provide backward compatibility with V4L1
604 API.
605
606- Some help functions for read()/poll() operations:
607 videobuf_read_stream()
608 For continuous stream read()
609 videobuf_read_one()
610 For snapshot read()
611 videobuf_poll_stream()
612 polling help function
613
614The better way to understand it is to take a look at vivi driver. One
615of the main reasons for vivi is to be a videobuf usage example. the
616vivi_thread_tick() does the task that the IRQ callback would do on PCI
617drivers (or the irq callback on USB).