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