Documentation/fb/sstfb.rst

   1 =====
   2 sstfb
   3 =====
   4
   5 Introduction
   6 ============
   7
   8 This is a frame buffer device driver for 3dfx' Voodoo Graphics
   9 (aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
  10 video boards. It's highly experimental code, but is guaranteed to work
  11 on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
  12 and with me "between chair and keyboard". Some people tested other
  13 combinations and it seems that it works.
  14 The main page is located at <http://sstfb.sourceforge.net>, and if
  15 you want the latest version, check out the CVS, as the driver is a work
  16 in progress, I feel uncomfortable with releasing tarballs of something
  17 not completely working...Don't worry, it's still more than usable
  18 (I eat my own dog food)
  19
  20 Please read the Bug section, and report any success or failure to me
  21 (Ghozlane Toumi <gtoumi@laposte.net>).
  22 BTW, If you have only one monitor , and you don't feel like playing
  23 with the vga passthrou cable, I can only suggest borrowing a screen
  24 somewhere...
  25
  26
  27 Installation
  28 ============
  29
  30 This driver (should) work on ix86, with "late" 2.2.x kernel (tested
  31 with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
  32 It has been included in mainstream kernel since the infamous 2.4.10.
  33 You can apply the patches found in `sstfb/kernel/*-2.{2|4}.x.patch`,
  34 and copy sstfb.c to linux/drivers/video/, or apply a single patch,
  35 `sstfb/patch-2.{2|4}.x-sstfb-yymmdd` to your linux source tree.
  36
  37 Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
  38 Graphics in section "console". Compile, install, have fun... and please
  39 drop me a report :)
  40
  41
  42 Module Usage
  43 ============
  44
  45 .. warning::
  46
  47        #. You should read completely this section before issuing any command.
  48
  49        #. If you have only one monitor to play with, once you insmod the
  50           module, the 3dfx takes control of the output, so you'll have to
  51           plug the monitor to the "normal" video board in order to issue
  52           the commands, or you can blindly use sst_dbg_vgapass
  53           in the tools directory (See Tools). The latest solution is pass the
  54           parameter vgapass=1 when insmodding the driver. (See Kernel/Modules
  55           Options)
  56
  57 Module insertion
  58 ----------------
  59
  60        #. insmod sstfb.o
  61
  62           you should see some strange output from the board:
  63           a big blue square, a green and a red small squares and a vertical
  64           white rectangle. why? the function's name is self-explanatory:
  65           "sstfb_test()"...
  66           (if you don't have a second monitor, you'll have to plug your monitor
  67           directly to the 2D videocard to see what you're typing)
  68
  69        #. con2fb /dev/fbx /dev/ttyx
  70
  71           bind a tty to the new frame buffer. if you already have a frame
  72           buffer driver, the voodoo fb will likely be /dev/fb1. if not,
  73           the device will be /dev/fb0. You can check this by doing a
  74           cat /proc/fb. You can find a copy of con2fb in tools/ directory.
  75           if you don't have another fb device, this step is superfluous,
  76           as the console subsystem automagicaly binds ttys to the fb.
  77        #. switch to the virtual console you just mapped. "tadaaa" ...
  78
  79 Module removal
  80 --------------
  81
  82        #. con2fb /dev/fbx /dev/ttyx
  83
  84           bind the tty to the old frame buffer so the module can be removed.
  85           (how does it work with vgacon ? short answer : it doesn't work)
  86
  87        #. rmmod sstfb
  88
  89
  90 Kernel/Modules Options
  91 ----------------------
  92
  93 You can pass some options to the sstfb module, and via the kernel
  94 command line when the driver is compiled in:
  95 for module : insmod sstfb.o option1=value1 option2=value2 ...
  96 in kernel :  video=sstfb:option1,option2:value2,option3 ...
  97
  98 sstfb supports the following options:
  99
 100 =============== =============== ===============================================
 101 Module          Kernel          Description
 102 =============== =============== ===============================================
 103 vgapass=0       vganopass       Enable or disable VGA passthrou cable.
 104 vgapass=1       vgapass         When enabled, the monitor will get the signal
 105                                 from the VGA board and not from the voodoo.
 106
 107                                 Default: nopass
 108
 109 mem=x           mem:x           Force frame buffer memory in MiB
 110                                 allowed values: 0, 1, 2, 4.
 111
 112                                 Default: 0 (= autodetect)
 113
 114 inverse=1       inverse         Supposed to enable inverse console.
 115                                 doesn't work yet...
 116
 117 clipping=1      clipping        Enable or disable clipping.
 118 clipping=0      noclipping      With clipping enabled, all offscreen
 119                                 reads and writes are discarded.
 120
 121                                 Default: enable clipping.
 122
 123 gfxclk=x        gfxclk:x        Force graphic clock frequency (in MHz).
 124                                 Be careful with this option, it may be
 125                                 DANGEROUS.
 126
 127                                 Default: auto
 128
 129                                         - 50Mhz for Voodoo 1,
 130                                         - 75MHz for Voodoo 2.
 131
 132 slowpci=1       fastpci         Enable or disable fast PCI read/writes.
 133 slowpci=1       slowpci         Default : fastpci
 134
 135 dev=x           dev:x           Attach the driver to device number x.
 136                                 0 is the first compatible board (in
 137                                 lspci order)
 138 =============== =============== ===============================================
 139
 140 Tools
 141 =====
 142
 143 These tools are mostly for debugging purposes, but you can
 144 find some of these interesting:
 145
 146 - `con2fb`, maps a tty to a fbramebuffer::
 147
 148         con2fb /dev/fb1 /dev/tty5
 149
 150 - `sst_dbg_vgapass`, changes vga passthrou. You have to recompile the
 151   driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1::
 152
 153         sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
 154         sst_dbg_vgapass /dev/fb1 0 (disables vga cable)
 155
 156 - `glide_reset`, resets the voodoo using glide
 157   use this after rmmoding sstfb, if the module refuses to
 158   reinsert.
 159
 160 Bugs
 161 ====
 162
 163 - DO NOT use glide while the sstfb module is in, you'll most likely
 164   hang your computer.
 165 - If you see some artefacts (pixels not cleaning and stuff like that),
 166   try turning off clipping (clipping=0), and/or using slowpci
 167 - the driver don't detect the 4Mb frame buffer voodoos, it seems that
 168   the 2 last Mbs wrap around. looking into that .
 169 - The driver is 16 bpp only, 24/32 won't work.
 170 - The driver is not your_favorite_toy-safe. this includes SMP...
 171
 172         [Actually from inspection it seems to be safe - Alan]
 173
 174 - When using XFree86 FBdev (X over fbdev) you may see strange color
 175   patterns at the border of your windows (the pixels lose the lowest
 176   byte -> basically the blue component and some of the green). I'm unable
 177   to reproduce this with XFree86-3.3, but one of the testers has this
 178   problem with XFree86-4. Apparently recent Xfree86-4.x solve this
 179   problem.
 180 - I didn't really test changing the palette, so you may find some weird
 181   things when playing with that.
 182 - Sometimes the driver will not recognise the DAC, and the
 183   initialisation will fail. This is specifically true for
 184   voodoo 2 boards, but it should be solved in recent versions. Please
 185   contact me.
 186 - The 24/32 is not likely to work anytime soon, knowing that the
 187   hardware does ... unusual things in 24/32 bpp.
 188
 189 Todo
 190 ====
 191
 192 - Get rid of the previous paragraph.
 193 - Buy more coffee.
 194 - test/port to other arch.
 195 - try to add panning using tweeks with front and back buffer .
 196 - try to implement accel on voodoo2, this board can actually do a
 197   lot in 2D even if it was sold as a 3D only board ...
 198
 199 Ghozlane Toumi <gtoumi@laposte.net>
 200
 201
 202 Date: 2002/05/09 20:11:45
 203
 204 http://sstfb.sourceforge.net/README