summaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2009-04-06 18:08:58 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2009-04-06 18:11:41 -0700
commit4ef4327b30957a16619ac7d47c749465e62de8c3 (patch)
tree5c80e853f0d9eadd01b2019d03d2432334393c5e /Documentation
parent3989203290fba6fdf6bc4825fbf6526e1bf17977 (diff)
parenta938b8c5be8fe5c28800c9cef4aa43d569aa57a8 (diff)
downloadlinux-4ef4327b30957a16619ac7d47c749465e62de8c3.tar.gz
linux-4ef4327b30957a16619ac7d47c749465e62de8c3.tar.bz2
linux-4ef4327b30957a16619ac7d47c749465e62de8c3.zip
Merge branch 'for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-2.6
* 'for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-2.6: (120 commits) cx231xx: Convert to snd_card_create() V4L/DVB (11440): PWC: fix build error when CONFIG_INPUT=m V4L/DVB (11439): UVC: uvc_status_cleanup(): undefined reference to `input_unregister_device' V4L/DVB (11438): au0828: fix Kconfig dependance V4L/DVB (11437): pvrusb2: Drop client_register/unregister stubs V4L/DVB (11436): radio-mr800: convert to to v4l2_device V4L/DVB (11435): dsbr100 radio: convert to to v4l2_device V4L/DVB: zr364xx: remove unused #include <version.h> V4L/DVB: usbvision: remove unused #include <version.h> V4L/DVB (11427): gspca - m5602: Minor cleanups V4L/DVB (11426): gspca - m5602: Don't touch hflip/vflip register on Read/Modify/Write V4L/DVB (11425): gspca - m5602: Move the vflip quirk to probe stage. V4L/DVB (11424): gspca - m5602-ov9650: Use the local ctrl cache. Adjust image on vflip. V4L/DVB (11423): gspca - m5602-ov9650: Add a disconnect hook, setup a ctrl cache ctrl. V4L/DVB (11422): gspca - m5602-ov9650: Replace a magic constant with a define V4L/DVB (11421): gspca - m5602-ov9650: Synthesize modesetting. V4L/DVB (11420): gspca - m5602: Improve error handling in the ov9650 driver V4L/DVB (11419): gspca - m5602-ov9650: Don't read exposure data from COM1. V4L/DVB (11418): gspca - m5602-ov9650: Auto white balancing is on by default V4L/DVB (11417): gspca - m5602-ov9650: Autogain is on by default ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/video4linux/pxa_camera.txt125
-rw-r--r--Documentation/video4linux/v4l2-framework.txt21
2 files changed, 129 insertions, 17 deletions
diff --git a/Documentation/video4linux/pxa_camera.txt b/Documentation/video4linux/pxa_camera.txt
new file mode 100644
index 000000000000..b1137f9a53eb
--- /dev/null
+++ b/Documentation/video4linux/pxa_camera.txt
@@ -0,0 +1,125 @@
+ PXA-Camera Host Driver
+ ======================
+
+Constraints
+-----------
+ a) Image size for YUV422P format
+ All YUV422P images are enforced to have width x height % 16 = 0.
+ This is due to DMA constraints, which transfers only planes of 8 byte
+ multiples.
+
+
+Global video workflow
+---------------------
+ a) QCI stopped
+ Initialy, the QCI interface is stopped.
+ When a buffer is queued (pxa_videobuf_ops->buf_queue), the QCI starts.
+
+ b) QCI started
+ More buffers can be queued while the QCI is started without halting the
+ capture. The new buffers are "appended" at the tail of the DMA chain, and
+ smoothly captured one frame after the other.
+
+ Once a buffer is filled in the QCI interface, it is marked as "DONE" and
+ removed from the active buffers list. It can be then requeud or dequeued by
+ userland application.
+
+ Once the last buffer is filled in, the QCI interface stops.
+
+
+DMA usage
+---------
+ a) DMA flow
+ - first buffer queued for capture
+ Once a first buffer is queued for capture, the QCI is started, but data
+ transfer is not started. On "End Of Frame" interrupt, the irq handler
+ starts the DMA chain.
+ - capture of one videobuffer
+ The DMA chain starts transfering data into videobuffer RAM pages.
+ When all pages are transfered, the DMA irq is raised on "ENDINTR" status
+ - finishing one videobuffer
+ The DMA irq handler marks the videobuffer as "done", and removes it from
+ the active running queue
+ Meanwhile, the next videobuffer (if there is one), is transfered by DMA
+ - finishing the last videobuffer
+ On the DMA irq of the last videobuffer, the QCI is stopped.
+
+ b) DMA prepared buffer will have this structure
+
+ +------------+-----+---------------+-----------------+
+ | desc-sg[0] | ... | desc-sg[last] | finisher/linker |
+ +------------+-----+---------------+-----------------+
+
+ This structure is pointed by dma->sg_cpu.
+ The descriptors are used as follows :
+ - desc-sg[i]: i-th descriptor, transfering the i-th sg
+ element to the video buffer scatter gather
+ - finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
+ - linker: has ddadr= desc-sg[0] of next video buffer, dcmd=0
+
+ For the next schema, let's assume d0=desc-sg[0] .. dN=desc-sg[N],
+ "f" stands for finisher and "l" for linker.
+ A typical running chain is :
+
+ Videobuffer 1 Videobuffer 2
+ +---------+----+---+ +----+----+----+---+
+ | d0 | .. | dN | l | | d0 | .. | dN | f |
+ +---------+----+-|-+ ^----+----+----+---+
+ | |
+ +----+
+
+ After the chaining is finished, the chain looks like :
+
+ Videobuffer 1 Videobuffer 2 Videobuffer 3
+ +---------+----+---+ +----+----+----+---+ +----+----+----+---+
+ | d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f |
+ +---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+
+ | | | |
+ +----+ +----+
+ new_link
+
+ c) DMA hot chaining timeslice issue
+
+ As DMA chaining is done while DMA _is_ running, the linking may be done
+ while the DMA jumps from one Videobuffer to another. On the schema, that
+ would be a problem if the following sequence is encountered :
+
+ - DMA chain is Videobuffer1 + Videobuffer2
+ - pxa_videobuf_queue() is called to queue Videobuffer3
+ - DMA controller finishes Videobuffer2, and DMA stops
+ =>
+ Videobuffer 1 Videobuffer 2
+ +---------+----+---+ +----+----+----+---+
+ | d0 | .. | dN | l | | d0 | .. | dN | f |
+ +---------+----+-|-+ ^----+----+----+-^-+
+ | | |
+ +----+ +-- DMA DDADR loads DDADR_STOP
+
+ - pxa_dma_add_tail_buf() is called, the Videobuffer2 "finisher" is
+ replaced by a "linker" to Videobuffer3 (creation of new_link)
+ - pxa_videobuf_queue() finishes
+ - the DMA irq handler is called, which terminates Videobuffer2
+ - Videobuffer3 capture is not scheduled on DMA chain (as it stopped !!!)
+
+ Videobuffer 1 Videobuffer 2 Videobuffer 3
+ +---------+----+---+ +----+----+----+---+ +----+----+----+---+
+ | d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f |
+ +---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+
+ | | | |
+ +----+ +----+
+ new_link
+ DMA DDADR still is DDADR_STOP
+
+ - pxa_camera_check_link_miss() is called
+ This checks if the DMA is finished and a buffer is still on the
+ pcdev->capture list. If that's the case, the capture will be restarted,
+ and Videobuffer3 is scheduled on DMA chain.
+ - the DMA irq handler finishes
+
+ Note: if DMA stops just after pxa_camera_check_link_miss() reads DDADR()
+ value, we have the guarantee that the DMA irq handler will be called back
+ when the DMA will finish the buffer, and pxa_camera_check_link_miss() will
+ be called again, to reschedule Videobuffer3.
+
+--
+Author: Robert Jarzmik <robert.jarzmik@free.fr>
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index a31177390e55..854808b67fae 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -90,7 +90,7 @@ 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. It is rare for dev to be NULL, but it happens
+usb_interface or platform_device. It is rare for dev to be NULL, but it happens
with ISA devices or when one device creates multiple PCI devices, thus making
it impossible to associate v4l2_dev with a particular parent.
@@ -351,17 +351,6 @@ And this to go from an i2c_client to a v4l2_subdev struct:
struct v4l2_subdev *sd = i2c_get_clientdata(client);
-Finally you need to make a command function to make driver->command()
-call the right subdev_ops functions:
-
-static int subdev_command(struct i2c_client *client, unsigned cmd, void *arg)
-{
- return v4l2_subdev_command(i2c_get_clientdata(client), cmd, arg);
-}
-
-If driver->command is never used then you can leave this out. Eventually the
-driver->command usage should be removed from v4l.
-
Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
is called. This will unregister the sub-device from the bridge driver. It is
safe to call this even if the sub-device was never registered.
@@ -375,14 +364,12 @@ from the remove() callback ensures that this is always done correctly.
The bridge driver also has some helper functions it can use:
-struct v4l2_subdev *sd = v4l2_i2c_new_subdev(adapter, "module_foo", "chipid", 0x36);
+struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
+ "module_foo", "chipid", 0x36);
This loads the given module (can be NULL if no module needs to be loaded) and
calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
-If all goes well, then it registers the subdev with the v4l2_device. It gets
-the v4l2_device by calling i2c_get_adapdata(adapter), so you should make sure
-to call i2c_set_adapdata(adapter, v4l2_device) when you setup the i2c_adapter
-in your driver.
+If all goes well, then it registers the subdev with the v4l2_device.
You can also use v4l2_i2c_new_probed_subdev() which is very similar to
v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses