matroxfb.rst 20 KB

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