0001 =================
0002 What is matroxfb?
0003 =================
0004
0005 .. [This file is cloned from VesaFB. Thanks go to Gerd Knorr]
0006
0007
0008 This is a driver for a graphic framebuffer for Matrox devices on
0009 Alpha, Intel and PPC boxes.
0010
0011 Advantages:
0012
0013 * It provides a nice large console (128 cols + 48 lines with 1024x768)
0014 without using tiny, unreadable fonts.
0015 * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
0016 * Most important: boot logo :-)
0017
0018 Disadvantages:
0019
0020 * graphic mode is slower than text mode... but you should not notice
0021 if you use same resolution as you used in textmode.
0022
0023
0024 How to use it?
0025 ==============
0026
0027 Switching modes is done using the video=matroxfb:vesa:... boot parameter
0028 or using `fbset` program.
0029
0030 If you want, for example, enable a resolution of 1280x1024x24bpp you should
0031 pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".
0032
0033 You should compile in both vgacon (to boot if you remove you Matrox from
0034 box) and matroxfb (for graphics mode). You should not compile-in vesafb
0035 unless you have primary display on non-Matrox VBE2.0 device (see
0036 Documentation/fb/vesafb.rst for details).
0037
0038 Currently supported video modes are (through vesa:... interface, PowerMac
0039 has [as addon] compatibility code):
0040
0041
0042 Graphic modes
0043 -------------
0044
0045 === ======= ======= ======= ======= =======
0046 bpp 640x400 640x480 768x576 800x600 960x720
0047 === ======= ======= ======= ======= =======
0048 4 0x12 0x102
0049 8 0x100 0x101 0x180 0x103 0x188
0050 15 0x110 0x181 0x113 0x189
0051 16 0x111 0x182 0x114 0x18A
0052 24 0x1B2 0x184 0x1B5 0x18C
0053 32 0x112 0x183 0x115 0x18B
0054 === ======= ======= ======= ======= =======
0055
0056
0057 Graphic modes (continued)
0058 -------------------------
0059
0060 === ======== ======== ========= ========= =========
0061 bpp 1024x768 1152x864 1280x1024 1408x1056 1600x1200
0062 === ======== ======== ========= ========= =========
0063 4 0x104 0x106
0064 8 0x105 0x190 0x107 0x198 0x11C
0065 15 0x116 0x191 0x119 0x199 0x11D
0066 16 0x117 0x192 0x11A 0x19A 0x11E
0067 24 0x1B8 0x194 0x1BB 0x19C 0x1BF
0068 32 0x118 0x193 0x11B 0x19B
0069 === ======== ======== ========= ========= =========
0070
0071
0072 Text modes
0073 ----------
0074
0075 ==== ======= ======= ======== ======== ========
0076 text 640x400 640x480 1056x344 1056x400 1056x480
0077 ==== ======= ======= ======== ======== ========
0078 8x8 0x1C0 0x108 0x10A 0x10B 0x10C
0079 8x16 2, 3, 7 0x109
0080 ==== ======= ======= ======== ======== ========
0081
0082 You can enter these number either hexadecimal (leading `0x`) or decimal
0083 (0x100 = 256). You can also use value + 512 to achieve compatibility
0084 with your old number passed to vesafb.
0085
0086 Non-listed number can be achieved by more complicated command-line, for
0087 example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32`.
0088
0089
0090 X11
0091 ===
0092
0093 XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
0094 architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
0095 works fine.
0096
0097 Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
0098 XFree servers have big troubles in multihead configurations (even on first
0099 head, not even talking about second). Running XFree86 4.x accelerated mga
0100 driver is possible, but you must not enable DRI - if you do, resolution and
0101 color depth of your X desktop must match resolution and color depths of your
0102 virtual consoles, otherwise X will corrupt accelerator settings.
0103
0104
0105 SVGALib
0106 =======
0107
0108 Driver contains SVGALib compatibility code. It is turned on by choosing textual
0109 mode for console. You can do it at boot time by using videomode
0110 2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0` does this work.
0111 Unfortunately, after SVGALib application exits, screen contents is corrupted.
0112 Switching to another console and back fixes it. I hope that it is SVGALib's
0113 problem and not mine, but I'm not sure.
0114
0115
0116 Configuration
0117 =============
0118
0119 You can pass kernel command line options to matroxfb with
0120 `video=matroxfb:option1,option2:value2,option3` (multiple options should be
0121 separated by comma, values are separated from options by `:`).
0122 Accepted options:
0123
0124 ============ ===================================================================
0125 mem:X size of memory (X can be in megabytes, kilobytes or bytes)
0126 You can only decrease value determined by driver because of
0127 it always probe for memory. Default is to use whole detected
0128 memory usable for on-screen display (i.e. max. 8 MB).
0129 disabled do not load driver; you can use also `off`, but `disabled`
0130 is here too.
0131 enabled load driver, if you have `video=matroxfb:disabled` in LILO
0132 configuration, you can override it by this (you cannot override
0133 `off`). It is default.
0134 noaccel do not use acceleration engine. It does not work on Alphas.
0135 accel use acceleration engine. It is default.
0136 nopan create initial consoles with vyres = yres, thus disabling virtual
0137 scrolling.
0138 pan create initial consoles as tall as possible (vyres = memory/vxres).
0139 It is default.
0140 nopciretry disable PCI retries. It is needed for some broken chipsets,
0141 it is autodetected for intel's 82437. In this case device does
0142 not comply to PCI 2.1 specs (it will not guarantee that every
0143 transaction terminate with success or retry in 32 PCLK).
0144 pciretry enable PCI retries. It is default, except for intel's 82437.
0145 novga disables VGA I/O ports. It is default if BIOS did not enable
0146 device. You should not use this option, some boards then do not
0147 restart without power off.
0148 vga preserve state of VGA I/O ports. It is default. Driver does not
0149 enable VGA I/O if BIOS did not it (it is not safe to enable it in
0150 most cases).
0151 nobios disables BIOS ROM. It is default if BIOS did not enable BIOS
0152 itself. You should not use this option, some boards then do not
0153 restart without power off.
0154 bios preserve state of BIOS ROM. It is default. Driver does not enable
0155 BIOS if BIOS was not enabled before.
0156 noinit tells driver, that devices were already initialized. You should use
0157 it if you have G100 and/or if driver cannot detect memory, you see
0158 strange pattern on screen and so on. Devices not enabled by BIOS
0159 are still initialized. It is default.
0160 init driver initializes every device it knows about.
0161 memtype specifies memory type, implies 'init'. This is valid only for G200
0162 and G400 and has following meaning:
0163
0164 G200:
0165 - 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
0166 - 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
0167 - 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
0168 - 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
0169 - 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
0170 - 5 -> same as above
0171 - 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
0172 - 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
0173 G400:
0174 - 0 -> 2x512Kx16 SDRAM, 16/32MB
0175 - 2x512Kx32 SGRAM, 16/32MB
0176 - 1 -> 2x256Kx32 SGRAM, 8/16MB
0177 - 2 -> 4x128Kx32 SGRAM, 8/16MB
0178 - 3 -> 4x512Kx32 SDRAM, 32MB
0179 - 4 -> 4x256Kx32 SGRAM, 16/32MB
0180 - 5 -> 2x1Mx32 SDRAM, 32MB
0181 - 6 -> reserved
0182 - 7 -> reserved
0183
0184 You should use sdram or sgram parameter in addition to memtype
0185 parameter.
0186 nomtrr disables write combining on frame buffer. This slows down driver
0187 but there is reported minor incompatibility between GUS DMA and
0188 XFree under high loads if write combining is enabled (sound
0189 dropouts).
0190 mtrr enables write combining on frame buffer. It speeds up video
0191 accesses much. It is default. You must have MTRR support enabled
0192 in kernel and your CPU must have MTRR (f.e. Pentium II have them).
0193 sgram tells to driver that you have Gxx0 with SGRAM memory. It has no
0194 effect without `init`.
0195 sdram tells to driver that you have Gxx0 with SDRAM memory.
0196 It is a default.
0197 inv24 change timings parameters for 24bpp modes on Millennium and
0198 Millennium II. Specify this if you see strange color shadows
0199 around characters.
0200 noinv24 use standard timings. It is the default.
0201 inverse invert colors on screen (for LCD displays)
0202 noinverse show true colors on screen. It is default.
0203 dev:X bind driver to device X. Driver numbers device from 0 up to N,
0204 where device 0 is first `known` device found, 1 second and so on.
0205 lspci lists devices in this order.
0206 Default is `every` known device.
0207 nohwcursor disables hardware cursor (use software cursor instead).
0208 hwcursor enables hardware cursor. It is default. If you are using
0209 non-accelerated mode (`noaccel` or `fbset -accel false`), software
0210 cursor is used (except for text mode).
0211 noblink disables cursor blinking. Cursor in text mode always blinks (hw
0212 limitation).
0213 blink enables cursor blinking. It is default.
0214 nofastfont disables fastfont feature. It is default.
0215 fastfont:X enables fastfont feature. X specifies size of memory reserved for
0216 font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
0217 It is faster on Gx00 series, but slower on older cards.
0218 grayscale enable grayscale summing. It works in PSEUDOCOLOR modes (text,
0219 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
0220 displayed through putc/putcs. Direct accesses to framebuffer
0221 can paint colors.
0222 nograyscale disable grayscale summing. It is default.
0223 cross4MB enables that pixel line can cross 4MB boundary. It is default for
0224 non-Millennium.
0225 nocross4MB pixel line must not cross 4MB boundary. It is default for
0226 Millennium I or II, because of these devices have hardware
0227 limitations which do not allow this. But this option is
0228 incompatible with some (if not all yet released) versions of
0229 XF86_FBDev.
0230 dfp enables digital flat panel interface. This option is incompatible
0231 with secondary (TV) output - if DFP is active, TV output must be
0232 inactive and vice versa. DFP always uses same timing as primary
0233 (monitor) output.
0234 dfp:X use settings X for digital flat panel interface. X is number from
0235 0 to 0xFF, and meaning of each individual bit is described in
0236 G400 manual, in description of DAC register 0x1F. For normal
0237 operation you should set all bits to zero, except lowest bit. This
0238 lowest bit selects who is source of display clocks, whether G400,
0239 or panel. Default value is now read back from hardware - so you
0240 should specify this value only if you are also using `init`
0241 parameter.
0242 outputs:XYZ set mapping between CRTC and outputs. Each letter can have value
0243 of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter
0244 corresponds to primary analog output, second letter to the
0245 secondary analog output and third letter to the DVI output.
0246 Default setting is 100 for cards below G400 or G400 without DFP,
0247 101 for G400 with DFP, and 111 for G450 and G550. You can set
0248 mapping only on first card, use matroxset for setting up other
0249 devices.
0250 vesa:X selects startup videomode. X is number from 0 to 0x1FF, see table
0251 above for detailed explanation. Default is 640x480x8bpp if driver
0252 has 8bpp support. Otherwise first available of 640x350x4bpp,
0253 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
0254 (80x25 text is always available).
0255 ============ ===================================================================
0256
0257 If you are not satisfied with videomode selected by `vesa` option, you
0258 can modify it with these options:
0259
0260 ============ ===================================================================
0261 xres:X horizontal resolution, in pixels. Default is derived from `vesa`
0262 option.
0263 yres:X vertical resolution, in pixel lines. Default is derived from `vesa`
0264 option.
0265 upper:X top boundary: lines between end of VSYNC pulse and start of first
0266 pixel line of picture. Default is derived from `vesa` option.
0267 lower:X bottom boundary: lines between end of picture and start of VSYNC
0268 pulse. Default is derived from `vesa` option.
0269 vslen:X length of VSYNC pulse, in lines. Default is derived from `vesa`
0270 option.
0271 left:X left boundary: pixels between end of HSYNC pulse and first pixel.
0272 Default is derived from `vesa` option.
0273 right:X right boundary: pixels between end of picture and start of HSYNC
0274 pulse. Default is derived from `vesa` option.
0275 hslen:X length of HSYNC pulse, in pixels. Default is derived from `vesa`
0276 option.
0277 pixclock:X dotclocks, in ps (picoseconds). Default is derived from `vesa`
0278 option and from `fh` and `fv` options.
0279 sync:X sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
0280 If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
0281 generated. If bit 5 (value 0x20) is set, sync on green is turned
0282 on. Do not forget that if you want sync on green, you also probably
0283 want composite sync.
0284 Default depends on `vesa`.
0285 depth:X Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
0286 `vesa`.
0287 ============ ===================================================================
0288
0289 If you know capabilities of your monitor, you can specify some (or all) of
0290 `maxclk`, `fh` and `fv`. In this case, `pixclock` is computed so that
0291 pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
0292
0293 ============ ==================================================================
0294 maxclk:X maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
0295 `don`t care`.
0296 fh:X maximum horizontal synchronization frequency. X can be specified
0297 in kHz or Hz. Default is `don't care`.
0298 fv:X maximum vertical frequency. X must be specified in Hz. Default is
0299 70 for modes derived from `vesa` with yres <= 400, 60Hz for
0300 yres > 400.
0301 ============ ==================================================================
0302
0303
0304 Limitations
0305 ===========
0306
0307 There are known and unknown bugs, features and misfeatures.
0308 Currently there are following known bugs:
0309
0310 - SVGALib does not restore screen on exit
0311 - generic fbcon-cfbX procedures do not work on Alphas. Due to this,
0312 `noaccel` (and cfb4 accel) driver does not work on Alpha. So everyone
0313 with access to `/dev/fb*` on Alpha can hang machine (you should restrict
0314 access to `/dev/fb*` - everyone with access to this device can destroy
0315 your monitor, believe me...).
0316 - 24bpp does not support correctly XF-FBDev on big-endian architectures.
0317 - interlaced text mode is not supported; it looks like hardware limitation,
0318 but I'm not sure.
0319 - Gxx0 SGRAM/SDRAM is not autodetected.
0320 - maybe more...
0321
0322 And following misfeatures:
0323
0324 - SVGALib does not restore screen on exit.
0325 - pixclock for text modes is limited by hardware to
0326
0327 - 83 MHz on G200
0328 - 66 MHz on Millennium I
0329 - 60 MHz on Millennium II
0330
0331 Because I have no access to other devices, I do not know specific
0332 frequencies for them. So driver does not check this and allows you to
0333 set frequency higher that this. It causes sparks, black holes and other
0334 pretty effects on screen. Device was not destroyed during tests. :-)
0335 - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
0336 (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
0337 But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
0338 them (maybe that chip overheats, but it has a very big cooler (G100 has
0339 none), so it should work).
0340 - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
0341 G16V16 are not supported
0342 - color keying is not supported
0343 - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
0344 by BIOS)
0345 - DDC (monitor detection) is supported through dualhead driver
0346 - some check for input values are not so strict how it should be (you can
0347 specify vslen=4000 and so on).
0348 - maybe more...
0349
0350 And following features:
0351
0352 - 4bpp is available only on Millennium I and Millennium II. It is hardware
0353 limitation.
0354 - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
0355 option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
0356 else selects 5:6:5 mode.
0357 - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
0358 instead of one of 16M colors). It is due to hardware limitation of
0359 Millennium I/II and SVGALib compatibility.
0360
0361
0362 Benchmarks
0363 ==========
0364 It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
0365 time for draw 6144000 characters on screen through /dev/vcsa
0366 (for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
0367 16 seconds, i.e. 187 MBps).
0368 Times were obtained from one older version of driver, now they are about 3%
0369 faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
0370 PCI slot, G200 in AGP 2x slot. I did not test vgacon::
0371
0372 NOACCEL
0373 8x16 12x22
0374 Millennium I G200 Millennium I G200
0375 8bpp 16.42 9.54 12.33 9.13
0376 16bpp 21.00 15.70 19.11 15.02
0377 24bpp 36.66 36.66 35.00 35.00
0378 32bpp 35.00 30.00 33.85 28.66
0379
0380 ACCEL, nofastfont
0381 8x16 12x22 6x11
0382 Millennium I G200 Millennium I G200 Millennium I G200
0383 8bpp 7.79 7.24 13.55 7.78 30.00 21.01
0384 16bpp 9.13 7.78 16.16 7.78 30.00 21.01
0385 24bpp 14.17 10.72 18.69 10.24 34.99 21.01
0386 32bpp 16.15 16.16 18.73 13.09 34.99 21.01
0387
0388 ACCEL, fastfont
0389 8x16 12x22 6x11
0390 Millennium I G200 Millennium I G200 Millennium I G200
0391 8bpp 8.41 6.01 6.54 4.37 16.00 10.51
0392 16bpp 9.54 9.12 8.76 6.17 17.52 14.01
0393 24bpp 15.00 12.36 11.67 10.00 22.01 18.32
0394 32bpp 16.18 18.29* 12.71 12.74 24.44 21.00
0395
0396 TEXT
0397 8x16
0398 Millennium I G200
0399 TEXT 3.29 1.50
0400
0401 * Yes, it is slower than Millennium I.
0402
0403
0404 Dualhead G400
0405 =============
0406 Driver supports dualhead G400 with some limitations:
0407 + secondary head shares videomemory with primary head. It is not problem
0408 if you have 32MB of videoram, but if you have only 16MB, you may have
0409 to think twice before choosing videomode (for example twice 1880x1440x32bpp
0410 is not possible).
0411 + due to hardware limitation, secondary head can use only 16 and 32bpp
0412 videomodes.
0413 + secondary head is not accelerated. There were bad problems with accelerated
0414 XFree when secondary head used to use acceleration.
0415 + secondary head always powerups in 640x480@60-32 videomode. You have to use
0416 fbset to change this mode.
0417 + secondary head always powerups in monitor mode. You have to use fbmatroxset
0418 to change it to TV mode. Also, you must select at least 525 lines for
0419 NTSC output and 625 lines for PAL output.
0420 + kernel is not fully multihead ready. So some things are impossible to do.
0421 + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
0422 and matroxfb_crtc2 into kernel.
0423
0424
0425 Dualhead G450
0426 =============
0427 Driver supports dualhead G450 with some limitations:
0428 + secondary head shares videomemory with primary head. It is not problem
0429 if you have 32MB of videoram, but if you have only 16MB, you may have
0430 to think twice before choosing videomode.
0431 + due to hardware limitation, secondary head can use only 16 and 32bpp
0432 videomodes.
0433 + secondary head is not accelerated.
0434 + secondary head always powerups in 640x480@60-32 videomode. You have to use
0435 fbset to change this mode.
0436 + TV output is not supported
0437 + kernel is not fully multihead ready, so some things are impossible to do.
0438 + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
0439 into kernel.
0440
0441 Petr Vandrovec <vandrove@vc.cvut.cz>
