RivaTV README
=============

This README applies to RivaTV v0.8.6

What's new
----------
The new release comes with some minor bug fixes and improvements
including up-to-date compatibility with latest 2.6.x kernels, experimental
code regarding detection of physical and virtual resolutions (to
get rid of v4l-conf for overlay) and also some more cards are now
detected automatically.


The Future
----------
The 0.9 cycle has begun. While 0.8.x is still alpha, 0.9 will become beta
software. We hope you will be just as supportive for the next releases,
as you've all been in the past. We couldn't have done it without you!


Supported cards
---------------
If your card has:
- NV03, NV04, NV10, NV20 or NV30 architecture
  (Riva128, RivaTNT, RivaTNT2, GF256, GF2, GF2MX, GF3, GF4(8x), GF4MX(8x), GFX)
- saa7111a, saa7113h, saa7108e, saa7114h or vpx32xx video decoder chip
chances are you can watch video today!
Tuners (e.g. Asus TV-Box and Asus V7100 Deluxe Combo) are also supported!
Check the CARDLIST file to see whether your card is known to us.

Preliminary support is available for:
- tw98, saa7174hl, saa7133hl and saa7134hl video decoders
Your milage may vary.


Quick start
-----------

Start X, then:

 $ ./configure
 $ make
 # make install
 # modprobe rivatv
 $ xawtv


Upgrading from older versions
-----------------------------
If you have an older release still installed, we suggest that you uninstall
it, or remove the modules manually. This will prevent weirdness and improve
your chances of success.


Install
-------
You need a 2.4 or 2.5/2.6 kernel. Older kernels are not supported.
Make sure you have enabled (either built-in or with modules) the following
features in your linux kernel:
* I2C core
* I2C bit banging algorithm
* video4linux

You don't have to, but will want to build these as well:
* kernel module loader
* /proc interface

When you built modules, make sure you have them loaded.

First step of the installation process is to run

   $ ./configure
   
This will check if your current setup has or could have trouble running rivatv.
If so, it reports the problem and suggests a solution.

You may want to change some configuration variables (e.g. KERNEL, if building 
for a different kernel than the running one) in the Makefile. Then, in the 
rivatv directory do:

   $ make

This should create the modules rivatv.o, and five decoder modules.
If something goes wrong during the building process, try to find out what
is wrong. If you can fix it, great, let us know. If not, let us know
as well.
After this, you are ready to

   # make install

This puts the modules in your /lib/modules tree.
Note that you don't have to do this! It's just more comfortable if you do.
If you read this too late, there is always the possibility to do

   # make uninstall

which undoes the make install step.


Loading
-------

If you did make install:

If your board is known to us, and consequently to RivaTV, all you have to 
do is:

   # modprobe rivatv

RivaTV will detect your board and load the decoder driver for it. You can
check whether it loaded the decoder by looking at your syslog
(/var/log/messages or /var/log/syslog) or looking in /proc/driver/rivatv.
Your board's name will be there, along with the module(s) it has loaded.

If your board is not (completely) known to us, rivatv will say so in the
syslog and /proc/driver/rivatv will reflect it as well. In your syslog you 
will find a line with PCI identifiers. Send those, along with info about your 
card to <rivatv-devel@lists.sourceforge.net>. More info is on the RivaTV 
homepage <http://rivatv.sourceforge.net>. Besides this, rivatv loads the 
driver for the most common decoder chip, the Philips saa7108e. If you happen 
to have that decoder, rivatv will work out of the box. We would still like 
to know the details mentioned above, to provide even better support for the 
card. If you do not have that decoder, you need to determine your decoder 
chip and load its driver manually. When you know what decoder chip you have, 
read 'if you did not make install'.


If you did not make install:

Load your dependencies (see Install).
Determine your decoder chip and load its driver module:
(for saa7114h load saa7108e.o)

  # insmod saa7111a.o        OR
  # insmod saa7113h.o        OR
  # insmod saa7108e.o        OR
  # insmod vpx32xx.o         OR
  # insmod tw98.o            OR
  # insmod saa7174hl.o

If you have a tuner (e.g. V7100 Deluxe Combo or TV-Box), load according 
modules:

  # insmod tuner.o
  # insmod tvaudio.o
  # insmod tvmixer.o

After this, load rivatv:

  # insmod rivatv.o

RivaTV should now be loaded. Check to see if it did in your syslog
(/var/log/message or /var/log/syslog). If you think something's wrong,
contact us. For 2.6.x kernel it is necessary to insmod/modprobe the
appropriate .ko files instead of the .o modules.


Notes on X and drivers
----------------------
It is one of our goals to make it possible to load rivatv before ever
starting X, thereby before the loading of a video driver for a nVidia card.
Unfortunately, this is difficult, because RivaTV and the nVidia driver are
driving the same resource. That's why RivaTV works best if you load it after
starting X.

Basically there are three different X drivers available for nVidia hardware.
Two of these (the 'nv' and 'vesa' drivers) are included in the XFree86 project
and come along with the standard X installation. The last but not least one is
the closed-source binary X driver by nVidia themselves.  It contains the X 
driver (including GL and GLX modules) and a kernel module which need to be 
loaded before X can start. The driver is referred to as the 'nvidia' driver.
You can switch between these drivers by editing your XF86Config file which
resides in different locations on various GNU/Linux distributions. In this
file should be a line like:

	Driver		"nvidia"

You can switch the X driver replacing "nvidia" by "nv" or "vesa".

Module parameters
-----------------
The rivatv kernel module as well as the video decoder modules do have
parameters which slightly adjust their runtime behaviour. The following list
applies to the rivatv module. The "debug" parameter is also available for 
each of the video decoder modules.

capbuffers: 1-32
  Number of capture buffers (default = 4). This parameter tells the driver 
  how many buffers the driver uses for mmap'ed capture.

autoload: 0/1
  Turn decoder chip driver autoloading off (= 0). It is on by default.

card: 1-X
  Specify card model, see CARDLIST file for a list. This parameter forces
  the driver to use card specific settings if it cannot detect your hardware
  correctly.

debug: 0-2
  Debug level: 0 = silent, 1 = verbose, 2 = very verbose (default = 1).

tvbox: 0-7
  Indicate usage of the TV-Box (0 = off).
    1 = Philips FI1216 and compatibles
    2 = Philips FI1236, FM1236 and compatibles
    3 = Philips FI1236 MK2
    4 = Philips FI1256 and compatibles
    5 = Philips FQ1216ME
    6 = Philips FI1216MF, FM1216MF, FR1216MF
    7 = Philips FI1246 and compatibles
  It is off by default. The driver cannot detect the TV-Box properly. 
  That is why you need to determine the kind of TV-Box you want to use.

dma: 0/1
  Indicate usage of DMA transfers (1 = on). It is off (= 0) by default. This
  feature is very young and still experimental. It speeds up the mmap'ed
  capture. Currently it works for NV4 and NV10 without X and/or the
  open source nv X driver only.

agp: 0/1
  Indicate usage of AGP (1 = on) (Off by default). This parameter enables
  or disables AGP checks. This option is only available if you have compiled
  RivaTV with --enable-agp.

mtrr: 0/1
  Turn off (= 0) MTRR usage (default = 1).  With this parameter switched on
  the driver is setting up a MTRR region for the framebuffer.  It may speed
  up the overall performance.

mmx: 0/1
  Indicate usage of MMX code (1 = on) (On by default). This parameter enables
  or disables MMX code in colour conversion routines (much faster) if the 
  processor has MMX registers.

conversion: 0/1
  Enable colour conversion code (1 = on) (Off by default).  With this
  parameter disabled V4L application will need to support the native 
  format(s) of the driver. This option is only available if you have
  compiled RivaTV with --enable-software-conversion.

Usage
-----
You should now have a(n extra) working video device (e.g. /dev/video0).
Use a video4linux application to try RivaTV. We recommend xawtv.

Configurable features
---------------------
RivaTV can be built with some extra functions. You can enable these
features by entering appropriate options for configure. See
./configure --help for more information on how to do that. The extra
features are:

enable-agp:
       Enable some experimental AGP code. Only detection of AGP is featured,
       so you can do without this. It is disabled by default because not
       everyone has AGP.

enable-software-conversion:
       RivaTV versions before 0.8.3 came with software colour conversions
       built in. This is a bad practice for drivers, see:
       <http://bytesex.org/v4l/>. Because nVidia's native format (UYVY) is
       not wide-spread supported by V4L applications, having no colour
       conversion would render RivaTV useless in a significant number of
       cases.  Using this feature, you can compile RivaTV with software
       conversion - at the cost of speed (also depending on the format
       used).  Note that this is not enough; you need to enable the
       conversion parameter as well.
       Bottom line is: harass the authors of your favorite V4L application
       to start supporting RivaTV's native format! Get the most out of
       your PC!

Feedback
--------
If you are having difficulties, or want more information, PLEASE read the
RivaTV testers guide and FAQ first, before mailing to the list. It will save
you a lot of time. The guide and FAQ can be found on the RivaTV homepage as
well. Send questions and/or feedback to <rivatv-devel@lists.sourceforge.net>
according to the guidelines stated on the homepage.


(c) 2005 RivaTV Team
