root/lm-sensors/branches/lm-sensors-2.10/doc/chips/bt869

Kernel driver `bt869.o'
======================

Status: 'Beta' and needs further development and testing

Supported chips: 
  * Brooktree BT869 Video Modulator chips
    Prefix: 'bt869'
    Addresses scanned: I2C 0x44 - 0x45
    Datasheet: Publicly available at the brooktree web site
    (www.brooktree.com)

Author: Frodo Looijaard <frodol@dds.nl>, Philip Edelbrock
        <phil@netroedge.com>, Ralph Metzler <rjkm@thp.uni-koeln.de>
        Steve Davies <steve@daviesfam.org> added the 720x576 and
        720x480 support, and the svideo configuration.

Main Contact: Philip Edelbrock <phil@netroedge.com>

Module Parameters
-----------------
* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_bt869: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to contain
  a `bt869' chip
* ignore: short array (min = 1, max = 48)
  List of adapter,address pairs not to scan
* ignore_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples not to scan
* probe: short array (min = 1, max = 48)
  List of adapter,address pairs to scan additionally
* probe_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples to scan additionally


Description
-----------

This driver provides some access to the Brooktree bt869 found on some
video cards (like the 'Voodoo3 3000').  Typically, the output can be
either an s-video connection or composite video.  Resolutions
supported using the chip's built in configurations are 640x480 or
800x600.  In addition, a 720x576 PAL mode and a 720x480 NTSC mode,
both without overscan compensation, are supported - a convenient
configuration for video playback.

Other possible implementations may allow for double resolutions with some
decimations (e.g., a monitor running at 1280x960 but the TV out getting every
other pixel for 640x480).


Driver Features
---------------
Standards: (US) NTSC or PAL
Resolutions: 640x480, 800x600, 720x576 (PAL only), 720x480 (NTSC only)
Depths: 16, 24 or 32 bits
Colorbars: Switch on the built-in color bar generator. (FYI- using a blue
filter, you should see only alternating bright stripes of equal brightness.
Adjust your TV's color and saturation if this isn't the case.)
SVideo: composite or s-video output.  Also, theoretically, RGB output, though
this isn't tested and will require that your card presents all three DAC outputs
(the 3dfx Voodoo3 doesn't)

In your XF86Config file, you should have these entries for NTSC output:

ModeLine "640x480NTSC"  28.195793   640  656  658  784   480  520  525  600
ModeLine "720x480NTSC"  27.5        720  744  800  872   480  483  485  525
ModeLine "800x600NTSC"  38.769241   800  812  814  880   600  646  649  735

or for PAL

ModeLine "640x480PAL"   29.50       640  675  678  944   480  530  535  625
ModeLine "720x576PAL"   27.50       720  744  800  880   576  581  583  625
ModeLine "800x600PAL"   36.00       800  818  820  960   600  653  655  750

Also, don't forget to add these modes to the resolutions list in the
'screen' sections of XF86Config.  You can change modes on the fly in X by
pressing (usually) ctrl-alt-+ or ctrl-alt-(minus)  with + and - being the
keys on your numeric 10-key pad.

BTW- My monitor doesn't like these entries very much, and as I've read:
don't run your monitor out of spec or else it will burst into fire.  So,
having the monitor turned on while in any of these modes is at your own
risk.  (I've never heard of a monitor breaking from this, but it seems to
be fashionable to warn about it.)


Chip Features
-------------
The chip is very flexible and customizable for many standards.  Right
now the driver sticks with the chip's built in NTSC and PAL standards,
with the addition of the 720x576PAL and 720x480NTSC modes.  It also
does some other wacky stuff like closed-captioning, Macro-vision
copy-protection, and other things.  Check out the datasheet for more
info.


Issues
------
The depth register doesn't seem to do much?  If you have troubles or
aren't sure the output is working, turn the color-bars on.  If they display
OK, then the chip is syncing correctly.  The next thing to try is the depth
setting.  Lastly, turning off your computer and back on with your TV
connected but you monitor not, may force the video card to configure and
use the BT869 as your primary output device (all bets are off once X is
started).  Let me know if you have problems which you can't figure out 
(phil@netroedge.com).

--------------------------------

On May 3rd, 2001 (My birthday, as it happens to be :') Tomi Ollila sent me 
a how-to from a user's perspective on using the BT869 with a 3Dfx card.
It should also provide insight for other video card users who have a
BT869 on board.  Here is his document:


How-To
------


This text describes my successful attempt to eventually get the TV-Out
feature of 3DFX Voodoo 3 3000 (PAL) working in a Linux environment.
I've successfully configured the 800x600 mode -- And currently I am
not interested in 640x480 -- hardware scaling rules in all cases
I need the tv-out. My monitor works much less worse w/ 800x600PAL...

All the information is based on my best knowledge but there might be
some mistakes. In any case, THE ENTIRE RISK OF USING THIS INFORMATION
IS WITH YOU, AND NO ONE ELSE IS LIABLE OF ANY PROBLEMS ENCOUNTERED.
Please fix any mistakes, inaccuracies, writing errors, etc. you
notice in this document.

I was about to write briefly, but sorry due to limited resources
I did not have time to write briefly (too much thinking ;). 
Well, browse through the text and skip all irrelevant parts
to proceed...

Tomi Ollila <too@iki.fi>


The first time I got the the tv-out working I was working w/ Linux kernel
2.4.3. Now I am redoing the work w/ Linux 2.4.4 and recording the steps
in this document. Description of my system and software used is as follows:

RedHat 7.0 linux distribution (probably any distribution will do, since
all of the needed software is compiled from packages that are not RH-pagkaged)
(maybe if anything is important, are modutils-2.3.14-3 and kernel-headers-2.4.0-0.26)

XFree-4.0.3. I don't see any reason anyone uses any older. HW acceleration
of Voodoo3 3000 works out of the box with this. Also Windowed!!!

lm_sensors-2.5.5: Get this or newer. I have not used any older.

i2c-2.5.5: Probably 2.4.x -kernel distributions has recent enough version
of i2c. Since I also have IOmega BUZ and it's (working) versions require
i2c-old, I cannot use the one's kernel provided. Since I cannot say anything
about not using this i2c as separate package I suggest you do the same
and compile this also.

I have used kgcc that comes in RedHat 7.0 -distribution to compile all
stuff. Probably all other recent gcc -compilers will produce good results
also: kgcc -v outputs:
Reading specs from /usr/lib/gcc-lib/i386-glibc21-linux/egcs-2.91.66/specs
gcc version egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)

--

1) The work starts w/ kernel compilation (or skip to step 2, I quess it will
   work w/ any recent 2.2 and 2.4 -kernels)
 
   # run make config, make menuconfig or make xconfig (I suggest 'xconfig')

   For sure you need kernel module support and /proc -filesystem support
   (XXX add more absolute requirements)

   Now I cannot say for sure, if following things needs to be compiled 
   at kernel compilation time or does i2c-2.5.5 bring all these:
        character devices->i2c support->i2c support
        character devices->i2c support->i2c bit-banging interfaces (*)
        character devices->i2c support->i2c devices     (**)
        character devices->/dev/agpart support
        character devices->Direct Rendering Manager (XFree86 DRI support) (+)
        character devices->3dfx banshee/Voodoo3+

        make above as modules.

        (*) I already forgot why I wanted some special attention for this
        (**) It seems I never need this
        (+) Hmm, It seems I have compiled this as part of the kernel binary

        There is of course lot of other options you need to choose but these
        are probably the ones needed...

   # run make dep
   # run make bzImage
   # run make modules
   # run make modules_install (as root)
   # copy arch/i386/boot/bzImage to /boot/vmlinuz-2.4.4 (as root)
   # edit /etc/lilo.conf and run lilo (as root)

2) In order to (the most easiest way) compile separate i2c and lm_sensors
   -package, symlink your linux source tree to /usr/src/linux (unless it is
   there already) and do the following  

   # tar zxvf i2c-2.5.5.tar.gz
   # cd i2c-2.5.5
   # make
   # make install (as root)
   # cd ..
   # tar zxvf lm_sensors-2.5.5.tar.gz
   # cd lm_sensors-2.5.5
   # make
   # make install (as root)
   # cd ..

   Now you have all necessary modules installed on the system (and
   /usr/local/bin/sensors and /usr/local/sbin/sensors-detect).

   But there is some configuration missing in order to activate
   the needed functionality of the modules...

3) Now, before going any further, let's take a look the modifications that
   is required in XFree86 -configuration so that X is ready for the
   tv-out functionality next time it is started.

   XFree86-4.x uses the configuration file /etc/X11/XF86Config-4. Older
   configuration files needed "ModeLine"s for all display resolutions
   that are needed, but XFree86 version 4 can figure out those by itself.
   But what it cannot figure out, are some special ModeLines that may
   be reguired in various cases... and this is one of these.

   For Voodoo 3 3000 TV out feature, special modelines are needed for
   the supported resolutions, 640x480 and 800x600 (there might be others
   but I don't know enough of the issue. In this document, I only
   activate the 800x600 mode.

   Make backup copy of your /etc/X11/XF86Config-4 in case you accidentally
   screw something up so you can then reuse the old file if this happens.

   Open /etc/X11/XF86Config-4 in your favourite editor and find line
   that contains `Section "Monitor"'. At the end of that section,
   just before line `EndSection', add the following lines:

ModeLine "640x480PAL"   29.50       640  675  678  944  480  530  535  625
ModeLine "800x600PAL"   36.00       800  818  820  960  600  653  655  750

   Then, find lines that starts with something like:

Section "Screen"
        Identifier "Screen0"
        Device "3Dfx Interactive, Inc.|Voodoo 3"
        Monitor "<Your monitor>"
        DefaultDepth 16
...
        Subsection "Display"
                Depth 16
#               Modes "1024x768" "640x480" "800x600" "800x600PAL" #"400x300"
                Modes "1024x768" "800x600PAL" 
        EndSubSection

   Make sure that `DefaultDepth' is set 16 (I don't know if any other works)
   Then you notice there my resolutions as `Modes' -lines. I have outcommented
   the first `Modes' -line so that testing is easier. You can do what
   you widh here, just make sure to add that `"800x600PAL"' -line there.
   Save the file and exit editor.


4) It's is time to reboot (with new kernel), that is the easiest way to
   continue.

5) After rebooting, and X startup `lsmod' in my machine output following:
   Module                  Size  Used by
   tdfx                   54536   1
   es1371                 28500   0
   ac97_codec              8808   0 [es1371]

   tdfx -module was loaded by X, and sound module by some RH -startup script.

   Now you could run /usr/local/sbin/sensors-detect. After that was run in 
   my PII class -machine it suggested I add the following:

   to /etc/modules.conf
   alias char-major-89 i2c-dev

   to some startup script (i choose append to /etc/rc.local)
   # I2C adapter drivers
   /sbin/modprobe i2c-piix4
   /sbin/modprobe i2c-voodoo3
   # I2C chip drivers
   /sbin/modprobe w83781d
   /sbin/modprobe eeprom

   (you run the prg and add the stuff it suggests)

   Let's now /sbin/modprobe -v i2c-voodoo3. Now I have:

   Module                  Size  Used by
   i2c-voodoo3             3012   0  (unused)
   i2c-algo-bit            7796   2  [i2c-voodoo3]
   i2c-core               12844   0  [i2c-algo-bit]
   tdfx                   54536   1 
   es1371                 28500   0 
   ac97_codec              8808   0  [es1371]

   I think this is the only one of the above that is required for the task.
   (If that is not true, I'll revise this text and you never know I though
    such a thing)

   Now, turn on your TV set (unless it is already open) and make sure it
   is getting (either s-video or composite... I personally have only
   tested composite) input from your voodoo3 card. Don't change any
   screen resolution just yet...

   You notice the tv set screen is still blank. Changing screen resolutions
   won't do any change on that, don't bother trying.

   So, how to continue from there. The answer was found looking through
   all the files that are found with zsh command line in lm_sensors dir:
   grep -i voodoo3 **/*(.) | less
   The file doc/chips/bt869 contains interesting information, with it
   and some other information I found somewhere else, don't remember
   either, I did:

   modprobe -v bt869  (or insmod /lib/modules/2.x.x/misc/bt869)

   NOW! you should see some noise on your TV-Set screen.

   and `lsmod' returns (on my machine)

   Module                  Size  Used by
   bt869                   5392   0  (unused)
   i2c-voodoo3             3012   0  (unused)
   sensors                 6140   0  [bt869]
   i2c-algo-bit            7796   2  [i2c-voodoo3]
   i2c-core               12844   0  [bt869 sensors i2c-algo-bit]
   tdfx                   54536   1 
   es1371                 28500   0 
   ac97_codec              8808   0  [es1371]
 
   If you now try to change mode to `800x600PAL' The noise pattern just
   changes. That's because there are various parameters for bt869 to
   make it operate in different systems.

   The configuration entries for bt869 live somewhere in `proc' filesystem
   and since it is so hard to remember, the following commands helps out:

   # find /proc -name "bt869*" -print

   In my system that output: /proc/sys/dev/sensors/bt869-i2c-0-44. Since
   the last few characters may be different on your system I'll use...

   # ls  /proc/sys/dev/sensors/bt869*  ... and this outputs:

   colorbars:  Output colorbars instead of display data. Default `0'.
   depth:      Display depth. Seems to be `16' on my system.
   half:       No idea. Default `0'.
   ntsc:       1: use NTSC, 0: use PAL. Default: `1'.
   res;        Screen resolution to use. Defaut: `640 480'.
   status:     Outputs some status info I do not know what that is.

   For me, in order to get TV sync with incoming signal (or is it Voodoo3 
   that needs syncing), I first put colorbars on, and when I get colorbars
   visible I shut colorbars off -- and then I have part of my 1024x768
   displayed on TV-screen. Normal WIMP screen doesn't look so nice, but
   games, pictures, etc. Looks just fine. And HW acceleration rules.

   Do the following to achieve this:

   # echo 1 > /proc/sys/dev/sensors/bt869*/colorbars
   # echo 0 > /proc/sys/dev/sensors/bt869*/ntsc
   # echo 800 600 > /proc/sys/dev/sensors/bt869*/res

   Press ctrl-alt-num_keypad_+

   Now you should see vertical colorbars on your TV-Set

   # echo 0 > /proc/sys/dev/sensors/bt869*/colorbars

   Now (part of) your computer display should be visible on your TV-Set.   


   ... Ok, I did just that... after ctrl-alt-num_keypad_+ I did not get
   synchronized colorbar output visible on my TV. So, at this time I
   re-did...

   # echo 1 > /proc/sys/dev/sensors/bt869*/colorbars

   ... and got colorbars, and ...

   # echo 0 > /proc/sys/dev/sensors/bt869*/colorbars

   ... got my computer display visible on my TV.


#EOF