Documentation/fb/matroxfb.txt

   1 [This file is cloned from VesaFB. Thanks go to Gerd Knorr]
   2
   3 What is matroxfb?
   4 =================
   5
   6 This is a driver for a graphic framebuffer for Matrox devices on
   7 Alpha, Intel and PPC boxes.
   8
   9 Advantages:
  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
  16 Disadvantages:
  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
  22 How to use it?
  23 ==============
  24
  25 Switching modes is done using the video=matroxfb:vesa:... boot parameter
  26 or using `fbset' program.
  27
  28 If you want, for example, enable a resolution of 1280x1024x24bpp you should
  29 pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".
  30
  31 You should compile in both vgacon (to boot if you remove you Matrox from
  32 box) and matroxfb (for graphics mode). You should not compile-in vesafb
  33 unless you have primary display on non-Matrox VBE2.0 device (see
  34 Documentation/fb/vesafb.txt for details).
  35
  36 Currently supported video modes are (through vesa:... interface, PowerMac
  37 has [as addon] compatibility code):
  38
  39
  40 [Graphic modes]
  41
  42 bpp | 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
  54 bpp | 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
  66 text | 640x400  640x480  1056x344  1056x400  1056x480
  67 -----+------------------------------------------------
  68  8x8 |  0x1C0    0x108     0x10A     0x10B     0x10C
  69 8x16 | 2, 3, 7                       0x109
  70
  71 You can enter these number either hexadecimal (leading `0x') or decimal
  72 (0x100 = 256). You can also use value + 512 to achieve compatibility
  73 with your old number passed to vesafb.
  74
  75 Non-listed number can be achieved by more complicated command-line, for
  76 example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32'.
  77
  78
  79 X11
  80 ===
  81
  82 XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
  83 architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
  84 works fine.
  85
  86 Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
  87 XFree servers have big troubles in multihead configurations (even on first
  88 head, not even talking about second). Running XFree86 4.x accelerated mga
  89 driver is possible, but you must not enable DRI - if you do, resolution and
  90 color depth of your X desktop must match resolution and color depths of your
  91 virtual consoles, otherwise X will corrupt accelerator settings.
  92
  93
  94 SVGALib
  95 =======
  96
  97 Driver contains SVGALib compatibility code. It is turned on by choosing textual
  98 mode for console. You can do it at boot time by using videomode
  99 2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0' does this work.
 100 Unfortunately, after SVGALib application exits, screen contents is corrupted.
 101 Switching to another console and back fixes it. I hope that it is SVGALib's
 102 problem and not mine, but I'm not sure.
 103
 104
 105 Configuration
 106 =============
 107
 108 You can pass kernel command line options to matroxfb with
 109 `video=matroxfb:option1,option2:value2,option3' (multiple options should be
 110 separated by comma, values are separated from options by `:').
 111 Accepted options:
 112
 113 mem: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).
 117 disabled - do not load driver; you can use also `off', but `disabled'
 118            is here too.
 119 enabled  - load driver, if you have `video=matroxfb:disabled' in LILO
 120            configuration, you can override it by this (you cannot override
 121            `off'). It is default.
 122 noaccel  - do not use acceleration engine. It does not work on Alphas.
 123 accel    - use acceleration engine. It is default.
 124 nopan    - create initial consoles with vyres = yres, thus disabling virtual
 125            scrolling.
 126 pan      - create initial consoles as tall as possible (vyres = memory/vxres).
 127            It is default.
 128 nopciretry - 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).
 132 pciretry - enable PCI retries. It is default, except for intel's 82437.
 133 novga    - 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.
 136 vga      - 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).
 139 nobios   - 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.
 142 bios     - preserve state of BIOS ROM. It is default. Driver does not enable
 143            BIOS if BIOS was not enabled before.
 144 noinit   - 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.
 148 init     - driver initializes every device it knows about.
 149 memtype  - 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.
 170 nomtrr   - 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).
 173 mtrr     - 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).
 176 sgram    - tells to driver that you have Gxx0 with SGRAM memory. It has no
 177            effect without `init'.
 178 sdram    - tells to driver that you have Gxx0 with SDRAM memory.
 179            It is a default.
 180 inv24    - change timings parameters for 24bpp modes on Millenium and
 181            Millenium II. Specify this if you see strange color shadows around
 182            characters.
 183 noinv24  - use standard timings. It is the default.
 184 inverse  - invert colors on screen (for LCD displays)
 185 noinverse - show true colors on screen. It is default.
 186 dev: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.
 192 nohwcursor - disables hardware cursor (use software cursor instead).
 193 hwcursor - 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).
 196 noblink  - disables cursor blinking. Cursor in text mode always blinks (hw
 197            limitation).
 198 blink    - enables cursor blinking. It is default.
 199 nofastfont - disables fastfont feature. It is default.
 200 fastfont: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.
 203 grayscale - 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.
 207 nograyscale - disable grayscale summing. It is default.
 208 cross4MB - enables that pixel line can cross 4MB boundary. It is default for
 209            non-Millenium.
 210 nocross4MB - 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.
 215 dfp      - 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.
 219 dfp: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.
 226 outputs:XYZ - set mapping between CRTC and outputs. Each letter can have value
 227            of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter corresponds
 228            to primary analog output, second letter to the secondary analog output
 229            and third letter to the DVI output. Default setting is 100 for
 230            cards below G400 or G400 without DFP, 101 for G400 with DFP, and
 231            111 for G450 and G550. You can set mapping only on first card,
 232            use matroxset for setting up other devices.
 233 vesa:X   - selects startup videomode. X is number from 0 to 0x1FF, see table
 234            above for detailed explanation. Default is 640x480x8bpp if driver
 235            has 8bpp support. Otherwise first available of 640x350x4bpp,
 236            640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
 237            (80x25 text is always available).
 238
 239 If you are not satisfied with videomode selected by `vesa' option, you
 240 can modify it with these options:
 241
 242 xres:X   - horizontal resolution, in pixels. Default is derived from `vesa'
 243            option.
 244 yres:X   - vertical resolution, in pixel lines. Default is derived from `vesa'
 245            option.
 246 upper:X  - top boundary: lines between end of VSYNC pulse and start of first
 247            pixel line of picture. Default is derived from `vesa' option.
 248 lower:X  - bottom boundary: lines between end of picture and start of VSYNC
 249            pulse. Default is derived from `vesa' option.
 250 vslen:X  - length of VSYNC pulse, in lines. Default is derived from `vesa'
 251            option.
 252 left:X   - left boundary: pixels between end of HSYNC pulse and first pixel.
 253            Default is derived from `vesa' option.
 254 right:X  - right boundary: pixels between end of picture and start of HSYNC
 255            pulse. Default is derived from `vesa' option.
 256 hslen:X  - length of HSYNC pulse, in pixels. Default is derived from `vesa'
 257            option.
 258 pixclock:X - dotclocks, in ps (picoseconds). Default is derived from `vesa'
 259              option and from `fh' and `fv' options.
 260 sync:X   - sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
 261            If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
 262            generated. If bit 5 (value 0x20) is set, sync on green is turned on.
 263            Do not forget that if you want sync on green, you also probably
 264            want composite sync.
 265            Default depends on `vesa'.
 266 depth:X  - Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
 267            `vesa'.
 268
 269 If you know capabilities of your monitor, you can specify some (or all) of
 270 `maxclk', `fh' and `fv'. In this case, `pixclock' is computed so that
 271 pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
 272
 273 maxclk:X - maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
 274            `don't care'.
 275 fh:X     - maximum horizontal synchronization frequency. X can be specified
 276            in kHz or Hz. Default is `don't care'.
 277 fv:X     - maximum vertical frequency. X must be specified in Hz. Default is
 278            70 for modes derived from `vesa' with yres <= 400, 60Hz for
 279            yres > 400.
 280
 281
 282 Limitations
 283 ===========
 284
 285 There are known and unknown bugs, features and misfeatures.
 286 Currently there are following known bugs:
 287  + SVGALib does not restore screen on exit
 288  + generic fbcon-cfbX procedures do not work on Alphas. Due to this,
 289    `noaccel' (and cfb4 accel) driver does not work on Alpha. So everyone
 290    with access to /dev/fb* on Alpha can hang machine (you should restrict
 291    access to /dev/fb* - everyone with access to this device can destroy
 292    your monitor, believe me...).
 293  + 24bpp does not support correctly XF-FBDev on big-endian architectures.
 294  + interlaced text mode is not supported; it looks like hardware limitation,
 295    but I'm not sure.
 296  + Gxx0 SGRAM/SDRAM is not autodetected.
 297  + If you are using more than one framebuffer device, you must boot kernel
 298    with 'video=scrollback:0'.
 299  + maybe more...
 300 And following misfeatures:
 301  + SVGALib does not restore screen on exit.
 302  + pixclock for text modes is limited by hardware to
 303     83 MHz on G200
 304     66 MHz on Millennium I
 305     60 MHz on Millennium II
 306    Because I have no access to other devices, I do not know specific
 307    frequencies for them. So driver does not check this and allows you to
 308    set frequency higher that this. It causes sparks, black holes and other
 309    pretty effects on screen. Device was not destroyed during tests. :-)
 310  + my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
 311    (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
 312    But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
 313    them (maybe that chip overheats, but it has a very big cooler (G100 has
 314    none), so it should work).
 315  + special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
 316    G16V16 are not supported
 317  + color keying is not supported
 318  + feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
 319    by BIOS)
 320  + DDC (monitor detection) is supported through dualhead driver
 321  + some check for input values are not so strict how it should be (you can
 322    specify vslen=4000 and so on).
 323  + maybe more...
 324 And following features:
 325  + 4bpp is available only on Millennium I and Millennium II. It is hardware
 326    limitation.
 327  + selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
 328    option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
 329    else selects 5:6:5 mode.
 330  + text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
 331    instead of one of 16M colors). It is due to hardware limitation of
 332    Millennium I/II and SVGALib compatibility.
 333
 334
 335 Benchmarks
 336 ==========
 337 It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
 338 time for draw 6144000 characters on screen through /dev/vcsa
 339 (for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
 340 16 seconds, i.e. 187 MBps).
 341 Times were obtained from one older version of driver, now they are about 3%
 342 faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
 343 PCI slot, G200 in AGP 2x slot. I did not test vgacon.
 344
 345 NOACCEL
 346         8x16                 12x22
 347         Millennium I  G200   Millennium I  G200
 348 8bpp    16.42         9.54   12.33         9.13
 349 16bpp   21.00        15.70   19.11        15.02
 350 24bpp   36.66        36.66   35.00        35.00
 351 32bpp   35.00        30.00   33.85        28.66
 352
 353 ACCEL, nofastfont
 354         8x16                 12x22                6x11
 355         Millennium I  G200   Millennium I  G200   Millennium I  G200
 356 8bpp     7.79         7.24   13.55         7.78   30.00        21.01
 357 16bpp    9.13         7.78   16.16         7.78   30.00        21.01
 358 24bpp   14.17        10.72   18.69        10.24   34.99        21.01
 359 32bpp   16.15        16.16   18.73        13.09   34.99        21.01
 360
 361 ACCEL, fastfont
 362         8x16                 12x22                6x11
 363         Millennium I  G200   Millennium I  G200   Millennium I  G200
 364 8bpp     8.41         6.01    6.54         4.37   16.00        10.51
 365 16bpp    9.54         9.12    8.76         6.17   17.52        14.01
 366 24bpp   15.00        12.36   11.67        10.00   22.01        18.32
 367 32bpp   16.18        18.29*  12.71        12.74   24.44        21.00
 368
 369 TEXT
 370         8x16
 371         Millennium I  G200
 372 TEXT     3.29         1.50
 373
 374 * Yes, it is slower than Millennium I.
 375
 376
 377 Dualhead G400
 378 =============
 379 Driver supports dualhead G400 with some limitations:
 380  + secondary head shares videomemory with primary head. It is not problem
 381    if you have 32MB of videoram, but if you have only 16MB, you may have
 382    to think twice before choosing videomode (for example twice 1880x1440x32bpp
 383    is not possible).
 384  + due to hardware limitation, secondary head can use only 16 and 32bpp
 385    videomodes.
 386  + secondary head is not accelerated. There were bad problems with accelerated
 387    XFree when secondary head used to use acceleration.
 388  + secondary head always powerups in 640x480@60-32 videomode. You have to use
 389    fbset to change this mode.
 390  + secondary head always powerups in monitor mode. You have to use fbmatroxset
 391    to change it to TV mode. Also, you must select at least 525 lines for
 392    NTSC output and 625 lines for PAL output.
 393  + kernel is not fully multihead ready. So some things are impossible to do.
 394  + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
 395    and matroxfb_crtc2 into kernel.
 396
 397
 398 Dualhead G450
 399 =============
 400 Driver supports dualhead G450 with some limitations:
 401  + secondary head shares videomemory with primary head. It is not problem
 402    if you have 32MB of videoram, but if you have only 16MB, you may have
 403    to think twice before choosing videomode.
 404  + due to hardware limitation, secondary head can use only 16 and 32bpp
 405    videomodes.
 406  + secondary head is not accelerated.
 407  + secondary head always powerups in 640x480@60-32 videomode. You have to use
 408    fbset to change this mode.
 409  + TV output is not supported
 410  + kernel is not fully multihead ready, so some things are impossible to do.
 411  + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
 412    into kernel.
 413
 414 --
 415 Petr Vandrovec <vandrove@vc.cvut.cz>