From 9511f472cfb47c53ad0f210dd137dedfb753cea7 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 14 Feb 2009 15:54:23 +0100 Subject: v4l2-device: allow a NULL parent device when registering. From: Hans Verkuil Some drivers (e.g. for ISA devices) have no parent device because there is no associated bus driver. Allow the parent device to be NULL in those cases when registering v4l2_device. Priority: normal Signed-off-by: Hans Verkuil --- linux/Documentation/video4linux/v4l2-framework.txt | 58 +++++++++++----------- 1 file changed, 30 insertions(+), 28 deletions(-) (limited to 'linux/Documentation/video4linux') diff --git a/linux/Documentation/video4linux/v4l2-framework.txt b/linux/Documentation/video4linux/v4l2-framework.txt index a6005257a..e1620e2a3 100644 --- a/linux/Documentation/video4linux/v4l2-framework.txt +++ b/linux/Documentation/video4linux/v4l2-framework.txt @@ -84,12 +84,14 @@ You must register the device instance: v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); Registration will initialize the v4l2_device struct and link dev->driver_data -to v4l2_dev. Registration will also set v4l2_dev->name to a value derived from -dev (driver name followed by the bus_id, to be precise). You may change the -name after registration if you want. +to v4l2_dev. If v4l2_dev->name is empty then it will be set to a value derived +from dev (driver name followed by the bus_id, to be precise). If you set it +up before calling v4l2_device_register then it will be untouched. If dev is +NULL, then you *must* setup v4l2_dev->name before calling v4l2_device_register. The first 'dev' argument is normally the struct device pointer of a pci_dev, -usb_device or platform_device. +usb_device or platform_device. It is rare for dev to be NULL, but it happens +with ISA devices, for example. You unregister with: @@ -531,11 +533,11 @@ 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 +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 +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). @@ -544,50 +546,50 @@ 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; + 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); + 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 +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)) + if (list_empty(&dma_q->active)) return; - buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue); + buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue); - if (!waitqueue_active(&buf->vb.done)) + 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); + 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 +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 + 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 + 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 + 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. @@ -607,12 +609,12 @@ videobuf-core: 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_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 + This function is used to provide backward compatibility with V4L1 API. - Some help functions for read()/poll() operations: @@ -623,7 +625,7 @@ videobuf-core: 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 +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). -- cgit v1.2.3 From 951bf44feee86f832f1b68efe05395dfee73a15c Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 14 Feb 2009 16:00:53 +0100 Subject: v4l2-subdev: rename dev field to v4l2_dev From: Hans Verkuil Remain consistent in the naming: fields pointing to v4l2_device should be called v4l2_dev. There are too many device-like entities without adding to the confusion by mixing naming conventions. Priority: normal Signed-off-by: Hans Verkuil --- linux/Documentation/video4linux/v4l2-framework.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'linux/Documentation/video4linux') diff --git a/linux/Documentation/video4linux/v4l2-framework.txt b/linux/Documentation/video4linux/v4l2-framework.txt index e1620e2a3..accc376e9 100644 --- a/linux/Documentation/video4linux/v4l2-framework.txt +++ b/linux/Documentation/video4linux/v4l2-framework.txt @@ -268,7 +268,7 @@ errors (except -ENOIOCTLCMD) occured, then 0 is returned. The second argument to both calls is a group ID. If 0, then all subdevs are called. If non-zero, then only those whose group ID match that value will -be called. Before a bridge driver registers a subdev it can set subdev->grp_id +be called. Before a bridge driver registers a subdev it can set sd->grp_id to whatever value it wants (it's 0 by default). This value is owned by the bridge driver and the sub-device driver will never modify or use it. -- cgit v1.2.3