About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / fb / matroxfb.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

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 Millennium and
181	           Millennium 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.
190	nohwcursor - disables hardware cursor (use software cursor instead).
191	hwcursor - enables hardware cursor. It is default. If you are using
192	           non-accelerated mode (`noaccel' or `fbset -accel false'), software
193		   cursor is used (except for text mode).
194	noblink  - disables cursor blinking. Cursor in text mode always blinks (hw
195	           limitation).
196	blink    - enables cursor blinking. It is default.
197	nofastfont - disables fastfont feature. It is default.
198	fastfont:X - enables fastfont feature. X specifies size of memory reserved for
199	             font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
200		     It is faster on Gx00 series, but slower on older cards.
201	grayscale - enable grayscale summing. It works in PSEUDOCOLOR modes (text,
202	            4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
203		    displayed through putc/putcs. Direct accesses to framebuffer
204		    can paint colors.
205	nograyscale - disable grayscale summing. It is default.
206	cross4MB - enables that pixel line can cross 4MB boundary. It is default for
207	           non-Millennium.
208	nocross4MB - pixel line must not cross 4MB boundary. It is default for
209	             Millennium I or II, because of these devices have hardware
210		     limitations which do not allow this. But this option is
211		     incompatible with some (if not all yet released) versions of
212		     XF86_FBDev.
213	dfp      - enables digital flat panel interface. This option is incompatible with
214	           secondary (TV) output - if DFP is active, TV output must be
215		   inactive and vice versa. DFP always uses same timing as primary
216		   (monitor) output.
217	dfp:X    - use settings X for digital flat panel interface. X is number from
218	           0 to 0xFF, and meaning of each individual bit is described in
219		   G400 manual, in description of DAC register 0x1F. For normal operation
220		   you should set all bits to zero, except lowest bit. This lowest bit
221		   selects who is source of display clocks, whether G400, or panel.
222		   Default value is now read back from hardware - so you should specify
223		   this value only if you are also using `init' parameter.
224	outputs:XYZ - set mapping between CRTC and outputs. Each letter can have value
225	           of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter corresponds
226		   to primary analog output, second letter to the secondary analog output
227		   and third letter to the DVI output. Default setting is 100 for
228		   cards below G400 or G400 without DFP, 101 for G400 with DFP, and
229		   111 for G450 and G550. You can set mapping only on first card,
230		   use matroxset for setting up other devices.
231	vesa:X   - selects startup videomode. X is number from 0 to 0x1FF, see table
232	           above for detailed explanation. Default is 640x480x8bpp if driver
233		   has 8bpp support. Otherwise first available of 640x350x4bpp,
234		   640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
235		   (80x25 text is always available).
236	
237	If you are not satisfied with videomode selected by `vesa' option, you
238	can modify it with these options:
239	
240	xres:X   - horizontal resolution, in pixels. Default is derived from `vesa'
241	           option.
242	yres:X   - vertical resolution, in pixel lines. Default is derived from `vesa'
243	           option.
244	upper:X  - top boundary: lines between end of VSYNC pulse and start of first
245	           pixel line of picture. Default is derived from `vesa' option.
246	lower:X  - bottom boundary: lines between end of picture and start of VSYNC
247	           pulse. Default is derived from `vesa' option.
248	vslen:X  - length of VSYNC pulse, in lines. Default is derived from `vesa'
249	           option.
250	left:X   - left boundary: pixels between end of HSYNC pulse and first pixel.
251	           Default is derived from `vesa' option.
252	right:X  - right boundary: pixels between end of picture and start of HSYNC
253	           pulse. Default is derived from `vesa' option.
254	hslen:X  - length of HSYNC pulse, in pixels. Default is derived from `vesa'
255	           option.
256	pixclock:X - dotclocks, in ps (picoseconds). Default is derived from `vesa'
257	             option and from `fh' and `fv' options.
258	sync:X   - sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
259	           If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
260		   generated. If bit 5 (value 0x20) is set, sync on green is turned on.
261		   Do not forget that if you want sync on green, you also probably
262		   want composite sync.
263		   Default depends on `vesa'.
264	depth:X  - Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
265	           `vesa'.
266	
267	If you know capabilities of your monitor, you can specify some (or all) of
268	`maxclk', `fh' and `fv'. In this case, `pixclock' is computed so that
269	pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
270	
271	maxclk:X - maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
272	           `don't care'.
273	fh:X     - maximum horizontal synchronization frequency. X can be specified
274	           in kHz or Hz. Default is `don't care'.
275	fv:X     - maximum vertical frequency. X must be specified in Hz. Default is
276	           70 for modes derived from `vesa' with yres <= 400, 60Hz for
277		   yres > 400.
278	
279	
280	Limitations
281	===========
282	
283	There are known and unknown bugs, features and misfeatures.
284	Currently there are following known bugs:
285	 + SVGALib does not restore screen on exit
286	 + generic fbcon-cfbX procedures do not work on Alphas. Due to this,
287	   `noaccel' (and cfb4 accel) driver does not work on Alpha. So everyone
288	   with access to /dev/fb* on Alpha can hang machine (you should restrict
289	   access to /dev/fb* - everyone with access to this device can destroy
290	   your monitor, believe me...).
291	 + 24bpp does not support correctly XF-FBDev on big-endian architectures.
292	 + interlaced text mode is not supported; it looks like hardware limitation,
293	   but I'm not sure.
294	 + Gxx0 SGRAM/SDRAM is not autodetected.
295	 + If you are using more than one framebuffer device, you must boot kernel
296	   with 'video=scrollback:0'.
297	 + maybe more...
298	And following misfeatures:
299	 + SVGALib does not restore screen on exit.
300	 + pixclock for text modes is limited by hardware to
301	    83 MHz on G200
302	    66 MHz on Millennium I
303	    60 MHz on Millennium II
304	   Because I have no access to other devices, I do not know specific
305	   frequencies for them. So driver does not check this and allows you to
306	   set frequency higher that this. It causes sparks, black holes and other
307	   pretty effects on screen. Device was not destroyed during tests. :-)
308	 + my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
309	   (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
310	   But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
311	   them (maybe that chip overheats, but it has a very big cooler (G100 has
312	   none), so it should work).
313	 + special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
314	   G16V16 are not supported
315	 + color keying is not supported
316	 + feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
317	   by BIOS)
318	 + DDC (monitor detection) is supported through dualhead driver
319	 + some check for input values are not so strict how it should be (you can
320	   specify vslen=4000 and so on).
321	 + maybe more...
322	And following features:
323	 + 4bpp is available only on Millennium I and Millennium II. It is hardware
324	   limitation.
325	 + selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba 
326	   option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
327	   else selects 5:6:5 mode.
328	 + text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
329	   instead of one of 16M colors). It is due to hardware limitation of 
330	   Millennium I/II and SVGALib compatibility.
331	
332	
333	Benchmarks
334	==========
335	It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
336	time for draw 6144000 characters on screen through /dev/vcsa
337	(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in 
338	16 seconds, i.e. 187 MBps).
339	Times were obtained from one older version of driver, now they are about 3%
340	faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
341	PCI slot, G200 in AGP 2x slot. I did not test vgacon.
342	
343	NOACCEL
344	        8x16                 12x22
345	        Millennium I  G200   Millennium I  G200
346	8bpp    16.42         9.54   12.33         9.13
347	16bpp   21.00        15.70   19.11        15.02
348	24bpp   36.66        36.66   35.00        35.00
349	32bpp   35.00        30.00   33.85        28.66
350	
351	ACCEL, nofastfont
352	        8x16                 12x22                6x11
353		Millennium I  G200   Millennium I  G200   Millennium I  G200
354	8bpp     7.79         7.24   13.55         7.78   30.00        21.01
355	16bpp    9.13         7.78   16.16         7.78   30.00        21.01
356	24bpp   14.17        10.72   18.69        10.24   34.99        21.01
357	32bpp   16.15	     16.16   18.73        13.09   34.99        21.01
358	
359	ACCEL, fastfont
360	        8x16                 12x22                6x11
361		Millennium I  G200   Millennium I  G200   Millennium I  G200
362	8bpp     8.41         6.01    6.54         4.37   16.00        10.51
363	16bpp    9.54         9.12    8.76         6.17   17.52        14.01
364	24bpp   15.00        12.36   11.67        10.00   22.01        18.32
365	32bpp   16.18        18.29*  12.71        12.74   24.44        21.00
366	
367	TEXT
368	        8x16
369		Millennium I  G200
370	TEXT     3.29         1.50
371	
372	* Yes, it is slower than Millennium I.
373	
374	
375	Dualhead G400
376	=============
377	Driver supports dualhead G400 with some limitations:
378	 + secondary head shares videomemory with primary head. It is not problem
379	   if you have 32MB of videoram, but if you have only 16MB, you may have
380	   to think twice before choosing videomode (for example twice 1880x1440x32bpp
381	   is not possible).
382	 + due to hardware limitation, secondary head can use only 16 and 32bpp
383	   videomodes.
384	 + secondary head is not accelerated. There were bad problems with accelerated
385	   XFree when secondary head used to use acceleration.
386	 + secondary head always powerups in 640x480@60-32 videomode. You have to use
387	   fbset to change this mode.
388	 + secondary head always powerups in monitor mode. You have to use fbmatroxset
389	   to change it to TV mode. Also, you must select at least 525 lines for
390	   NTSC output and 625 lines for PAL output.
391	 + kernel is not fully multihead ready. So some things are impossible to do.
392	 + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
393	   and matroxfb_crtc2 into kernel.
394	
395	
396	Dualhead G450
397	=============
398	Driver supports dualhead G450 with some limitations:
399	 + secondary head shares videomemory with primary head. It is not problem
400	   if you have 32MB of videoram, but if you have only 16MB, you may have
401	   to think twice before choosing videomode.
402	 + due to hardware limitation, secondary head can use only 16 and 32bpp
403	   videomodes.
404	 + secondary head is not accelerated.
405	 + secondary head always powerups in 640x480@60-32 videomode. You have to use
406	   fbset to change this mode.
407	 + TV output is not supported
408	 + kernel is not fully multihead ready, so some things are impossible to do.
409	 + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
410	   into kernel.
411		
412	--
413	Petr Vandrovec <vandrove@vc.cvut.cz>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.