1=====
2sstfb
3=====
4
5Introduction
6============
7
8This is a frame buffer device driver for 3dfx' Voodoo Graphics
9(aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
10video boards. It's highly experimental code, but is guaranteed to work
11on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
12and with me "between chair and keyboard". Some people tested other
13combinations and it seems that it works.
14The main page is located at <http://sstfb.sourceforge.net>, and if
15you want the latest version, check out the CVS, as the driver is a work
16in progress, I feel uncomfortable with releasing tarballs of something
17not completely working...Don't worry, it's still more than usable
18(I eat my own dog food)
19
20Please read the Bug section, and report any success or failure to me
21(Ghozlane Toumi <gtoumi@laposte.net>).
22BTW, If you have only one monitor , and you don't feel like playing
23with the vga passthrou cable, I can only suggest borrowing a screen
24somewhere...
25
26
27Installation
28============
29
30This driver (should) work on ix86, with "late" 2.2.x kernel (tested
31with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
32It has been included in mainstream kernel since the infamous 2.4.10.
33You can apply the patches found in `sstfb/kernel/*-2.{2|4}.x.patch`,
34and 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
37Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
38Graphics in section "console". Compile, install, have fun... and please
39drop me a report :)
40
41
42Module 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
57Module 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
79Module 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
90Kernel/Modules Options
91----------------------
92
93You can pass some options to the sstfb module, and via the kernel
94command line when the driver is compiled in:
95for module : insmod sstfb.o option1=value1 option2=value2 ...
96in kernel :  video=sstfb:option1,option2:value2,option3 ...
97
98sstfb supports the following options:
99
100=============== =============== ===============================================
101Module		Kernel		Description
102=============== =============== ===============================================
103vgapass=0	vganopass	Enable or disable VGA passthrou cable.
104vgapass=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
109mem=x		mem:x		Force frame buffer memory in MiB
110				allowed values: 0, 1, 2, 4.
111
112				Default: 0 (= autodetect)
113
114inverse=1	inverse		Supposed to enable inverse console.
115				doesn't work yet...
116
117clipping=1	clipping	Enable or disable clipping.
118clipping=0	noclipping	With clipping enabled, all offscreen
119				reads and writes are discarded.
120
121				Default: enable clipping.
122
123gfxclk=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
132slowpci=1	fastpci		Enable or disable fast PCI read/writes.
133slowpci=1	slowpci		Default : fastpci
134
135dev=x		dev:x		Attach the driver to device number x.
136				0 is the first compatible board (in
137				lspci order)
138=============== =============== ===============================================
139
140Tools
141=====
142
143These tools are mostly for debugging purposes, but you can
144find 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
160Bugs
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
189Todo
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
199Ghozlane Toumi <gtoumi@laposte.net>
200
201
202Date: 2002/05/09 20:11:45
203
204http://sstfb.sourceforge.net/README
205