Documentation/fb/matroxfb.rst

   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  - maybe more...
 321
 322 And following misfeatures:
 323
 324  - SVGALib does not restore screen on exit.
 325  - pixclock for text modes is limited by hardware to
 326
 327     - 83 MHz on G200
 328     - 66 MHz on Millennium I
 329     - 60 MHz on Millennium II
 330
 331    Because I have no access to other devices, I do not know specific
 332    frequencies for them. So driver does not check this and allows you to
 333    set frequency higher that this. It causes sparks, black holes and other
 334    pretty effects on screen. Device was not destroyed during tests. :-)
 335  - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
 336    (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
 337    But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
 338    them (maybe that chip overheats, but it has a very big cooler (G100 has
 339    none), so it should work).
 340  - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
 341    G16V16 are not supported
 342  - color keying is not supported
 343  - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
 344    by BIOS)
 345  - DDC (monitor detection) is supported through dualhead driver
 346  - some check for input values are not so strict how it should be (you can
 347    specify vslen=4000 and so on).
 348  - maybe more...
 349
 350 And following features:
 351
 352  - 4bpp is available only on Millennium I and Millennium II. It is hardware
 353    limitation.
 354  - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
 355    option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
 356    else selects 5:6:5 mode.
 357  - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
 358    instead of one of 16M colors). It is due to hardware limitation of
 359    Millennium I/II and SVGALib compatibility.
 360
 361
 362 Benchmarks
 363 ==========
 364 It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
 365 time for draw 6144000 characters on screen through /dev/vcsa
 366 (for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
 367 16 seconds, i.e. 187 MBps).
 368 Times were obtained from one older version of driver, now they are about 3%
 369 faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
 370 PCI slot, G200 in AGP 2x slot. I did not test vgacon::
 371
 372   NOACCEL
 373         8x16                 12x22
 374         Millennium I  G200   Millennium I  G200
 375   8bpp    16.42         9.54   12.33         9.13
 376   16bpp   21.00        15.70   19.11        15.02
 377   24bpp   36.66        36.66   35.00        35.00
 378   32bpp   35.00        30.00   33.85        28.66
 379
 380   ACCEL, nofastfont
 381         8x16                 12x22                6x11
 382         Millennium I  G200   Millennium I  G200   Millennium I  G200
 383   8bpp     7.79         7.24   13.55         7.78   30.00        21.01
 384   16bpp    9.13         7.78   16.16         7.78   30.00        21.01
 385   24bpp   14.17        10.72   18.69        10.24   34.99        21.01
 386   32bpp   16.15      16.16   18.73        13.09   34.99        21.01
 387
 388   ACCEL, fastfont
 389         8x16                 12x22                6x11
 390         Millennium I  G200   Millennium I  G200   Millennium I  G200
 391   8bpp     8.41         6.01    6.54         4.37   16.00        10.51
 392   16bpp    9.54         9.12    8.76         6.17   17.52        14.01
 393   24bpp   15.00        12.36   11.67        10.00   22.01        18.32
 394   32bpp   16.18        18.29*  12.71        12.74   24.44        21.00
 395
 396   TEXT
 397         8x16
 398         Millennium I  G200
 399   TEXT     3.29         1.50
 400
 401   * Yes, it is slower than Millennium I.
 402
 403
 404 Dualhead G400
 405 =============
 406 Driver supports dualhead G400 with some limitations:
 407  + secondary head shares videomemory with primary head. It is not problem
 408    if you have 32MB of videoram, but if you have only 16MB, you may have
 409    to think twice before choosing videomode (for example twice 1880x1440x32bpp
 410    is not possible).
 411  + due to hardware limitation, secondary head can use only 16 and 32bpp
 412    videomodes.
 413  + secondary head is not accelerated. There were bad problems with accelerated
 414    XFree when secondary head used to use acceleration.
 415  + secondary head always powerups in 640x480@60-32 videomode. You have to use
 416    fbset to change this mode.
 417  + secondary head always powerups in monitor mode. You have to use fbmatroxset
 418    to change it to TV mode. Also, you must select at least 525 lines for
 419    NTSC output and 625 lines for PAL output.
 420  + kernel is not fully multihead ready. So some things are impossible to do.
 421  + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
 422    and matroxfb_crtc2 into kernel.
 423
 424
 425 Dualhead G450
 426 =============
 427 Driver supports dualhead G450 with some limitations:
 428  + secondary head shares videomemory with primary head. It is not problem
 429    if you have 32MB of videoram, but if you have only 16MB, you may have
 430    to think twice before choosing videomode.
 431  + due to hardware limitation, secondary head can use only 16 and 32bpp
 432    videomodes.
 433  + secondary head is not accelerated.
 434  + secondary head always powerups in 640x480@60-32 videomode. You have to use
 435    fbset to change this mode.
 436  + TV output is not supported
 437  + kernel is not fully multihead ready, so some things are impossible to do.
 438  + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
 439    into kernel.
 440
 441 Petr Vandrovec <vandrove@vc.cvut.cz>