[linux-block.git] / Documentation / fb / vesafb.rst

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

This is a generic driver for a graphic framebuffer on intel boxes.

The idea is simple:  Turn on graphics mode at boot time with the help
of the BIOS, and use this as framebuffer device /dev/fb0, like the m68k
(and other) ports do.

This means we decide at boot time whenever we want to run in text or
graphics mode.  Switching mode later on (in protected mode) is
impossible; BIOS calls work in real mode only.  VESA BIOS Extensions
Version 2.0 are required, because we need a linear frame buffer.

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?
==============

Switching modes is done using the vga=... boot parameter.  Read
Documentation/admin-guide/svga.rst for details.

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:

====== =======  =======  ======== =========
colors 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:

====== =======  =======  ======== =========
colors 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, else you end up
with a broken console (and vesafb cannot do anything about this).


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

There is no way to change the vesafb video mode and/or 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 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!
 * VBE 3.0 might work too.  I have neither a gfx board with VBE 3.0
   support nor the specs, so I have not checked this yet.


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,inverse"

Accepted options:

inverse	use inverse color map

========= ======================================================================
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.

          kontra:

		* 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    disable mtrr

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).
========= ======================================================================

Have fun!

Gerd Knorr <kraxel@goldbach.in-berlin.de>

Minor (mostly typo) changes
by Nico Schmoigl <schmoigl@rumms.uni-mannheim.de>
Commit	Line	Data
	1	===============
	2	What is vesafb?
	3	===============
	4
	5	This is a generic driver for a graphic framebuffer on intel boxes.
	6
	7	The idea is simple: Turn on graphics mode at boot time with the help
	8	of the BIOS, and use this as framebuffer device /dev/fb0, like the m68k
	9	(and other) ports do.
	10
	11	This means we decide at boot time whenever we want to run in text or
	12	graphics mode. Switching mode later on (in protected mode) is
	13	impossible; BIOS calls work in real mode only. VESA BIOS Extensions
	14	Version 2.0 are required, because we need a linear frame buffer.
	15
	16	Advantages:
	17
	18	* It provides a nice large console (128 cols + 48 lines with 1024x768)
	19	without using tiny, unreadable fonts.
	20	* You can run XF68_FBDev on top of /dev/fb0 (=> non-accelerated X11
	21	support for every VBE 2.0 compliant graphics board).
	22	* Most important: boot logo :-)
	23
	24	Disadvantages:
	25
	26	* graphic mode is slower than text mode...
	27
	28
	29	How to use it?
	30	==============
	31
	32	Switching modes is done using the vga=... boot parameter. Read
	33	Documentation/admin-guide/svga.rst for details.
	34
	35	You should compile in both vgacon (for text mode) and vesafb (for
	36	graphics mode). Which of them takes over the console depends on
	37	whenever the specified mode is text or graphics.
	38
	39	The graphic modes are NOT in the list which you get if you boot with
	40	vga=ask and hit return. The mode you wish to use is derived from the
	41	VESA mode number. Here are those VESA mode numbers:
	42
	43	====== ======= ======= ======== =========
	44	colors 640x480 800x600 1024x768 1280x1024
	45	====== ======= ======= ======== =========
	46	256 0x101 0x103 0x105 0x107
	47	32k 0x110 0x113 0x116 0x119
	48	64k 0x111 0x114 0x117 0x11A
	49	16M 0x112 0x115 0x118 0x11B
	50	====== ======= ======= ======== =========
	51
	52
	53	The video mode number of the Linux kernel is the VESA mode number plus
	54	0x200:
	55
	56	Linux_kernel_mode_number = VESA_mode_number + 0x200
	57
	58	So the table for the Kernel mode numbers are:
	59
	60	====== ======= ======= ======== =========
	61	colors 640x480 800x600 1024x768 1280x1024
	62	====== ======= ======= ======== =========
	63	256 0x301 0x303 0x305 0x307
	64	32k 0x310 0x313 0x316 0x319
	65	64k 0x311 0x314 0x317 0x31A
	66	16M 0x312 0x315 0x318 0x31B
	67	====== ======= ======= ======== =========
	68
	69	To enable one of those modes you have to specify "vga=ask" in the
	70	lilo.conf file and rerun LILO. Then you can type in the desired
	71	mode at the "vga=ask" prompt. For example if you like to use
	72	1024x768x256 colors you have to say "305" at this prompt.
	73
	74	If this does not work, this might be because your BIOS does not support
	75	linear framebuffers or because it does not support this mode at all.
	76	Even if your board does, it might be the BIOS which does not. VESA BIOS
	77	Extensions v2.0 are required, 1.2 is NOT sufficient. You will get a
	78	"bad mode number" message if something goes wrong.
	79
	80	1. Note: LILO cannot handle hex, for booting directly with
	81	"vga=mode-number" you have to transform the numbers to decimal.
	82	2. Note: Some newer versions of LILO appear to work with those hex values,
	83	if you set the 0x in front of the numbers.
	84
	85	X11
	86	===
	87
	88	XF68_FBDev should work just fine, but it is non-accelerated. Running
	89	another (accelerated) X-Server like XF86_SVGA might or might not work.
	90	It depends on X-Server and graphics board.
	91
	92	The X-Server must restore the video mode correctly, else you end up
	93	with a broken console (and vesafb cannot do anything about this).
	94
	95
	96	Refresh rates
	97	=============
	98
	99	There is no way to change the vesafb video mode and/or timings after
	100	booting linux. If you are not happy with the 60 Hz refresh rate, you
	101	have these options:
	102
	103	* configure and load the DOS-Tools for the graphics board (if
	104	available) and boot linux with loadlin.
	105	* use a native driver (matroxfb/atyfb) instead if vesafb. If none
	106	is available, write a new one!
	107	* VBE 3.0 might work too. I have neither a gfx board with VBE 3.0
	108	support nor the specs, so I have not checked this yet.
	109
	110
	111	Configuration
	112	=============
	113
	114	The VESA BIOS provides protected mode interface for changing
	115	some parameters. vesafb can use it for palette changes and
	116	to pan the display. It is turned off by default because it
	117	seems not to work with some BIOS versions, but there are options
	118	to turn it on.
	119
	120	You can pass options to vesafb using "video=vesafb:option" on
	121	the kernel command line. Multiple options should be separated
	122	by comma, like this: "video=vesafb:ypan,inverse"
	123
	124	Accepted options:
	125
	126	inverse use inverse color map
	127
	128	========= ======================================================================
	129	ypan enable display panning using the VESA protected mode
	130	interface. The visible screen is just a window of the
	131	video memory, console scrolling is done by changing the
	132	start of the window.
	133
	134	pro:
	135
	136	* scrolling (fullscreen) is fast, because there is
	137	no need to copy around data.
	138
	139	kontra:
	140
	141	* scrolling only parts of the screen causes some
	142	ugly flicker effects (boot logo flickers for
	143	example).
	144
	145	ywrap Same as ypan, but assumes your gfx board can wrap-around
	146	the video memory (i.e. starts reading from top if it
	147	reaches the end of video memory). Faster than ypan.
	148
	149	redraw Scroll by redrawing the affected part of the screen, this
	150	is the safe (and slow) default.
	151
	152
	153	vgapal Use the standard vga registers for palette changes.
	154	This is the default.
	155	pmipal Use the protected mode interface for palette changes.
	156
	157	mtrr:n Setup memory type range registers for the vesafb framebuffer
	158	where n:
	159
	160	- 0 - disabled (equivalent to nomtrr) (default)
	161	- 1 - uncachable
	162	- 2 - write-back
	163	- 3 - write-combining
	164	- 4 - write-through
	165
	166	If you see the following in dmesg, choose the type that matches the
	167	old one. In this example, use "mtrr:2".
	168	...
	169	mtrr: type mismatch for e0000000,8000000 old: write-back new:
	170	write-combining
	171	...
	172
	173	nomtrr disable mtrr
	174
	175	vremap:n
	176	Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
	177	according to video mode. (2.5.66 patch/idea by Antonino Daplas
	178	reversed to give override possibility (allocate more fb memory
	179	than the kernel would) to 2.4 by tmb@iki.fi)
	180
	181	vtotal:n If the video BIOS of your card incorrectly determines the total
	182	amount of video RAM, use this option to override the BIOS (in MiB).
	183	========= ======================================================================
	184
	185	Have fun!
	186
	187	Gerd Knorr <kraxel@goldbach.in-berlin.de>
	188
	189	Minor (mostly typo) changes
	190	by Nico Schmoigl <schmoigl@rumms.uni-mannheim.de>