SVGATextMode(8)
NAME
SVGATextMode - Textmode manipulation/enhancement tool
SYNOPSIS
SVGATextMode [ -ndhrfcvsam ] [ -t ConfigFile ] [ Textmode-
Label ]
DESCRIPTION
SVGATextMode provides a means to seriously enhance the
looks of your Linux text consoles, by re-programming the
(S)VGA hardware. It uses a configuration file similar to
the one the XFree86 X-windows server uses (Xconfig or
XF86Config) to set up better looking textmodes. (=higher
resolution, larger font size, higher display refresh...).
It works independently of what text modes are allowed from
the BIOS. In theory, any text mode size is possible, as
long as your VGA card is up to the job. Whether it is or
not, depends greatly on the chipset.
SVGATextMode can resize the console screen on the fly,
without rebooting, to any other size. The configuration
file holds all the parameters needed for the new mode.
It needs kernel version 1.1.54 or newer if screen resizing
is to be possible.
Supported chipsets
VGA Generic VGA chips. This can also be used for unsup-
ported VGA chips, but with very limited possibili-
ties. Most portable VGA computers (Compaq LTE, ...)
should work with this also: VGA LCD's can't use
higher dot-clocks anyway.
It is important to start from a standard VGA text
mode (80x25...80x50) when using this "chipset" for
unsupported chips. Otherwise the clock will not be
programmed correctly.
ET6000
ET4000
ET3000
S3 any S3-based card, including those from Diamond,
Number 9 and SPEA/Video7.
CIRRUS Cirrus Logic chipsets. This works with CL-GD542x,
CL-GD543x ("Alpine") and CL-GD546x ("Laguna")
chipsets.
TVGA8900, TVGA9000
The oldest Trident cards. NOT for the Trident
accelerated cards like the 9440 etc.
TGUI All accelerated Trident cards from TGUI9320LCD and
up.
PVGA1, WDC90C0X, WDC90C1X, WDC90C2X, WDC90C3X
All (?) Western Digital cards, from the plain old
first Paradise card (PVGA1) to the more recent
WDC90C33 accelerator (WDC90C3X).
ATI All ATI cards BEFORE the MACH32.
ATIMACH32
ATI MACH32 and MACH64. Many MACH64 cards use spe-
cial RAMDACs and clockchips that are not yet sup-
ported by SVGATextMode. Those will not work.
ATIMACH64
The MACH64CT is the only member of the MACH64
series that is supported.
VIDEO7 Headland Technologies based Video 7 boards only.
Older V7 boards use C&T or Cirrus chips. Newer
V7/SPEA cards use S3.
ALI, AL2101
Avance Logic chipsets. It's not sure whether this
will work on ALL Avance Logic cards.
OTI67, OTI77, OTI78
Oak Technology chipsets.
SIS SiS chipsets. UNTESTED!
RealTek
RealTek chipsets. UNTESTED!
ARK ARK1000 and ARK2000 chipsets. UNTESTED!
NCR77C22E, NCR77C32
NCR chipsets. The NCR77C21 and NCR77C22 (without
"E" suffix) will not benefit from this. They should
work just as well with the generic VGA driver.
UNTESTED!
GVGA Genoa 6000 series cards. The 5000 and 7000 series
are based on resp. ET3000 and ET4000 chips. Use the
ET4000 driver for those. UNTESTED!
MX MX graphics chips. MX86000 and MX86010 chips should
work. UNTESTED!
MATROX Matrox Millennium and Mystique are supported.
SVGATextMode needs a configuration file with a similar
syntax as Xconfig or XF86Config, the configuration file
for XFree86, the X-Windows server. The default config file
is /etc/TextConfig.
See the TextConfig(5) manual file for details on its syn-
tax.
When running SVGATextMode with a new textmode, it will
output a single line, describing what the new mode is, and
what are the screen refresh rates.
Example output:
Chipset = 'S3', Textmode clock = 75.00 MHz, 116x48 chars,
CharCell = 9x16. Refresh = 55.93kHz/69.9Hz.
OPTIONS
The only required option is the TextmodeLabel, which tells
SVGATextMode to which mode it must switch. A mode descrip-
tion line with the same name must be present in the config
file. The parameters on that line will be used to program
the new text mode.
-n don't program the new mode. This option will scan
the config file for the requested mode, parse all
parameters, and report what the new mode will look
like. But it doesn't actually change anything. This
is useful for seeing if a mode is correctly entered
in the config file, and if your monitor will be
able to handle it.
-d debugging mode. SVGATextMode will output lots of
debugging information about all the things it
attempts to do. This is mostly for "internal pur-
poses" only, but it could help you discover why
SVGATextMode doesn't react as you expect it to.
This could also be useful when reporting a problem.
A second "d" option will enable extended debugging,
showing you all the data that was parsed from the
config file, instead of just the most important
things. More specifically, this will add all the
mode lines and the font selection list to the debug
output.
-h prints out a short help and the version number.
-r don't run the ResetProg.
When a ResetProg is defined (and thus enabled) from
the config file, SVGATextMode, without "-r", will
attempt to run it whenever it has changed the
screen size.
The reset program is normally used to signal or
restart a program that depends on the current
screen size, and that doesn't react to the SIGWINCH
signal the kernel sends it upon a screen resize.
Typical examples are gpm and selection; two very
handy textmode-mouse handlers.
Resizing the screen from 80x25 to e.g. 116x48 with-
out telling gpm or selection about it, will cause
the mouse cursor to get stuck in the upper left
80x25 characters of the screen.
The "-r" option is useful when SVGATextMode is
started from the system initialisation files
(/etc/rc.d/...), because many of the programs that
need to be reset through the ResetProg have not yet
been started, so trying to send them signals, or
trying to kill them, would fail. And trying to
restart them would cause two copies of the same
program running when the rest of the rc-files start
them up.
-f don't run the FontProg. When the font loader is
enabled through the LoadFont option in the config
file, SVGATextMode will not run it, even when the
screen is resized. When this option is not enabled
and the font loader is enabled, SVGATextMode will
run an external program to load a suitable font.
-c don't program the pixel clock. More of a debugging
option. If you suspect that SVGATextMode fails to
program your VGA clock properly, then this option
programs everything else except the pixel clock,
which is left at its old value. Some laptops don't
react to well when the pixel clock is reprogrammed,
so this option can help there, too.
-v don't validate H/V frequencies. Normally SVGA-
TextMode will check the horizontal frequency and
the vertical refresh of the new mode against the
ranges specified in the config file, and refuse to
program a mode that doesn't fall within those lim-
its. This option turns off that checking, and will
program ANY mode, even if the config file says your
monitor cannot handle them.
-s scan mode. SVGATextMode will scan the entire config
file, and will dump a listing of all valid modes
for your configuration, taking the limits for ver-
tical refresh, horizontal scan rate, maximum text
mode pixel clock and availability of the required
clock frequency (if you don't have a programmable
clock chip) for your VGA card / monitor configura-
tion into account. When combined with the -v
option, it will dump all modes, whether they are
allowed or not.
This is particularly useful to create input to a
script or program that lets you (for example)
select a text mode from a menu.
-m allow trying to resize screen via a 1x1 screen.
This option is only useful when you get an out of
memory error when resizing the screen. Normally
SVGATextMode will just exit and tell you there was
not enough memory. The best thing to do then is to
free some memory. If that is impossible for some
reason, this option will first resize the screen to
a 1x1 size to free the memory already taken up by
all the consoles, and then resize to the desired
size.
WARNING: see the BUGS section for more information
on the potential dangers of this method. Do not use
this option unless it is absolutely necessary.
-a always do a full resize. SVGATextMode will normally
check with the old screen size to see if the new
mode actually resizes the screen (it could just
enhance the screen by moving to a larger font, but
remain at the same width/height). It does that via
the tty settings (those you get when typing "stty
-a"). If it detects that the new mode is a differ-
ent size than the old one, it will run all sorts of
extra code to make various system components know
about the resizing. But if it thinks no actual
resizing has been done, it won't do that.
Under certain circumstances (see the BUGS section),
it is desirable to resize the screen, even if the
tty settings say the screen already has that size.
This option will force the resizing code to "fake"
a resize, and run all necessary code (set the tty
settings again, tell the kernel about the resizing,
and run the optional ResetProg).
-t ConfigFile
This option tells SVGATextMode to use a different
configuration file than the default one
(/etc/TextConfig).
-o Force all standard VGA registers to a known
textmode state. This is quite useful when some VGA-
aware program (X-server, svgalib, ...) crashes or
gets killed and leaves the screen in graphics mode.
There's only one problem with this. Most of these
types of crashes leave the keyboard in raw (scan-
code) mode, and thus you won't be able to type the
command to restore text mode... You will have to do
a "kbd_mode -a" from a remote terminal first.
Unless you add "kbd_mode -a" to the file defined in
the "ResetProg" label in the TextConfig file, and
have "stm -o" under a mousebutton combination with
the GPM mouse package.
Another fun-stopper is the extended VGA registers,
which this option does _not_ reset, because they
are chipset-dependent. This means that the "-o"
option might not help at all, depending on how
sophisticated your card is. SVGATextMode knows
about a few cards and how to kick them back into
"normal" mode, but not all (due to lack of documen-
tation and cards to test -- hint, hint).
Example
A small example of how SVGATextMode goes to work: suppose
you started up in 80x25 text mode, and wanted to change to
a more respectable 116x48 mode with a fine 16-pixel high
font (normal 132x43 modes from the BIOS are only 8 to 11
pixels high, and the difference is incredible), and extra-
wide spacing (using 9-pixel wide characters instead of 8).
Now suppose you have a mode description line in the config
file that looks like this:
"Super116x48" 75 928 968 1104 1192 768 775 776
800 font 9x16
(the entire config line must be on a single line)
After correctly configuring the /etc/TextConfig file for
your VGA card, typing
SVGATextMode Super116x48
will produce an output similar to the following:
Chipset = 'S3', Textmode clock = 75.00 MHz, 116x48
chars, CharCell = 9x16. Refresh = 55.93kHz/69.9Hz.
Loading 8x16 font from file /usr/lib/kbd/console-
fonts/Cyr_a8x16
Note the refresh timings at the end of the first output
line: this mode would require an SVGA monitor capable of
56 kHz at 70 Hz (the same frequencies as a VESA 1024x768 @
70 HZ mode).
The second output line actually comes from setfont, a pro-
gram which SVGATextMode can be made to call automatically
after resizing the screen, so the font is adjusted to the
available space in the character cell.
SECURITY
In order to be able to do anything, SVGATextMode must be
run by the superuser, or it must be setuid root.
Having SVGATextMode installed with the SETUID bits ON
makes it run as root, even when a non-root user runs it.
This is a potential security problem, since SVGATextMode
can be made to execute external programs (font loader and
ResetProg).
The default distribution will NOT renounce superuser
rights EVER, so it'll run any external program as root
also (if the setuid bits on SVGATextMode are on, of
course). If you are administering a critical system, don't
set the SETUID bits on SVGATextMode (which will have the
side effect that non-root users cannot use SVGATextMode),
or if you do, make sure that all externally called pro-
grams are secure.
If you want to have the SUID bits on, but don't trust the
external program's security, then recompiling SVGATextMode
with the compile-time option "RUN_SECURE" enabled will
make SVGATextMode renounce superuser rights immediately
after requesting rights to write to the VGA registers. Any
program run thereafter will be run with the user ID of the
one executing SVGATextMode.
If the programs called by SVGATextMode are not setuid
root, they might fail, because they want to change things
only root is allowed to tamper with.
DOS VERSION
There is a DOS version of all SVGATextMode tools (includ-
ing SVGATextMode itself) included in the distribution.
The stm.exe program will do the same, and require the same
as SVGATextMode under Linux, with the following excep-
tions:
* The TextConfig file is in \etc\textconf. Note the lack
of a drive letter. You have to execute stm.exe from
the same drive the textconf file is on. Otherwise, use
the -t option to specify a full textconf file path.
* No font loading (yet?). Do not enable the "loadfont"
option in the textconf file. It will not work: there is
no DOS font loader included in the SVGATextMode distri-
bution. This basically means you are limited to modes
that still work with the same font you started with.
There are no doubt numerous font loaders available for
DOS that could solve this problem.
* Stm.exe is really of limited use. DOS was not designed
to have flexible screen sizes (DOS was not designed -
period. DOS was patched). DOS programs follow the same
route. Some DOS programs assume a certain screen size
(like 80x25). Many assume at least a constant screen
width (80 chars). Only a few support all screen sizes
without trouble. You can expect DOS versions of UNIX
tools to be of the last kind (like the editor joe.exe).
* Running stm.exe in a Windows DOS box IS possible,
although you must remain 80 chars wide, or Windows will
report that "due to the way this program uses the VGA,
it must be run full-screen". If you run stm.exe to
change from a 80x25 screen to a 80x50 screen, the DOS
box will auto-resize to the new height.
BUGS
Probaby zillions of them. And for a program that must be
run as root, and that changes hardware registers, this is
not a good thing.
mode switching
SVGATextMode's purpose is to change the previous
text mode into the new one. It only changes those
VGA registers that determine the text mode size.
Any other register is left untouched. This has the
advantage that the special (tricky) registers that
were set up by the BIOS when the machine booted
remain unchanged, so SVGATextMode doesn't need to
have the intelligence built-in to deal with all
kinds of special settings.
The downside of this is that it can only go from
one text mode to another. In most cases, SVGA-
TextMode cannot switch to text mode from a non-text
screen (e.g. from graphics mode, or from a messed-
up screen when some graphical application exits
ungracefully).
chipset
SVGATextMode does not even try to detect the VGA
chipset you are using. This means that if you con-
figure it for an S3 chip, but there's a Cirrus
Logic under the bonnet, you'll get a similar effect
as when you try to use diesel fuel in a petrol
engine...
kernel version
You need at least kernel version 1.1.54 to be able
to resize the screen to some other X/Y dimension
than is currently being used. The program will
refuse to resize the screen when it detects an
older kernel version.
out of memory
When the system is under heavy load, screen resiz-
ing could bail out with an `out of memory' error.
The reason for this is rather obscure, but it boils
down to the fact that you need to have at least a
certain amount of free, contiguous RAM if you want
to avoid this. The amount depends on the requested
screen size. On most linux systems (which have a
maximum possible amount of 64 virtual consoles),
this is:
X * Y * 2 * 64
bytes of memory, where X is the number of charac-
ters per line, and Y the number of text lines on
the screen.
When the kernel fails to resize the screen because
of a lack of the right kind of memory, SVGATextMode
tries to free some more by temporarily requesting a
large block of memory and freeing it immediately
again, forcing some disk buffers to be flushed to
disk, and forcing some programs to be swapped out.
If the resizing still fails, it tries to free twice
that much memory, and if that fails, three times
the amount. If you attempt to resize to a really
big screen, this is resp. 2, 4 and 6 MB of memory
that will be "freed" before trying to resize the
screen. If all that fails, then SVGATextMode will
finally give up, and announce this in a large,
friendly error message.
The -m option is a way around this, but it has its
own problems. When it temporarily switches to a 1x1
screen in order to free some more memory, some
other process might snatch memory away from under
it before SVGATextMode can switch back to the new
mode, causing the final resize to the new size to
fail. This is very unlikely to happen, but when it
does, you are left with a 1x1 screen, which is
rather small. When that happens, blindly stopping
some jobs, and blindly resizing to a 80x25 mode
(either through SVGATextMode or set80) is the only
solution.
A much better option to avoid out-of-memory prob-
lems is to tell the kernel it needs to keep more
memory free, by swapping a little sooner. This can
be done only in Linux kernels from somewhere around
the 1.3.60's and up, using /prov/sys/vm/freepages.
The default contents of this configuration "file"
are:
32 48 64
These numbers represent the amount of free pages
(one page is 4096 bytes on an Intel platform) below
which the kernel will begin to swap pages out or
reduce buffer sizes aggressively, moderately and
lightly, resp. All this means that in the default
case, an unloaded machine will saturate towards 64
free pages (256k) free memory. Changing these set-
tings to higher values, e.g.
cat 128 256 1024 >/proc/sys/vm/freepages
will cause an unloaded machine to have 4M free mem-
ory after a while. This will reduce the risk of
running out of memory for SVGATextMode resizing
significantly.
Slow startup
This is more a feature than a bug, but it could
bother you at some time that SVGATextMode starts up
extremely slow. This only happens when you are
starting SVGATextMode from a non-working text mode
(screen blank, monitor doesn't sync,...).
While experimenting with mode timings, at some
point you could end up with a mode that the VGA
card cannot handle, and it just stops outputting
anything at all: no video, no sync, nothing.
SVGATextMode does its work in the vertical blanking
interval, waiting for a vertical sync signal before
starting to change VGA registers. But when there is
no sync, it would wait forever. A timeout of one
second prevents that, but shows up as a relatively
long delay before the new mode becomes active.
In addition to that, the default TextConfig file
has the "SyncDisks" option active, which makes
SVGATextMode execute a "sync" instruction to flush
all remaining data in the disk cache to disk. Since
there is no way to know when that has finished,
SVGATextMode just waits a good while (a few sec-
onds), hoping that all data is flushed by the time
it starts.
Your worst nightmare: SVGATextMode bails out!
SVGATextMode works its way through the VGA register
programming sequentially, working its way through
all the registers one at a time. When it encounters
some kind of error in the middle, it will most
probably bail out with an error message.
But that message will not be of much use, since
leaving those VGA registers halfway programmed will
most probably result in no video at all. So the
message is there, telling you in all detail what
went wrong, but you will not be able to see it...
The author has been made aware of this problem on
various occasions, and future versions will not be
as unforgiving.
In the mean time, make sure nothing will go lost
when you first experiment with SVGATextMode and you
have to reboot to get back into a visible text
mode. Preferably use `savetextmode' from svgalib to
enable a future `textmode' restore command when
something goes wrong. Also consider redirecting
standard error to a file when you expect trouble.
You can then inspect the result when (or "if" ;-)
you get back your screen.
There are some nasty interactions with other programs that
do VGA programming. Amongst them are: the XFree86 XWindows
server, svgalib, dosemu and probably others. The most com-
mon effect is a distorted screen when such a program
switches back to text mode. The real reason for this
mostly lies with that program, because it doesn't restore
all VGA chip registers as they were before that program
started. They were all written a long time before SVGA-
TextMode saw the light of day, so how could they know?
SVGATextMode cannot really solve this problem, since it
exits after setting the new mode, and so it doesn't stay
active to restore the mode whenever another one screws it
up.
For a more in-depth discussion of these kinds of problems,
read the doc/FAQ file in the SVGATextMode distribution.
XFree86
Most problems with XFree86 happen when you change
the text mode after X has been started. The X-
server remembers all VGA chip settings when it
first starts up, and never seems to check them
again. So when you start X, switch back to text
mode while X is still running, then change the text
mode to something else, switch back to X, and then
back to text mode, you're in trouble.
X has restored the VGA register contents of when it
started, which are not the same that you programmed
with SVGATextMode. But the kernel still thinks you
are in the new mode, since X didn't tell it about
the restoration to the old values, and thus the
kernel draws its characters in the wrong place in
the video memory.
Result: screen completely garbled. Solution: re-
running SVGATextMode whenever you switch back from
X to text mode, or exit X, and restart it after re-
programming the new text mode.
The former case will need the -a option to tell
SVGATextMode to force a full resize. When X
restores the VGA register contents, it doesn't
restore the tty settings, nor the kernel screen
size parameters. Thus SVGATextMode is made to
believe that the screen is not resized, and thus
doesn't do all the resizing code, leaving the ker-
nel parameters and tty settings as they were:
wrong.
A general rule of thumb to avoid interaction-prob-
lems with the X-server is to specify as much as
possible, thus allowing the server as little guess-
work as possible. This is recommended by the
XFree86 manuals also, even without SVGATextMode. In
practice this means you let the server guess for
all hardware parameters just once, i.e. when you
first install it on a new VGA card, and preferably
from a non-tweaked textmode (no SVGATextMode). You
then copy as much parameters from the probe to the
XF86Config file as possible. The reason for this is
that some probing routines in the XFree86 server
work well only under a standard text mode (e.g. the
S3 IBM RGB RAMDAC RefClk probe).
other X-servers
If you thought XFree86 was evil for doing this,
keep in mind that some commercial X-servers (e.g.
Accelerated-X from Xinside) for Linux are even
worse (don't shoot me guys! They are absolutely
MARVELOUS X-servers, but their textmode support is
not just bad, it's non-existent).
They _assume_ you start from a 80x25 screen, and
will always return to a 80x25 screen when doing a
VT-switch or when exiting the server. Since they
don't tell the linux kernel what they've just done,
the linux kernel, still thinking it's in some
weirdo text mode, will draw its characters all over
the place, except in the right one... A partial
solution is to change the `startx' script to make
it re-run SVGATextMode after the server exits. But
this doesn't solve the VT-switching problem.
svgalib
Svgalib will show the same type of problems as the
X-server. Some cards will react differently than
from XFree86, because they are more or less sup-
ported in svgalib.
DOSEMU Ditto. Only worse. Dosemu only "knows" about some
basic VGA cards, but has no knowledgs whatsoever
about clock chips and more modern VGA chips.
Chances are DOSEMU gets you in text mode trouble.
DOSEMU might not be clever enough to reset all your
card's VGA registers (including the clock setting
registers) when it starts up in VGA-mode. In that
case, any non-standard SVGATextMode mode could pro-
duce a non-syncing DOS display. The only cure in
this case is to reset to a standard VGA text mode
like 80x25 before starting DOSEMU.
A similar problem might pop up when exiting DOSEMU.
If it doesn't restore all linux textmode registers,
the linux console might get corrupted.
Both problems can be resolved by embedding the
DOSEMU call in a script, which does something like
this:
SVGATextMode 80x25x9
dos
SVGATextMode My_SuperMode
This will not solve the problem when switching to
another virtual terminal while DOSEMU is still run-
ning.
DOS After rebooting to DOS (shame on you! There's a
Doom for Linux also) or when starting DOSEMU, the
text mode screen, or, more likely some graphics
modes might produce a non-syncing display. This is
more likely to happen on boards that use a
clockchip (i.e. when the TextConfig file has a
`ClockChip' line enabled.
The reason for this is that some card's BIOSses
don't care to reset all clocks to their defaults
when they get a reset signal (i.e. when rebooting).
Some die-hard cards won't even do that when you hit
the cold-reset switch, and will only revert to the
default clock values when you power-cycle the
machine.
A simple solution to this is to put an SVGATextMode
(or ClockProg) command in the system shutdown
script. This is in most cases
/etc/rc.d/rc.0
If the programmed clock is the correct default
clock value, your DOS problems will be solved. The
only tricky part here is to find out what that
default clock is...
Since SVGATextMode reprograms clock #2 (the third
clock) on most clockchips, the default clock value
depends on the clockchip type you're using.
Only clocks #0 and #1 are the same for (almost) all
VGA chips, and thus this method is only really sim-
ple for those clockchips where clock #0 (default =
25.175 MHz) or #1 (28.3 MHz) is reprogrammed. This
is currently only for the icd2061a (or the equiva-
lent ics9161) clockchips when the "clockchip_x"
option is used.
More Information
Read doc/FAQ in the SVGATextMode distribution for
more reading on this subject.
FILES
/etc/TextConfig
The (default) configuration file for SVGATextMode
/usr/sbin/SVGATextMode
The main text mode manipulation program described
here
AUTHOR
SVGATextMode was written by Koen Gadeyne
lt;koen.gadeyne@barco.com, with help from a lot of local
and remote Linux fans.
Much of the VGA code for SVGATextMode was borrowed (I will
give it back :-) from the XFree86 3.1 server code (and
also from newer versions). The S3 clock chip code and Cir-
rus Logic clock code was copied (with some improvements
added) from the original XFree86 code.
See the CREDITS file in the distribution for a full list
of all helping hands.
SEE ALSO
TextConfig(5) - Configuration file for SVGATextMode
grabmode(8) - A XFree86/SVGATextMode VGA mode grabber
SVGATextMode-x.y/doc/FAQ - description of problems you
could encounter when using SVGATextMode, and some solu-
tions.
The 'doc' directory in the SVGATextMode distribution con-
tains a lot of miscellaneous documentation on a range of
topics related to configuring and using SVGATextMode.