kernel/linux/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