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