Documentation/fb/intel810.rst

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