This document wants to give a rough overview over the modules of the
source, so you can get an idea where to look if you want to make
changes.

How to produce TV-Out
~~~~~~~~~~~~~~~~~~~~~

The NVidia-card contains access to several I2C-Busses. These are slow
two-line busses used to communicate with peripherie. The TV-chip
is connected to one of those busses.

To access this chip, the program has to memory map the PCI-I/O-range
of the card into its address space. Then it can read and write
the card's registers, control the I2C-Bus and setup the registers
of the TV-chip. Finally, it has to change a few registers of the
card to enable or disable tv-out.

That's all there is to it.

Structure of the program
~~~~~~~~~~~~~~~~~~~~~~~~

There are three "layers" in nvtv: The "frontend" layer, where the user
interacts with the system, the "backend" layer, that encapsulates
different forms of access, and the "hardware" layer, where the video
hardware is accessed. The backend layer itself is split into to parts,
a card independent access part, and a card dependent part.

  
     Frontend           Backend (Access)    Backend (Card)       Hardware

                               ............+-------------+    +-------------+ 
                               .           | NVidia      |....| NVidia      | 
                       +---------------+ ..+-------------+    +-------------+ 
                       |  Direct/nvdev | .                                    
                    ...| (/dev/nv*)    | . +-------------+    +-------------+ 
 +---------------+  .  +---------------+ ..| Intel I810  |....| Intel I810  | 
 |  Main         |...  |  Direct/root  | . +-------------+    +-------------+ 
 | (Commandline) |  ...| (/dev/mem)    |..                                    
 +---------------+  .  +---------------+ . +-------------+    +-------------+ 
         |          .                    ..| 3DFX Voodoo |....| 3DFX Voodoo | 
         V          .                      +-------------+    +-------------+ 
 +----------------  .                                        
 |      GUI      |  .  +-----------------+---------------+    
 |     (GTK)     |.....|  Null           |               |   
 +---------------+  .  | (for testing)   |               |   
         |          .  +-----------------+---------------+   
         V          .                                        
 +---------------+  .  +-----------------+---------------+                   
 |  4 GUI parts  |  ...|  Client         |               |                   
 | (bt,cx,ch,ph) |  .  | (named pipe)    |               |                   
 +---------------+  .  +-----------------+---------------+                   
                    .                                        
 +----------------  .  +-----------------+---------------+    +-----------+ 
 |     Server    |.....|  XVidMode       |               |....| X Server  | 
 |  (named pipe) |     | (planned)       |               |    |           | 
 +---------------+     +-----------------+---------------+    +-----------+ 


There are four different backends at the moment. If the program is run
with root permissions, it can use /dev/mem to access the card.
Alternatively, even without root permissions, it can use the /dev/nv*
devices of the closed source NVidia kernel module for the access. 
However, this only works when the NVidia X driver is using the kernel
module, due to a bug in the kernel module. Both these backends are in
'back_direct.c' The third backend in 'back_none.c' is an empty 'stub'
backend, that however contains all four possible tv chips, used for
testing or calculating. The fourth backend in 'back_client.c' uses the
server, if it is available. For communication with each other, both
server and client use 'pipe.c'.

One of the front end is the server 'server.c', which is a standalone
program that just communicates with clients and passes the commands on
to one of the direct backends or the null backend. This frontend makes
up 'nvtvd'. The other two frontends are combined in 'nvtv'.  The
commandline interface is completely in 'main.c'. If nvtv is built with
GTK, the gui part is also available. The main gui routines are in
'gui.c' together with common subroutines. The encoder specific GUI for
the Brooktree, the Conexant, the Chrontel and the Philips encoder are
in 'gui_bt.c', 'gui_cx.c', 'gui_ch.c' and 'gui_ph.c', respectively. 
These are used depending on the tv chip detected/selected.

The last two backends use 'actions.c', which contains some X related
actions (changing the video mode, centering, selecting a window).

Besides these three layers, there is the data for the TV modes of all
four encoder types in 'data_bt.c', 'data_cx.c', 'data_ph.c' and
'data_ch.c'. This is where you can include your own modes, if you
want. For the Brooktree chip, the mode calculation for arbitrary
overscan compensation values takes place in 'calc_bt.c'.


The hardware layer is seperated because it is eventually meant to
become a part of the XFree server. All the files belonging to it start
with 'tv_', except the X I2C Bus routines in 'xf86i2c.c', which are
copied verbatim from the X server source. It has the following
structure:


   Hardware            TV Encoder               I2C Bus

                     
                     +---------------+ 
                  ...| Brooktree     |...
		  .  +---------------+  .
 		  .                     .
 +-------------+  .  +---------------+  .    +------------+
 | NVidia      |.....| Conexant      |...    | X I2C Bus  |
 +-------------+  .  +---------------+  .    |  routines  |
 		  .                     .    +------------+ 
 +-------------+  .  +---------------+  .          ^
 | Intel I810  |.....| Chrontel      |...          |
 +-------------+  .  +---------------+  .    +------------+
 		  .                     .....| I2C Bus    |
 +-------------+  .  +---------------+  .    |   access   |
 | 3DFX Voodoo |.....| Philips       |...    +------------+
 +-------------+  .  +---------------+             ^
 		  .                                |
 		  .  +---------------+    +-------------------+ 
 		  ...| Null          | 	  | Common            | 
 		  .  | (for testing) | 	  | (Detection, etc.) | 
                  .  +---------------+ 	  +-------------------+ 
 		  .                                .
		  ..................................

		     
Finally, there is 'libc_wrapper.c', which contains a few wrapper
routines from the XFree server, and 'xf86PciInfo.h', which is a 
slightly extended copy of the XFree server PCI id information.