**************************************************************************
****           Fast Multimedia AV Master driver for GNU/Linux         ****
**************************************************************************
*   Copyright (C) 1999,2000 Michael Stickel                              *
*   Copyright (C) 2004 Luca Bonissi <lucabon@interfree.it>               *
*                                                                        *
*   Released under the GPL licence (version 2 or later)                  *
**************************************************************************

1. Introduction - History
2. What was done, what is to do
3. Test hardware
4. Operating system and software
5. Installation
6. Bugs
7. Help!
8. Licence
9. Contacts
10. Thanksgivings

1. INTRODUCTION - HISTORY
I'm trying to do a driver for the AVMaster that runs with the Linux kernel.
Fast Multimedia (that became Dazzle and now it is Pinnacle) had never want 
to give any documentation about this video acquisition board.
Michel Stickel (I'd like to thank him for the support that he gives me) 
wrote in 2000 an alpha driver for AVMaster, but it was limited to "play" 
with I2C bus, and therefore with only video decoder/encoder. Since 2000 the 
driver has no more evolution.
So I take the unified driver for the Zoran PCI chipset 36057 and I do a 
fork for the AVMaster. This choise was based on two aspects:

   1. The driver includes some modules that I can reuse (videocodec,
      saa7110, saa7185/87, zr36016/15, zr36050)
   2. The driver has support for both V4L and V4L2.

I substitute (some) parts of the original PCI chipset zr36057 with the ones 
of the saa7145 (AVMaster PCI Bridge). But it is more complicated...

2. WHAT WAS DONE, WHAT IS TO DO
At today (Sep 12th, 2004) the only "quite bit" working part is the video 
overlay. The "quite bit" is mandatory because if you want to see something 
you have to start Windows and then reset the PC (without shutdown) and 
restart GNU/Linux. This because (I think) at boot time the video bus from 
FPGA is enabled, and this creates a conflict with the input video chipset 
SAA7110. I did not test the video output  (SAA7187), but I think it is 
working.
The big and hard part is the JPEG encoding/decoding and the audio 
management (see documentation for more details). At the moment you can use 
the AVMaster only like a TV...

3. TEST HARDWARE
My testing system is:

    * Processor: PII 350Mhz
    * Motherboard: Asus P2B-F (chipset Intel 440BX)
    * Video card: ATI 3D Rage Pro AGP 2X
    * Other PCI/ISA cards: Network Realtek 8139, Audio SBLive, Audio 
      SB64Gold

I don't think that other information about the testing system are necessary 
(but if you want to know somethinkg else, you can contact me).

4. OPERATING SYSTEM AND SOFTWARE
The used operating system is GNU/Linux x86, Slackware 9.1 distribution. The 
driver was tested with the Linux kernel 2.4.24 (V4L) e 2.6.6 (V4L2).
The used software for overlay test is xawtv. In order to get it working, I 
had to remove the line Option "omit xfree86-dga" from /etc/X11/XF86Config 
(but I think this is a specific of Slackware).
Unfortunately lavvideo from mjpeg-tools does not work: it seems that it 
cannot recover the necessary information from X, so the AVMaster driver 
cannot do the overlay.
The tested video resolution are: RGB15, RGB16, RGB32. I could not test 
RGB24 and YUV422, the first because my video card does not support it, the 
latter because I doesn't have the software for YUV422 overlay.

5. INSTALLATION
You must have the kernel sources installed and you have to configure your 
kernel at least with the following options:

    * For kernel 2.4.x:
          o General setup ---> [*] PCI support
          o Character devices ---> I2C support ---> <M> I2C support
          o Multimedia devices ---> <M> Video For Linux
    * For kernel 2.6.x:
          o Bus options (PCI, PCMCIA, EISA, MCA, ISA) ---> [*] PCI support
          o Devices drivers ---> I2C support --> <M> I2C support
          o Multimedia devices ---> <M> Video For Linux

These options are usually enabled by default in the most common 
distributions.
Then you have to unpack the tar file and compile it:

	# tar xzvf avmaster-0.0.1.tar.gz
	# cd avmaster-0.0.1
	# make

Then you have to switch to root user and install the modules:

	# su
	Password:
	# make install

If you have PCI hotplug enabled and you distribution have the correct 
scripts (Slackware has them), the module avmaster and the related ones 
(saa7110, saa7187, zr36015, zr36050, videodev, videocodec, i2c-core) are 
loaded automatically.
If you want to install them manually without rebooting, simply type (from root):

	# modprobe avmaster

Then you can start (from normal user) one TV application (I use xawtv) and 
you can see the video overlay (after rebooting from Windows).

6. BUGS
I think that the driver has many bugs!! But from my tests I found only one 
bug that I was not able to fix: if you quickly go from full-screen to 
window mode, thw whole operating system hangs. Normally the overlay is 
still working, but I don't think you want to use to PC only like a TV....
Before do any test, type the sync command; in this way you don't lost any 
data (I lost 2 source file of the driver...). If it is possible, use a 
journaled file system, so, in the case you forgot to do sync, at least the 
file system keeps its integrity. With tune2fs you can upgrade in a simple 
way from ext2 (not journaled) to ext3 (journaled).

7. HELP!
Unfortunately there is an obstacle hard to break: the AVMaster has two 
programmable chipsets (a FPGA and a DSP, see documentation), and nobody 
(except FAST) knows how they was programmed. I'm trying to get the 
necessary informations by reverse engineering of the Windows drivers. If 
someone wants to help me or has some other idea, he/she is welcome.

8. LICENCE
This program is free software; you can redistribute it and/or modify it 
under the terms of the GNU General Public Licence (Licenza Pubblica 
Generica) as published by the Free Software Foundation; either version 2 of 
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for 
more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

9. CONTACTS
I am Luca Bonissi, a computer programmer, a lover of GNU/Linux (and the 
free software in general) and of audio/video tools. For anything about 
AVMaster, feel free to call me <lucabon@interfree.it>

10. THANKSGIVINGS
I'd like to give many many thanks to Michael Stickel. Without him the 
development of this driver could not be started. He giove me the datasheet 
of the main chipset  SAA7145 and, aboveall, the "hope" to make working the 
AVMaster under GNU/Linux.
My thanks are aldo for the unified drver Zoran team, the mjpeg-tools team, 
Alessandro Rubini for his Linux Device Driver book and the ones who have 
wrote some free software that I used.

