Documentation/video4linux/zr36120.txt - kernel/msm - Gitiles

 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
	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