1 files changed, 159 insertions, 0 deletions

diff --git a/Documentation/video4linux/zr36120.txt b/Documentation/video4linux/zr36120.txt
new file mode 100644
index 000000000000..4af6c52595eb
--- /dev/null
+++ b/Documentation/video4linux/zr36120.txt
@@ -0,0 +1,159 @@
+Driver for Trust Computer Products Framegrabber, version 0.6.1
+------ --- ----- -------- -------- ------------  ------- - - -
+
+- ZORAN ------------------------------------------------------
+ Author: Pauline Middelink <middelin@polyware.nl> 
+   Date: 18 September 1999
+Version: 0.6.1
+
+- Description ------------------------------------------------
+
+Video4Linux compatible driver for an unknown brand framegrabber
+(Sold in the Netherlands by TRUST Computer Products) and various
+other zoran zr36120 based framegrabbers.
+
+The card contains a ZR36120 Multimedia PCI Interface and a Philips
+SAA7110 Onechip Frontend videodecoder. There is also an DSP of
+which I have forgotten the number, since i will never get that thing
+to work without specs from the vendor itself.
+
+The SAA711x are capable of processing 6 different video inputs,
+CVBS1..6 and Y1+C1, Y2+C2, Y3+C3. All in 50/60Hz, NTSC, PAL or
+SECAM and delivering a YUV datastream.  On my card the input
+'CVBS-0' corresponds to channel CVBS2 and 'S-Video' to Y2+C2.
+
+I have some reports of other cards working with the mentioned
+chip sets. For a list of other working cards please have a look
+at the cards named in the tvcards struct in the beginning of
+zr36120.c
+
+After some testing, I discovered that the carddesigner messed up
+on the I2C interface. The Zoran chip includes 2 lines SDA and SCL
+which (s)he connected reversely. So we have to clock on the SDA
+and r/w data on the SCL pin. Life is fun... Each cardtype now has
+a bit which signifies if you have a card with the same deficiency.
+
+Oh, for the completeness of this story I must mention that my
+card delivers the VSYNC pulse of the SAA chip to GIRQ1, not
+GIRQ0 as some other cards have. This is also incorporated in
+the driver be clearing/setting the 'useirq1' bit in the tvcard
+description.
+
+Another problems of continuous capturing data with a Zoran chip
+is something nasty inside the chip. It effectively halves the
+fps we ought to get... Here is the scenario: capturing frames
+to memory is done in the so-called snapshot mode. In this mode
+the Zoran stops after capturing a frame worth of data and wait
+till the application set GRAB bit to indicate readiness for the
+next frame. After detecting a set bit, the chip neatly waits
+till the start of a frame, captures it and it goes back to off.
+Smart ppl will notice the problem here. Its the waiting on the
+_next_ frame each time we set the GRAB bit... Oh well, 12,5 fps
+is still plenty fast for me.
+-- update 28/7/1999 --
+Don't believe a word I just said... Proof is the output
+of `streamer -t 300 -r 25 -f avi15 -o /dev/null`
+        ++--+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+- 25/25
+        +-s+-+-+-+-+-+-+-+-+-+-+-+-+-s+-+-+-+-+-+-+-+-+-+-+-
+        syncer: done
+        writer: done
+(note the /dev/null is prudent here, my system is not able to
+ grab /and/ write 25 fps to a file... gifts welcome :) )
+The technical reasoning follows: The zoran completed the last
+frame, the VSYNC goes low, and GRAB is cleared. The interrupt
+routine starts to work since its VSYNC driven, and again
+activates the GRAB bit. A few ms later the VSYNC (re-)rises and
+the zoran starts to work on a new and freshly broadcasted frame....
+
+For pointers I used the specs of both chips. Below are the URLs:
+        http://www.zoran.com/ftp/download/devices/pci/ZR36120/36120data.pdf
+        http://www-us.semiconductor.philips.com/acrobat/datasheets/SAA_7110_A_1.pdf
+
+The documentation has very little on absolute numbers or timings
+needed for the various modes/resolutions, but there are other
+programs you can borrow those from.
+
+------ Install --------------------------------------------
+Read the file called TODO.  Note its long list of limitations.
+
+Build a kernel with VIDEO4LINUX enabled. Activate the
+BT848 driver; we need this because we have need for the
+other modules (i2c and videodev) it enables.
+
+To install this software, extract it into a suitable directory.
+Examine the makefile and change anything you don't like.  Type "make".
+
+After making the modules check if you have the much needed
+/dev/video devices. If not, execute the following 4 lines:
+        mknod /dev/video c 81 0
+        mknod /dev/video1 c 81 1
+        mknod /dev/video2 c 81 2
+        mknod /dev/video3 c 81 3
+        mknod /dev/video4 c 81 4
+
+After making/checking the devices do:
+        modprobe i2c
+        modprobe videodev
+        modprobe saa7110        (optional)
+        modprobe saa7111        (optional)
+        modprobe tuner          (optional)
+        insmod zoran cardtype=<n>
+
+<n> is the cardtype of the card you have. The cardnumber can
+be found in the source of zr36120. Look for tvcards. If your
+card is not there, please try if any other card gives some
+response, and mail me if you got a working tvcard addition. 
+
+PS. <TVCard editors behold!)
+    Dont forget to set video_input to the number of inputs
+    you defined in the video_mux part of the tvcard definition.
+    Its a common error to add a channel but not incrementing
+    video_input and getting angry with me/v4l/linux/linus :(
+
+You are now ready to test the framegrabber with your favorite
+video4linux compatible tool
+
+------ Application ----------------------------------------
+
+This device works with all Video4Linux compatible applications,
+given the limitations in the TODO file.
+
+------ API ------------------------------------------------
+
+This uses the V4L interface as of kernel release 2.1.116, and in
+fact has not been tested on any lower version.  There are a couple
+of minor differences due to the fact that the amount of data returned
+with each frame varies, and no doubt there are discrepancies due to my
+misunderstanding of the API.  I intend to convert this driver to the
+new V4L2 API when it has stabilized more.
+
+------ Current state --------------------------------------
+
+The driver is capable of overlaying a video image in screen, and
+even capable of grabbing frames. It uses the BIGPHYSAREA patch
+to allocate lots of large memory blocks when tis patch is
+found in the kernel, but it doesn't need it.
+The consequence is that, when loading the driver as a module,
+the module may tell you it's out of memory, but 'free' says
+otherwise. The reason is simple; the modules wants its memory
+contiguous, not fragmented, and after a long uptime there
+probably isn't a fragment of memory large enough...
+
+The driver uses a double buffering scheme, which should really
+be an n-way buffer, depending on the size of allocated framebuffer
+and the requested grab-size/format.
+This current version also fixes a dead-lock situation during irq
+time, which really, really froze my system... :)
+
+Good luck.
+  Pauline