Commit | Line | Data |
---|---|---|
ab42b818 MCC |
1 | ================= |
2 | What is matroxfb? | |
3 | ================= | |
4 | ||
5 | .. [This file is cloned from VesaFB. Thanks go to Gerd Knorr] | |
6 | ||
7 | ||
8 | This is a driver for a graphic framebuffer for Matrox devices on | |
9 | Alpha, Intel and PPC boxes. | |
10 | ||
11 | Advantages: | |
12 | ||
13 | * It provides a nice large console (128 cols + 48 lines with 1024x768) | |
14 | without using tiny, unreadable fonts. | |
15 | * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0 | |
16 | * Most important: boot logo :-) | |
17 | ||
18 | Disadvantages: | |
19 | ||
20 | * graphic mode is slower than text mode... but you should not notice | |
21 | if you use same resolution as you used in textmode. | |
22 | ||
23 | ||
24 | How to use it? | |
25 | ============== | |
26 | ||
27 | Switching modes is done using the video=matroxfb:vesa:... boot parameter | |
28 | or using `fbset` program. | |
29 | ||
30 | If you want, for example, enable a resolution of 1280x1024x24bpp you should | |
31 | pass to the kernel this command line: "video=matroxfb:vesa:0x1BB". | |
32 | ||
33 | You should compile in both vgacon (to boot if you remove you Matrox from | |
34 | box) and matroxfb (for graphics mode). You should not compile-in vesafb | |
35 | unless you have primary display on non-Matrox VBE2.0 device (see | |
36 | Documentation/fb/vesafb.rst for details). | |
37 | ||
38 | Currently supported video modes are (through vesa:... interface, PowerMac | |
39 | has [as addon] compatibility code): | |
40 | ||
41 | ||
42 | Graphic modes | |
43 | ------------- | |
44 | ||
45 | === ======= ======= ======= ======= ======= | |
46 | bpp 640x400 640x480 768x576 800x600 960x720 | |
47 | === ======= ======= ======= ======= ======= | |
48 | 4 0x12 0x102 | |
49 | 8 0x100 0x101 0x180 0x103 0x188 | |
50 | 15 0x110 0x181 0x113 0x189 | |
51 | 16 0x111 0x182 0x114 0x18A | |
52 | 24 0x1B2 0x184 0x1B5 0x18C | |
53 | 32 0x112 0x183 0x115 0x18B | |
54 | === ======= ======= ======= ======= ======= | |
55 | ||
56 | ||
57 | Graphic modes (continued) | |
58 | ------------------------- | |
59 | ||
60 | === ======== ======== ========= ========= ========= | |
61 | bpp 1024x768 1152x864 1280x1024 1408x1056 1600x1200 | |
62 | === ======== ======== ========= ========= ========= | |
63 | 4 0x104 0x106 | |
64 | 8 0x105 0x190 0x107 0x198 0x11C | |
65 | 15 0x116 0x191 0x119 0x199 0x11D | |
66 | 16 0x117 0x192 0x11A 0x19A 0x11E | |
67 | 24 0x1B8 0x194 0x1BB 0x19C 0x1BF | |
68 | 32 0x118 0x193 0x11B 0x19B | |
69 | === ======== ======== ========= ========= ========= | |
70 | ||
71 | ||
72 | Text modes | |
73 | ---------- | |
74 | ||
75 | ==== ======= ======= ======== ======== ======== | |
76 | text 640x400 640x480 1056x344 1056x400 1056x480 | |
77 | ==== ======= ======= ======== ======== ======== | |
78 | 8x8 0x1C0 0x108 0x10A 0x10B 0x10C | |
79 | 8x16 2, 3, 7 0x109 | |
80 | ==== ======= ======= ======== ======== ======== | |
81 | ||
82 | You can enter these number either hexadecimal (leading `0x`) or decimal | |
83 | (0x100 = 256). You can also use value + 512 to achieve compatibility | |
84 | with your old number passed to vesafb. | |
85 | ||
86 | Non-listed number can be achieved by more complicated command-line, for | |
87 | example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32`. | |
88 | ||
89 | ||
90 | X11 | |
91 | === | |
92 | ||
93 | XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel | |
94 | architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp | |
95 | works fine. | |
96 | ||
97 | Running another (accelerated) X-Server like XF86_SVGA works too. But (at least) | |
98 | XFree servers have big troubles in multihead configurations (even on first | |
99 | head, not even talking about second). Running XFree86 4.x accelerated mga | |
100 | driver is possible, but you must not enable DRI - if you do, resolution and | |
101 | color depth of your X desktop must match resolution and color depths of your | |
102 | virtual consoles, otherwise X will corrupt accelerator settings. | |
103 | ||
104 | ||
105 | SVGALib | |
106 | ======= | |
107 | ||
108 | Driver contains SVGALib compatibility code. It is turned on by choosing textual | |
109 | mode for console. You can do it at boot time by using videomode | |
110 | 2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0` does this work. | |
111 | Unfortunately, after SVGALib application exits, screen contents is corrupted. | |
112 | Switching to another console and back fixes it. I hope that it is SVGALib's | |
113 | problem and not mine, but I'm not sure. | |
114 | ||
115 | ||
116 | Configuration | |
117 | ============= | |
118 | ||
119 | You can pass kernel command line options to matroxfb with | |
120 | `video=matroxfb:option1,option2:value2,option3` (multiple options should be | |
121 | separated by comma, values are separated from options by `:`). | |
122 | Accepted options: | |
123 | ||
124 | ============ =================================================================== | |
125 | mem:X size of memory (X can be in megabytes, kilobytes or bytes) | |
126 | You can only decrease value determined by driver because of | |
127 | it always probe for memory. Default is to use whole detected | |
128 | memory usable for on-screen display (i.e. max. 8 MB). | |
129 | disabled do not load driver; you can use also `off`, but `disabled` | |
130 | is here too. | |
131 | enabled load driver, if you have `video=matroxfb:disabled` in LILO | |
132 | configuration, you can override it by this (you cannot override | |
133 | `off`). It is default. | |
134 | noaccel do not use acceleration engine. It does not work on Alphas. | |
135 | accel use acceleration engine. It is default. | |
136 | nopan create initial consoles with vyres = yres, thus disabling virtual | |
137 | scrolling. | |
138 | pan create initial consoles as tall as possible (vyres = memory/vxres). | |
139 | It is default. | |
140 | nopciretry disable PCI retries. It is needed for some broken chipsets, | |
141 | it is autodetected for intel's 82437. In this case device does | |
142 | not comply to PCI 2.1 specs (it will not guarantee that every | |
143 | transaction terminate with success or retry in 32 PCLK). | |
144 | pciretry enable PCI retries. It is default, except for intel's 82437. | |
145 | novga disables VGA I/O ports. It is default if BIOS did not enable | |
146 | device. You should not use this option, some boards then do not | |
147 | restart without power off. | |
148 | vga preserve state of VGA I/O ports. It is default. Driver does not | |
149 | enable VGA I/O if BIOS did not it (it is not safe to enable it in | |
150 | most cases). | |
151 | nobios disables BIOS ROM. It is default if BIOS did not enable BIOS | |
152 | itself. You should not use this option, some boards then do not | |
153 | restart without power off. | |
154 | bios preserve state of BIOS ROM. It is default. Driver does not enable | |
155 | BIOS if BIOS was not enabled before. | |
156 | noinit tells driver, that devices were already initialized. You should use | |
157 | it if you have G100 and/or if driver cannot detect memory, you see | |
158 | strange pattern on screen and so on. Devices not enabled by BIOS | |
159 | are still initialized. It is default. | |
160 | init driver initializes every device it knows about. | |
161 | memtype specifies memory type, implies 'init'. This is valid only for G200 | |
162 | and G400 and has following meaning: | |
163 | ||
164 | G200: | |
165 | - 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram | |
166 | - 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram | |
167 | - 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram | |
168 | - 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram | |
169 | - 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only | |
170 | - 5 -> same as above | |
171 | - 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram | |
172 | - 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram | |
173 | G400: | |
174 | - 0 -> 2x512Kx16 SDRAM, 16/32MB | |
175 | - 2x512Kx32 SGRAM, 16/32MB | |
176 | - 1 -> 2x256Kx32 SGRAM, 8/16MB | |
177 | - 2 -> 4x128Kx32 SGRAM, 8/16MB | |
178 | - 3 -> 4x512Kx32 SDRAM, 32MB | |
179 | - 4 -> 4x256Kx32 SGRAM, 16/32MB | |
180 | - 5 -> 2x1Mx32 SDRAM, 32MB | |
181 | - 6 -> reserved | |
182 | - 7 -> reserved | |
183 | ||
184 | You should use sdram or sgram parameter in addition to memtype | |
185 | parameter. | |
186 | nomtrr disables write combining on frame buffer. This slows down driver | |
187 | but there is reported minor incompatibility between GUS DMA and | |
188 | XFree under high loads if write combining is enabled (sound | |
189 | dropouts). | |
190 | mtrr enables write combining on frame buffer. It speeds up video | |
191 | accesses much. It is default. You must have MTRR support enabled | |
192 | in kernel and your CPU must have MTRR (f.e. Pentium II have them). | |
193 | sgram tells to driver that you have Gxx0 with SGRAM memory. It has no | |
194 | effect without `init`. | |
195 | sdram tells to driver that you have Gxx0 with SDRAM memory. | |
196 | It is a default. | |
197 | inv24 change timings parameters for 24bpp modes on Millennium and | |
198 | Millennium II. Specify this if you see strange color shadows | |
199 | around characters. | |
200 | noinv24 use standard timings. It is the default. | |
201 | inverse invert colors on screen (for LCD displays) | |
202 | noinverse show true colors on screen. It is default. | |
203 | dev:X bind driver to device X. Driver numbers device from 0 up to N, | |
204 | where device 0 is first `known` device found, 1 second and so on. | |
205 | lspci lists devices in this order. | |
206 | Default is `every` known device. | |
207 | nohwcursor disables hardware cursor (use software cursor instead). | |
208 | hwcursor enables hardware cursor. It is default. If you are using | |
209 | non-accelerated mode (`noaccel` or `fbset -accel false`), software | |
210 | cursor is used (except for text mode). | |
211 | noblink disables cursor blinking. Cursor in text mode always blinks (hw | |
212 | limitation). | |
213 | blink enables cursor blinking. It is default. | |
214 | nofastfont disables fastfont feature. It is default. | |
215 | fastfont:X enables fastfont feature. X specifies size of memory reserved for | |
216 | font data, it must be >= (fontwidth*fontheight*chars_in_font)/8. | |
217 | It is faster on Gx00 series, but slower on older cards. | |
218 | grayscale enable grayscale summing. It works in PSEUDOCOLOR modes (text, | |
219 | 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters | |
220 | displayed through putc/putcs. Direct accesses to framebuffer | |
221 | can paint colors. | |
222 | nograyscale disable grayscale summing. It is default. | |
223 | cross4MB enables that pixel line can cross 4MB boundary. It is default for | |
224 | non-Millennium. | |
225 | nocross4MB pixel line must not cross 4MB boundary. It is default for | |
226 | Millennium I or II, because of these devices have hardware | |
227 | limitations which do not allow this. But this option is | |
228 | incompatible with some (if not all yet released) versions of | |
229 | XF86_FBDev. | |
230 | dfp enables digital flat panel interface. This option is incompatible | |
231 | with secondary (TV) output - if DFP is active, TV output must be | |
232 | inactive and vice versa. DFP always uses same timing as primary | |
233 | (monitor) output. | |
234 | dfp:X use settings X for digital flat panel interface. X is number from | |
235 | 0 to 0xFF, and meaning of each individual bit is described in | |
236 | G400 manual, in description of DAC register 0x1F. For normal | |
237 | operation you should set all bits to zero, except lowest bit. This | |
238 | lowest bit selects who is source of display clocks, whether G400, | |
239 | or panel. Default value is now read back from hardware - so you | |
240 | should specify this value only if you are also using `init` | |
241 | parameter. | |
242 | outputs:XYZ set mapping between CRTC and outputs. Each letter can have value | |
243 | of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter | |
244 | corresponds to primary analog output, second letter to the | |
245 | secondary analog output and third letter to the DVI output. | |
246 | Default setting is 100 for cards below G400 or G400 without DFP, | |
247 | 101 for G400 with DFP, and 111 for G450 and G550. You can set | |
248 | mapping only on first card, use matroxset for setting up other | |
249 | devices. | |
250 | vesa:X selects startup videomode. X is number from 0 to 0x1FF, see table | |
251 | above for detailed explanation. Default is 640x480x8bpp if driver | |
252 | has 8bpp support. Otherwise first available of 640x350x4bpp, | |
253 | 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text | |
254 | (80x25 text is always available). | |
255 | ============ =================================================================== | |
256 | ||
257 | If you are not satisfied with videomode selected by `vesa` option, you | |
258 | can modify it with these options: | |
259 | ||
260 | ============ =================================================================== | |
261 | xres:X horizontal resolution, in pixels. Default is derived from `vesa` | |
262 | option. | |
263 | yres:X vertical resolution, in pixel lines. Default is derived from `vesa` | |
264 | option. | |
265 | upper:X top boundary: lines between end of VSYNC pulse and start of first | |
266 | pixel line of picture. Default is derived from `vesa` option. | |
267 | lower:X bottom boundary: lines between end of picture and start of VSYNC | |
268 | pulse. Default is derived from `vesa` option. | |
269 | vslen:X length of VSYNC pulse, in lines. Default is derived from `vesa` | |
270 | option. | |
271 | left:X left boundary: pixels between end of HSYNC pulse and first pixel. | |
272 | Default is derived from `vesa` option. | |
273 | right:X right boundary: pixels between end of picture and start of HSYNC | |
274 | pulse. Default is derived from `vesa` option. | |
275 | hslen:X length of HSYNC pulse, in pixels. Default is derived from `vesa` | |
276 | option. | |
277 | pixclock:X dotclocks, in ps (picoseconds). Default is derived from `vesa` | |
278 | option and from `fh` and `fv` options. | |
279 | sync:X sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity. | |
280 | If bit 3 (value 0x08) is set, composite sync instead of HSYNC is | |
281 | generated. If bit 5 (value 0x20) is set, sync on green is turned | |
282 | on. Do not forget that if you want sync on green, you also probably | |
283 | want composite sync. | |
284 | Default depends on `vesa`. | |
285 | depth:X Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on | |
286 | `vesa`. | |
287 | ============ =================================================================== | |
288 | ||
289 | If you know capabilities of your monitor, you can specify some (or all) of | |
290 | `maxclk`, `fh` and `fv`. In this case, `pixclock` is computed so that | |
291 | pixclock <= maxclk, real_fh <= fh and real_fv <= fv. | |
292 | ||
293 | ============ ================================================================== | |
294 | maxclk:X maximum dotclock. X can be specified in MHz, kHz or Hz. Default is | |
295 | `don`t care`. | |
296 | fh:X maximum horizontal synchronization frequency. X can be specified | |
297 | in kHz or Hz. Default is `don't care`. | |
298 | fv:X maximum vertical frequency. X must be specified in Hz. Default is | |
299 | 70 for modes derived from `vesa` with yres <= 400, 60Hz for | |
300 | yres > 400. | |
301 | ============ ================================================================== | |
302 | ||
303 | ||
304 | Limitations | |
305 | =========== | |
306 | ||
307 | There are known and unknown bugs, features and misfeatures. | |
308 | Currently there are following known bugs: | |
309 | ||
310 | - SVGALib does not restore screen on exit | |
311 | - generic fbcon-cfbX procedures do not work on Alphas. Due to this, | |
312 | `noaccel` (and cfb4 accel) driver does not work on Alpha. So everyone | |
313 | with access to `/dev/fb*` on Alpha can hang machine (you should restrict | |
314 | access to `/dev/fb*` - everyone with access to this device can destroy | |
315 | your monitor, believe me...). | |
316 | - 24bpp does not support correctly XF-FBDev on big-endian architectures. | |
317 | - interlaced text mode is not supported; it looks like hardware limitation, | |
318 | but I'm not sure. | |
319 | - Gxx0 SGRAM/SDRAM is not autodetected. | |
320 | - If you are using more than one framebuffer device, you must boot kernel | |
321 | with 'video=scrollback:0'. | |
322 | - maybe more... | |
323 | ||
324 | And following misfeatures: | |
325 | ||
326 | - SVGALib does not restore screen on exit. | |
327 | - pixclock for text modes is limited by hardware to | |
328 | ||
329 | - 83 MHz on G200 | |
330 | - 66 MHz on Millennium I | |
331 | - 60 MHz on Millennium II | |
332 | ||
333 | Because I have no access to other devices, I do not know specific | |
334 | frequencies for them. So driver does not check this and allows you to | |
335 | set frequency higher that this. It causes sparks, black holes and other | |
336 | pretty effects on screen. Device was not destroyed during tests. :-) | |
337 | - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz | |
338 | (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)). | |
339 | But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe | |
340 | them (maybe that chip overheats, but it has a very big cooler (G100 has | |
341 | none), so it should work). | |
342 | - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and | |
343 | G16V16 are not supported | |
344 | - color keying is not supported | |
345 | - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled | |
346 | by BIOS) | |
347 | - DDC (monitor detection) is supported through dualhead driver | |
348 | - some check for input values are not so strict how it should be (you can | |
349 | specify vslen=4000 and so on). | |
350 | - maybe more... | |
351 | ||
352 | And following features: | |
353 | ||
354 | - 4bpp is available only on Millennium I and Millennium II. It is hardware | |
355 | limitation. | |
356 | - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba | |
357 | option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything | |
358 | else selects 5:6:5 mode. | |
359 | - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors | |
360 | instead of one of 16M colors). It is due to hardware limitation of | |
361 | Millennium I/II and SVGALib compatibility. | |
362 | ||
363 | ||
364 | Benchmarks | |
365 | ========== | |
366 | It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is | |
367 | time for draw 6144000 characters on screen through /dev/vcsa | |
368 | (for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in | |
369 | 16 seconds, i.e. 187 MBps). | |
370 | Times were obtained from one older version of driver, now they are about 3% | |
371 | faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz | |
372 | PCI slot, G200 in AGP 2x slot. I did not test vgacon:: | |
373 | ||
374 | NOACCEL | |
375 | 8x16 12x22 | |
376 | Millennium I G200 Millennium I G200 | |
377 | 8bpp 16.42 9.54 12.33 9.13 | |
378 | 16bpp 21.00 15.70 19.11 15.02 | |
379 | 24bpp 36.66 36.66 35.00 35.00 | |
380 | 32bpp 35.00 30.00 33.85 28.66 | |
381 | ||
382 | ACCEL, nofastfont | |
383 | 8x16 12x22 6x11 | |
384 | Millennium I G200 Millennium I G200 Millennium I G200 | |
385 | 8bpp 7.79 7.24 13.55 7.78 30.00 21.01 | |
386 | 16bpp 9.13 7.78 16.16 7.78 30.00 21.01 | |
387 | 24bpp 14.17 10.72 18.69 10.24 34.99 21.01 | |
388 | 32bpp 16.15 16.16 18.73 13.09 34.99 21.01 | |
389 | ||
390 | ACCEL, fastfont | |
391 | 8x16 12x22 6x11 | |
392 | Millennium I G200 Millennium I G200 Millennium I G200 | |
393 | 8bpp 8.41 6.01 6.54 4.37 16.00 10.51 | |
394 | 16bpp 9.54 9.12 8.76 6.17 17.52 14.01 | |
395 | 24bpp 15.00 12.36 11.67 10.00 22.01 18.32 | |
396 | 32bpp 16.18 18.29* 12.71 12.74 24.44 21.00 | |
397 | ||
398 | TEXT | |
399 | 8x16 | |
400 | Millennium I G200 | |
401 | TEXT 3.29 1.50 | |
402 | ||
403 | * Yes, it is slower than Millennium I. | |
404 | ||
405 | ||
406 | Dualhead G400 | |
407 | ============= | |
408 | Driver supports dualhead G400 with some limitations: | |
409 | + secondary head shares videomemory with primary head. It is not problem | |
410 | if you have 32MB of videoram, but if you have only 16MB, you may have | |
411 | to think twice before choosing videomode (for example twice 1880x1440x32bpp | |
412 | is not possible). | |
413 | + due to hardware limitation, secondary head can use only 16 and 32bpp | |
414 | videomodes. | |
415 | + secondary head is not accelerated. There were bad problems with accelerated | |
416 | XFree when secondary head used to use acceleration. | |
417 | + secondary head always powerups in 640x480@60-32 videomode. You have to use | |
418 | fbset to change this mode. | |
419 | + secondary head always powerups in monitor mode. You have to use fbmatroxset | |
420 | to change it to TV mode. Also, you must select at least 525 lines for | |
421 | NTSC output and 625 lines for PAL output. | |
422 | + kernel is not fully multihead ready. So some things are impossible to do. | |
423 | + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven | |
424 | and matroxfb_crtc2 into kernel. | |
425 | ||
426 | ||
427 | Dualhead G450 | |
428 | ============= | |
429 | Driver supports dualhead G450 with some limitations: | |
430 | + secondary head shares videomemory with primary head. It is not problem | |
431 | if you have 32MB of videoram, but if you have only 16MB, you may have | |
432 | to think twice before choosing videomode. | |
433 | + due to hardware limitation, secondary head can use only 16 and 32bpp | |
434 | videomodes. | |
435 | + secondary head is not accelerated. | |
436 | + secondary head always powerups in 640x480@60-32 videomode. You have to use | |
437 | fbset to change this mode. | |
438 | + TV output is not supported | |
439 | + kernel is not fully multihead ready, so some things are impossible to do. | |
440 | + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2 | |
441 | into kernel. | |
442 | ||
443 | Petr Vandrovec <vandrove@vc.cvut.cz> |