
What is vesafb?
===============

Vesafb is a generic framebuffer driver for x86 and x86_64 boxes.

VESA BIOS Extensions Version 2.0 are required, because we need access to
a linear frame buffer. VBE 3.0 is required if you want to use modes with a
higher (than the standard 60Hz) refresh rate.

The VESA framebuffer driver comes in two flavors - the standard 'vesafb'
and 'vesafb-tng'. Vesafb-tng is available only on 32-bit x86 due to the
technology it uses (vm86). Vesafb-tng has more features than vesafb
(adjusting the refresh rate on VBE3.0-compliant boards, switching the
video mode without rebooting, selecting a mode by providing its
modedb name, and more).

Advantages:

 * It provides a nice large console (128 cols + 48 lines with 1024x768)
   without using tiny, unreadable fonts.
 * You can run XF68_FBDev on top of /dev/fb0 (=> non-accelerated X11
   support for every VBE 2.0 compliant graphics board).
 * Most important: boot logo :-)

Disadvantages:

 * graphic mode is slower than text mode...


How to use it?
==============

If you are running a 32-bit x86 system and you decide to use vesafb-tng,
you can either compile the driver into the kernel or use it as a module.
The graphics mode you want to use is in both cases specified using the
standard modedb format.

If your system doesn't support vm86 calls, things get a little more tricky.
Since on such systems you can't do BIOS calls from protected mode in which
kernel runs, you have to decide at boot time whenever you want to run in text
or in graphics mode. Switching mode later on is impossible. Switching modes
is done using the vga=... boot parameter.  Read Documentation/svga.txt for
details. Below is a more detailed description of what to do on systems using
the standard vesafb driver.

You should compile in both vgacon (for text mode) and vesafb (for graphics
mode). Which of them takes over the console depends on whenever the
specified mode is text or graphics.

The graphic modes are NOT in the list which you get if you boot with vga=ask
and hit return. The mode you wish to use is derived from the VESA mode number.
Here are those VESA mode numbers:

    | 640x480  800x600  1024x768 1280x1024
----+-------------------------------------
256 |  0x101    0x103    0x105    0x107
32k |  0x110    0x113    0x116    0x119
64k |  0x111    0x114    0x117    0x11A
16M |  0x112    0x115    0x118    0x11B

The video mode number of the Linux kernel is the VESA mode number plus 0x200.
 
 Linux_kernel_mode_number = VESA_mode_number + 0x200

So the table for the Kernel mode numbers are:

    | 640x480  800x600  1024x768 1280x1024
----+-------------------------------------
256 |  0x301    0x303    0x305    0x307
32k |  0x310    0x313    0x316    0x319
64k |  0x311    0x314    0x317    0x31A
16M |  0x312    0x315    0x318    0x31B

To enable one of those modes you have to specify "vga=ask" in the lilo.conf
file and rerun LILO. Then you can type in the desired mode at the "vga=ask"
prompt. For example if you like to use 1024x768x256 colors you have to say
"305" at this prompt.

If this does not work, this might be because your BIOS does not support
linear framebuffers or because it does not support this mode at all.
Even if your board does, it might be the BIOS which does not.  VESA BIOS
Extensions v2.0 are required, 1.2 is NOT sufficient.  You will get a
"bad mode number" message if something goes wrong.

1. Note: LILO cannot handle hex, for booting directly with
         "vga=mode-number" you have to transform the numbers to decimal.
2. Note: Some newer versions of LILO appear to work with those hex values,
         if you set the 0x in front of the numbers.


X11
===

XF68_FBDev should work just fine, but it is non-accelerated.  Running
another (accelerated) X-Server like XF86_SVGA might or might not work.
It depends on X-Server and graphics board.

The X-Server must restore the video mode correctly, or else you end up
with a broken console (and vesafb cannot do anything about this).
With vesafb-tng chances are that the console will be restored properly
even if the X server messes up the video mode.


Refresh rates
=============

With VBE3.0 compatible BIOSes and vesafb-tng it is possible to change
the refresh rate either at boot time (by specifying the @<rr> part of
the mode name) or later, using the fbset utility.

If you want to use the default BIOS refresh rate while switching modes
on a running system, set pixclock to 0.

With VBE2.0 there is no way to change the mode timings after booting
Linux. If you are not happy with the 60 Hz refresh rate, you have
these options:

 * configure and load the DOS tools for your the graphics board (if
   available) and boot Linux with loadlin.
 * use a native driver (matroxfb/atyfb) instead if vesafb.  If none
   is available, write a new one!
 * use a BIOS editor to change the default refresh rate (such an
   editor does exist at least for ATI Radeon BIOSes).
 * if you're running a non-vm86 and VBE3.0-compatible system, you can
   use a kernel patch (vesafb-rrc) to hard-code some mode timings in
   the kernel and use these while setting the graphic mode at boot time.

Note that there are some boards (nVidia 59**, 57** and newer models)
claiming that their Video BIOS is VBE3.0 compliant, while ignoring the
CRTC values provided by software such as vesafb-tng. You'll not be able
to change the refresh rate if you're using one of these boards.


Configuration
=============

The VESA BIOS provides protected mode interface for changing some parameters.
vesafb can use it for palette changes and to pan the display. It is turned
off by default because it seems not to work with some BIOS versions, but
there are options to turn it on.

You can pass options to vesafb using "video=vesafb:option" on the kernel
command line. Multiple options should be separated by comma, like this:
"video=vesafb:ypan,1024x768-32@85"

Note that vesafb-tng still uses the "video=vesafb:option" format of the
kernel command line video parameter. "video=vesafb-tng:xxx" is incorrect.

Accepted options (both vesafb and vesafb-tng):

ypan    Enable display panning using the VESA protected mode interface
        The visible screen is just a window of the video memory,
        console scrolling is done by changing the start of the window.
        pro:    * scrolling (fullscreen) is fast, because there is
                  no need to copy around data.
                * you'll get scrollback (the Shift-PgUp thing),
                  the video memory can be used as scrollback buffer
        con:    * scrolling only parts of the screen causes some
                  ugly flicker effects (boot logo flickers for
                  example).

ywrap   Same as ypan, but assumes your gfx board can wrap-around the video
        memory (i.e. starts reading from top if it reaches the end of
        video memory). Faster than ypan.

redraw  Scroll by redrawing the affected part of the screen, this is the
        safe (and slow) default.

vgapal  Use the standard VGA registers for palette changes.
        This is the default.

pmipal  Use the protected mode interface for palette changes.

mtrr:n  Setup memory type range registers for the vesafb framebuffer
        where n:
              0 - disabled (equivalent to nomtrr) (default)
              1 - uncachable
              2 - write-back
              3 - write-combining
              4 - write-through

	If you see the following in dmesg, choose the type that matches
        the old one. In this example, use "mtrr:2".
...
mtrr: type mismatch for e0000000,8000000 old: write-back new: write-combining
...

nomtrr  Do not use memory type range registers for vesafb.

vremap:n
        remap 'n' MiB of video RAM. If 0 or not specified, remap memory
        according to video mode. (2.5.66 patch/idea by Antonino Daplas
        reversed to give override possibility (allocate more fb memory
        than the kernel would) to 2.4 by tmb@iki.fi)

vtotal:n
        if the video BIOS of your card incorrectly determines the total
        amount of video RAM, use this option to override the BIOS (in MiB).

Options accepted only by vesafb-tng:

<mode>  The mode you want to set, in the standard modedb format. Refer to
        modedb.txt for detailed description. If you specify a mode that is
        not supported by your board's BIOS, vesafb will attempt to set a
        similar mode. The list of supported modes can be found in
        /proc/fbx/modes, where x is the framebuffer number (usually 0).
        When vesafb is compiled as a module, the mode string should be
        provided as a value of the parameter 'mode'.

vbemode:x
        Force the use of VBE mode x. The mode will only be set if it's
        found in VBE-provided list of supported modes.
        NOTE: The mode number 'x' should be specified in VESA mode number
        notation, not the Linux kernel one (ie. 257 instead of 769).
        HINT: If you use this option because normal <mode> parameter does
        not work for you and you use a X server, you'll probably want to
        set the 'nocrtc' option to ensure that the video mode is properly
        restored after console <-> X switches.

nocrtc  Do not use CRTC timings while setting the graphic mode. This option
        makes sence only with VBE3.0 compliant systems. Use it if you have
        problems with the modes set in the standard way. Note that specifying
        this option means the refresh rate will be ignored and will stay at
        your BIOS default (60 Hz).

noedid  Do not try to fetch and use EDID-provided modes.

gtf     Force the use of VESA's GTF (Generalized Timing Formula). Specifying
        this will cause vesafb to skip it's internal modedb and EDID-modedb
        and jump straight to the GTF part of the code (normally used only if
        everything else failed). This can be useful if you want to get as
        much as possible from you graphics board but your BIOS doesn't
        support modes with refresh rates you require. Note that you may need
        to specify the maxhf, maxvf and maxclk parameters if they are not
        provided by EDID.

Additionally, the following parameters may be provided. They all override the
EDID-provided values and BIOS defaults. Refer to your monitor's specs to get
the correct values for maxhf, maxvf and maxclk for your hardware.

maxhf:n     Maximum horizontal frequency (in kHz).
maxvf:n     Maximum vertical frequency (in Hz).
maxclk:n    Maximum pixel clock (in MHz).

Have fun!

--
Original document for the vesafb driver by
Gerd Knorr <kraxel@goldbach.in-berlin.de>

Minor (mostly typo) changes by
Nico Schmoigl <schmoigl@rumms.uni-mannheim.de>

Extended documentation for vm86, VBE3.0 and vesafb-tng by
Michal Januszewski <spock@gentoo.org>

