Driver for Iomega Buz, version 0.0.3
------ --- ------ ---  ------- - - -

This is still very flaky software, and will probably screw up your system.
No warranties of its fitness are expressed or implied.  What passes as
testing was done on a dual Pentium II machine with 128MB memory and an
ATI Mach64 RageII+DVD video card with 8MB.

This is the last release by me that uses the original V4L API. Future
development will target the V4L2 interface instead.

Installing
----------

Read the file called TODO.  Note its long list of limitations.

To install this software, extract it into a suitable directory.
Examine the makefile and change anything you don't like.  Type "make".
Back up your file systems.  As root, type "./update".  You might want
to look at the file "update" first and tailor it to your needs.

Run your X server in 16 bit mode for watching TV.  32 bit mode tends
not to work on my system.

The buz.o module takes a few command-line arguments.

	vidmem=n	- sets address of frame buffer to n<<20
	triton=1	- use Triton workaround for DMA
	natoma=1	- use contiguous frame buffers (doesn't work!)
	nbufs=n		- use 'n' buffers instead of VIDEO_MAX_FRAME
	input=n		- select input 'n' initially (for debugging)
	gpio=n		- initialize GPIO lines to 'n'

Applications
------------

There are no applications for it yet.  I just hacked up XTV to work.
(The file "XTV-diff" is a set of diffs against bttv-0.5.8's version.)
There are VIDEO_MAX_FRAME (32) buffers of BUZ_MAX_FBUF (200K) bytes each.
The VIDIOCGMBUF ioctl will allow an application to discover this fact
without having to resort to #include files.

The file "mrecord.c" is a streaming capture hack. It writes a stream of
frames to a single file. Each frame is prefixed by its length, sequence
number, and timestamp so "mplay.c" can separate them, but as yet the
playback support in the driver doesn't work anyway.

API
---

This uses the V4L interface as of kernel release 2.1.125, and in
fact has not been tested on many other versions.  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
V4L2 API when it has stabilized more since V4L really only seems to
fit the BTTV-type cards.

	1) The VIDIOCSYNC call returns the number of bytes
	   of JPEG data in the buffer if successful.

	2) In the struct video_mmap passed to VIDIOCMCAPTURE, the
	   format field is ignored.

	3) The VIDIOCSWIN call stops streaming capture. The next
	   VIDIOCMCAPTURE call will set things up for the capture.
	   On subsequent VIDIOMCAPTURE calls the height and width
	   fields of the struct video_mmap are ignored.  (The V4L2
	   API calls to explicitly start and stop streaming capture
	   and to specify compression options will come in handy.)

	4) There are three Buz-specific ioctls so far. BUZIOCSYNC is
	   an alternative to VIDIOCSYNC that returns frame sequence
	   number and timestamp information as well as length.
	   BUZIOCSCODEC allows you to set the compression quality
	   and the text of the comment marker embedded in each field.
	   BUZIOCMPLAY is supposed to allow frames to be fed to the
	   motion playback mechanism which at present just locks up
	   my machine!
