Linux-2.6.12-rc2
[linux-3.10.git] / Documentation / fb / intel810.txt
1 Intel 810/815 Framebuffer driver
2         Tony Daplas <adaplas@pol.net>
3         http://i810fb.sourceforge.net
4
5         March 17, 2002
6
7         First Released: July 2001
8 ================================================================
9
10 A. Introduction
11         This is a framebuffer driver for various Intel 810/815 compatible
12 graphics devices.  These would include:
13
14         Intel 810
15         Intel 810E
16         Intel 810-DC100
17         Intel 815 Internal graphics only, 100Mhz FSB
18         Intel 815 Internal graphics only
19         Intel 815 Internal graphics and AGP
20
21 B.  Features
22
23         - Choice of using Discrete Video Timings, VESA Generalized Timing
24           Formula, or a framebuffer specific database to set the video mode
25
26         - Supports a variable range of horizontal and vertical resolution, and
27           vertical refresh rates if the VESA Generalized Timing Formula is 
28           enabled.
29
30         - Supports color depths of 8, 16, 24 and 32 bits per pixel
31
32         - Supports pseudocolor, directcolor, or truecolor visuals
33
34         - Full and optimized hardware acceleration at 8, 16 and 24 bpp
35
36         - Robust video state save and restore
37
38         - MTRR support 
39
40         - Utilizes user-entered monitor specifications to automatically
41           calculate required video mode parameters.
42
43         - Can concurrently run with xfree86 running with native i810 drivers 
44
45         - Hardware Cursor Support
46  
47 C.  List of available options
48         
49    a. "video=i810fb"  
50         enables the i810 driver
51
52         Recommendation: required
53  
54    b. "xres:<value>"  
55         select horizontal resolution in pixels
56
57         Recommendation: user preference 
58         (default = 640)
59
60    c. "yres:<value>"
61         select vertical resolution in scanlines. If Discrete Video Timings
62         is enabled, this will be ignored and computed as 3*xres/4.  
63
64         Recommendation: user preference
65         (default = 480)
66                 
67    d. "vyres:<value>" 
68         select virtual vertical resolution in scanlines. If (0) or none
69         is specified, this will be computed against maximum available memory. 
70
71         Recommendation: do not set
72         (default = 480)
73
74    e. "vram:<value>"
75         select amount of system RAM in MB to allocate for the video memory 
76
77         Recommendation: 1 - 4 MB.
78         (default = 4)
79
80    f. "bpp:<value>"   
81         select desired pixel depth 
82
83         Recommendation: 8
84         (default = 8)
85
86    g. "hsync1/hsync2:<value>" 
87         select the minimum and maximum Horizontal Sync Frequency of the 
88         monitor in KHz.  If a using a fixed frequency monitor, hsync1 must 
89         be equal to hsync2. 
90
91         Recommendation: check monitor manual for correct values
92         default (29/30)
93
94    h. "vsync1/vsync2:<value>" 
95         select the minimum and maximum Vertical Sync Frequency of the monitor
96         in Hz. You can also use this option to lock your monitor's refresh 
97         rate.
98
99         Recommendation: check monitor manual for correct values
100         (default = 60/60)
101
102         IMPORTANT:  If you need to clamp your timings, try to give some 
103         leeway for computational errors (over/underflows).  Example: if 
104         using vsync1/vsync2 = 60/60, make sure hsync1/hsync2 has at least
105         a 1 unit difference, and vice versa.
106
107    i. "voffset:<value>" 
108         select at what offset in MB of the logical memory to allocate the 
109         framebuffer memory.  The intent is to avoid the memory blocks
110         used by standard graphics applications (XFree86).  The default
111         offset (16 MB for a 64MB aperture, 8 MB for a 32MB aperture) will
112         avoid XFree86's usage and allows up to 7MB/15MB of framebuffer
113         memory.  Depending on your usage, adjust the value up or down, 
114         (0 for maximum usage, 31/63 MB for the least amount).  Note, an 
115         arbitrary setting may conflict with XFree86.
116
117         Recommendation: do not set
118         (default = 8 or 16 MB)
119       
120    j. "accel" 
121         enable text acceleration.  This can be enabled/reenabled anytime 
122         by using 'fbset -accel true/false'. 
123
124         Recommendation: enable
125         (default = not set) 
126
127    k. "mtrr" 
128         enable MTRR.  This allows data transfers to the framebuffer memory
129         to occur in bursts which can significantly increase performance.
130         Not very helpful with the i810/i815 because of 'shared memory'. 
131
132         Recommendation: do not set
133         (default = not set) 
134
135    l. "extvga"
136         if specified, secondary/external VGA output will always be enabled.
137         Useful if the BIOS turns off the VGA port when no monitor is attached.
138         The external VGA monitor can then be attached without rebooting. 
139
140         Recommendation: do not set
141         (default = not set)
142         
143    m. "sync" 
144         Forces the hardware engine to do a "sync" or wait for the hardware
145         to finish before starting another instruction. This will produce a 
146         more stable setup, but will be slower.
147
148         Recommendation: do not set
149         (default = not set)
150
151    n. "dcolor"
152         Use directcolor visual instead of truecolor for pixel depths greater
153         than 8 bpp.  Useful for color tuning, such as gamma control.
154
155         Recommendation: do not set
156         (default = not set)
157                         
158 D. Kernel booting
159
160 Separate each option/option-pair by commas (,) and the option from its value
161 with a colon (:) as in the following:
162
163 video=i810fb:option1,option2:value2
164
165 Sample Usage
166 ------------
167
168 In /etc/lilo.conf, add the line:
169
170 append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
171         vsync1:50,vsync2:85,accel,mtrr"
172
173 This will initialize the framebuffer to 1024x768 at 8bpp.  The framebuffer
174 will use 2 MB of System RAM. MTRR support will be enabled. The refresh rate 
175 will be computed based on the hsync1/hsync2 and vsync1/vsync2 values.  
176
177 IMPORTANT:
178 You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
179 better than 640x480 at 60Hz.
180
181 E.  Module options
182         
183         The module parameters are essentially similar to the kernel 
184 parameters. The main difference is that you need to include a Boolean value 
185 (1 for TRUE, and 0 for FALSE) for those options which don't need a value. 
186
187 Example, to enable MTRR, include "mtrr=1".
188
189 Sample Usage
190 ------------
191
192 Using the same setup as described above, load the module like this:
193
194         modprobe i810fb vram=2 xres=1024 bpp=8 hsync1=30 hsync2=55 vsync1=50 \
195                  vsync2=85 accel=1 mtrr=1
196
197 Or just add the following to /etc/modprobe.conf
198
199         options i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 \
200         vsync2=85 accel=1 mtrr=1
201
202 and just do a 
203
204         modprobe i810fb
205
206
207 F.  Setup
208
209         a. Do your usual method of configuring the kernel. 
210         
211         make menuconfig/xconfig/config
212
213         b. Under "Code Maturity Options", enable "Prompt for experimental/
214            incomplete code/drivers".
215
216         c. Enable agpgart support for the Intel 810/815 on-board graphics.
217            This is required.  The option is under "Character Devices"
218
219         d. Under "Graphics Support", select "Intel 810/815" either statically
220            or as a module.  Choose "use VESA GTF for video timings"  if you 
221            need to maximize the capability of your display.  To be on the 
222            safe side, you can leave this unselected.  
223   
224         e. If you want a framebuffer console, enable it under "Console 
225            Drivers"
226
227         f. Compile your kernel. 
228                 
229         g. Load the driver as described in section D and E.
230         
231         Optional:       
232         h.  If you are going to run XFree86 with its native drivers, the 
233             standard XFree86 4.1.0 and 4.2.0 drivers should work as is.
234             However, there's a bug in the XFree86 i810 drivers.  It attempts 
235             to use XAA even when switched to the console. This will crash
236             your server. I have a fix at this site:  
237             
238             http://i810fb.sourceforge.net.  
239
240             You can either use the patch, or just replace 
241             
242             /usr/X11R6/lib/modules/drivers/i810_drv.o
243
244             with the one provided at the website.       
245
246         i.  Try the DirectFB (http://www.directfb.org) + the i810 gfxdriver
247             patch to see the chipset in action (or inaction :-).
248
249 G.  Acknowledgment:
250         
251         1.  Geert Uytterhoeven - his excellent howto and the virtual
252                                  framebuffer driver code made this possible.
253
254         2.  Jeff Hartmann for his agpgart code.  
255
256         3.  The X developers.  Insights were provided just by reading the
257             XFree86 source code.
258
259         4.  Intel(c).  For this value-oriented chipset driver and for
260             providing documentation.
261
262         5. Matt Sottek.  His inputs and ideas  helped in making some
263         optimizations possible.
264
265 H.  Home Page:
266
267         A more complete, and probably updated information is provided at
268 http://i810fb.sourceforge.net.
269
270 ###########################
271 Tony
272