Provided by: svgatextmode_1.9-21_i386
TextConfig - Configuration file for SVGATextMode
SVGATextMode uses a configuration file normally called `TextConfig’ for
its initial setup. The default place for it is
It has a similar syntax as the configuration file for the XFree86 X-
Windows server. It adheres more or less to version 2 of the XFree86
config file (called Xconfig), but the new Xfree86 syntax, adopted since
version 3 (and now called XF86Config) is quite similar, just a lot more
Config file syntax rules
Basically, the TextConfig file is scanned on a line-per-line basis,
with no specific ordering whatsoever forced upon the user. A line can
appear anywhere in the config file, and will have the same effect.
If the same definition (option, chipset, clockchips, mode lines, ...)
appears twice in the config file, the LAST instance will be used, and
all others ignored. The only exceptions to that rule are the
definitions that can span more than one line. E.g. `clocks´ lines and
`fontselect´ lines. In those cases all lines accumulate, instead of
canceling each other out.
In the entire configuration file, character casing is not important,
i.e. `ChipSet´, `chipset´ , or any other upper/lowercase combination
are considered the same label.
Empty lines are allowed. The last line will always be ignored (make
sure the last line is an empty one).
Any text following a # (hash) character is comment, and will be
You must enclose text strings in double quotes ("). E.g. modeline names
(modeline "my_80x25"), option names (Option "LoadFont"), DefaultMode
names, ClockChip names, Chipset names, etc.
Configuration lines start with a keyword, which tells SVGATextMode what
this line is about. Mode lines can have the prefix "modeline", but this
is not a requirement.
Mode description lines start with an optional `modeline´, and then a
mode label, (any text enclosed in quotes), followed by at least 9
numbers describing the mode timings. A description of the meaning of
these mode timings should be in the MODE TIMINGS section. Note that the
mode label is just what the name says: a label. Even if the label says
"100x37", it does NOT mean this will actually produce a 100x37 text
mode. The mode timings determine that.
Lines not complying with any of the above restrictions, or lines that
use an undefined keyword will produce a parsing error. The most common
error is forgetting the double quotes around a string, causing an error
./stm: ERROR: Unknown token on line 853 of config file
Also consider reading the comments in the distribution TextConfig file
as well. They explain some modes and options as they come along.
When trying to create a new mode of your own, consider "testing" it
first non-destructively: use
SVGATextMode -n <MyNewMode>
(note the ’-n’ option) before doing the real thing (=without ’-n’).
This way the program will show you what the new mode will look like,
WITHOUT really changing anything. This allows you to check if the H and
V sync values will work with your monitor. And it avoids a blank screen
because some number was wrong, and the mode line got screwed up.
Several keywords are used by SVGATextMode to define what the line will
describe. This section only describes the syntax of the keywords, and
some general explanation. The complete syntax, with all possible
entries for each label is described in separate chapters below.
This keyword tells SVGATextMode which SVGA chipset needs to be
programmed. The syntax is straightforward:
will make SVGATextMode treat your card as an S3 card. This can be any
of the many types of S3 cards around.
S3, as well as many other chipsets, have a range of different subtypes
around, but they basically are the same, and SVGATextMode only needs a
tiny bit of its full array of features (imagine what amount of the
chip’s full potential you were using in text mode _before_ SVGATextMode
was around, if it’s still only a tiny part of it _with_ STM ;-)
Roughly speaking, the pixel clock programming is all that is VGA chip
dependent from SVGATextMode’s perspective.
Some chipsets are subdivided into different chipset ID’s. This probably
means the subtypes _are_ different, and so they must be differentiated
in the config file.
See the ChipSet section for a detailed listing of supported chipsets.
Mostly for S3 chipsets, ET6000, Matrox, Cirrus, some ET4000’s and some
Trident cards. This tells SVGATextMode that the pixel clock for this
chipset does not come from the "default" clock generator with (e.g.) 16
discrete clocks, but from a programmable clock chip. All the clock chip
drivers from the XFree86 version 3.1.2 X-server are available, plus the
ICS5301/5341 GenDAC for some ET4000W32/W32p cards. VGA cards that did
_not_ work with the "standard" XFree3.1.2 server are likely to fail
with the current SVGATextMode as well.
Note for XFREE 3.1.X (or newer) users: You WILL get into trouble with
the newer XFREE servers that have some clock chips built-in (The
ICD2061a and ICS9161). When using on of those XFREE clock chips, X
cannot restore the textmode clock correctly.
If this is your problem, using a "ClockProg" for XFREE might be the
only (temporary) solution, until the XFREE86 server has a way around
ClockProg <path/to/ClockProg> [textclock]
This tells SVGATextMode that the clock is to be programmed using an
external clock setting program, not the default or ClockChip method.
This is especially useful for unsupported cards, or supported cards
with unsupported clock chips, because the clock programming is about
the only thing that needs to know what chip we’re talking about.
It’s also a useful stub for plugging in replacements for buggy or wrong
SVGATextMode clock code.
The syntax is roughly the same as the syntax for the XFree clock
program, and indeed any clock program written for XFree 3 should plug
in without a glitch. In theory.
Example (note the second argument is not necessary, and is ignored by
ClockProg "/usr/sbin/pixclock_prg" 2
The Following paragraph, from the XFree docs, shows how this program
must be used:
"This optional entry runs the specified command to set the
clock on the graphics board instead of using the internal code.
The command string must consist of the full pathname (and no
flags). When using this option, a Clocks entry is required to
specify which clock values are to be made available to the
server (up to 128 clocks may be specified). The optional
textclock value is used to tell the server that command must be
run to restore the textmode clock at server exit (or when VT
switching). textclock must match one of the values in the Clocks
entry. This parameter is required when the clock used for text
mode is a programmable clock."
Note for SVGATextMode: the [textclock] argument is not used in
SVGATextMode, since we’re already talking about text mode. The XFREE
server WILL use this, so the SVGATextMode mode will be restored
Note for XFREE users: You MUST define the textclock in your XF86Config
file when you are using a clock program. XFree86 will not be able to
restore the correct textmode clock, UNLESS you tell it what clock was
When the ClockProg is run by SVGATextMode, two arguments are passed to
the command. The first is the clock frequency in MHz as a floating
point number and the second is the index of the clock in the Clocks
entry. When setting a new text mode using a ClockProg, SVGATextMode
will execute the following shell command:
<path/to/clockprog> <frequency in Mhz> <clock index>
The command should return an exit status of 0 when successful, and
something in the range 1-254 otherwise.
NOTE: as mentioned in the text above, you need to specify a clocks
line, although the clock chip can (in most cases) make any clock within
a certain range, and not just the ones in the clocks line. This
requirement is necessary for external clock programs that program an
"old-style" clock chip with just a fixed set of (mostly 16) clocks,
like most "cheaper" VGA cards use. In that case, the program will
probably ignore the frequency parameter passed to it, but will use the
index number to select the appropriate clock. In the other case, the
index will be ignored, and the specified frequency will be programmed.
The clock program path must be a fully specified path to a clock
setting program that is SETUID ROOT! If it is not correctly SETUID
ROOT, you will get an error:
./SVGATextMode: ERROR: ’system’ returned error code 35584
No environment variables will be used. If your clock selection program
uses another interface, use a script that calls that one.
Special options can be entered with this keyword. Some options are
general, and apply to any VGA card type. Other options are specific to
one or a few VGA cards. Any option enabled in the config file that is
NOT allowed for the VGA card in the ChipSet line, will cause an error
See the separate OPTIONS section for a full list of all options and
Clocks <clock0> <clock1> [ <clock2> ... ]
The most important section in the TextConfig file (at least for some
cards) is (are) the Clocks line(s). This entry in the config file tells
SVGATextMode which clocks your card has, and what their ordering is.
Some VGA cards do NOT need a clocks line, since they can create ANY
possible clock within certain limits, and not just one from a fixed,
given list. These are:
- Cirrus Logic cards.
- All cards for which a ClockChip must be defined.
When using a ClockProg (an externally called program to select the
correct pixel clock, see the appropriate section in this manual page),
the clocks line MUST be specified, even if the clock program is
programming a fully programmable chip. By requiring a clocks line, the
ClockProg option can support both programmable clocks, as fixed clock
from a list (i.e. the Clocks line). See the Clockprog section for a
full explanation of the use of the "ClockProg" keyword.
All cases not mentioned above will need a "Clocks" line, or a set of
Any line in the TextConfig file that starts with "Clocks" will be used,
and all clock values will be appended into one big list of available
clocks. In other words, multiple Clocks lines are allowed, and will all
The order of the clocks in the one or more clocks line(s) will also
determine their order: most VGA clocks generators are connected to the
VGA chips with a series of wires, constituting a bus. For 16 clocks,
there are 4 wires, which are driven from 4 pins on the VGA chip, which
are then driven by a register in the VGA chip. If your clocks line
would suggest the 4th clock is a 45 Mhz clock, SVGATextMode will then
put a "4" on that 4-bit bus in order to select that clock. If you lied
(=the actual 45 MHz is the 5th clock, selected by putting a "5" on that
bus), then you will not be getting the expected clocks. Bad luck.
Example Clocks line:
Clocks 25.175 28.3 36 40 0 45 50
Note that a 0 MHz clock MUST be entered in the Clock line! This just
means that there is no clock with that number (index). It must be there
in order to get the correct indexes for the ones following them (a
"placeholder"). A 0 MHz clock will never be used by SVGATextMode.
Determining the values in the clocks line is a problem. There is no
"simple" tool around that can tell you the pixel clocks available on
your card. The easiest solution that is available on most systems is
the XFree86 X-Windows server. Typing X -probeonly should give you
(amongst others) a list of clocks on your card. See the XFREE manuals
for more information: XF86Config(5), XF86_SVGA(1), XF86_Accel(1).
The XFree86 X-server is known to give erroneous clock
measurements on unsupported cards or on badly supported ones.
The most notorious ones are the ET4000 cards. If the hibit
option is not set correctly fior this card in the Xconfig file,
XFree86 WILL give wrong results! You have been warned. See also
the `doc´ directory in the SVGATextMode distribution for more
explanation about this.
Just to be on the sure side, another warning: SVGATextMode
assumes the clock VALUES are correct. All timing parameters that
you are given at the end of the program are based on those
numbers! Saying that clock number 3 is 40 MHz will make
SVGATextMode behave as if that is the Absolute Truth (TM). It
will use that clock as if it were 40 MHz.
The clocks lines in the distribution TextConfig are just
examples, and only work for some cards. Don’t use them unless
you know they’re OK.
Terminals <term_dev0> [ <term_dev1>... ]
The `Terminals´ line tells SVGATextMode which terminal devices will be
affected by a possible screen resize, and need to be resized. It will
resize all mentioned terminals after switching to another mode. This
"resizing" consists of sending a ‘SIGWINCH’ to all specified virtual
The usefulness of this option depends on the Linux kernel version you
are running (as reported by ‘uname -r’). SVGATextMode detects the
kernel version, and acts accordingly, as described below.
There are three distinct cases:
Kernels older than 1.1.54: run-time terminal resizing is not
supported by the kernel at all, and SVGATextMode will only allow
you to select modes that have the same number of rows and
columns as the one you booted with.
Kernels in the range 1.1.54 to 1.3.2 (inclusive): If no
`Terminals´ line is defined, SVGATextMode will be able to detect
which of the first 16 virtual terminals is active, and resize
all those. All VT’s with a number higher than 16 (/dev/tty16 and
up) cannot be detected, and so they would not be resized
automatically. If a `Terminals´ line is defined, all terminals
specified in that line will be resized. So, in this range of
kernel versions, the `Terminals´ line is only useful when you
have more that 16 active VT’s.
Linux kernels versions 1.3.3 and up do all this resizing
automatically, so this line is not needed in that case, and will
If you need the `Terminals´ line, enter the terminal devices without
the leading "/dev/":
Terminals "tty6" "tty5" "tty4" "tty3" "tty2" "tty1"
This is equivalent to typing stty rows <y> cols <x> at every of those
terminals. With the added advantage that any applications running in
those terminals will be sent a SIGWINCH signal by the kernel. Many
full-screen terminal applications will redraw their screen into the new
sizes upon receipt of that signal.
But some programs will NOT know about the new screen size, and will not
work correctly anymore after a screen resize. They need a more drastic
approach: the ResetProg.
An example of such a programs is gpm. SIGWINCH only gets sent to tasks
running with a virtual terminal (/dev/ttyX) as a controlling terminal
(the ps command shows in the TTY field what the controlling terminal of
a task is). Gpm runs with a mouse device (e.g. a serial line) as its
controlling terminal, and hence it doesn’t get sent this SIGWINCH
The "reset program" is called when SVGATextMode has finished its job
successfully, but only when a ResetProg is defined.
The path must be a fully specified path, as in
The reset program could be used to "reset" any application that is
affected when the screen size changes due to using SVGATextMode. It
could for example be a script that kills selection and restarts it, or
sends an explicit SIGWINCH to gpm, or sends some other application an
appropriate signal to let it know the screen has changed.
The reset program will be called with TWO arguments: the H and V size
of the new text mode.
will first switch to a 100x37 mode (if the config line with that label
actually described such a size), and then call:
</path/to/ResetProg> 100 37
FontSelect <FontFileName> <size_X>x<size_Y> [ ... ]
These keywords define the font loading program, the path where all the
textmode fonts are stored, and the font selection table.
SVGATextMode can be told to automatically load a new font when the text
mode has changed, by putting the option line
in the TextConfig file.
In order to load a new font, SVGATextMode needs to know a few things.
First of all: the font loading program. This is an external program,
that will be called with the specified font as an argument. It can for
example specified as:
Where "/bin/setfont" is of course the full pathname of the font
program. If this line is NOT present, but you enabled font loading
with the "LoadFont" option, SVGATextMode will use the default path
The path may contain an entire command line within the quotes. This
allows you to say:
FontProg "/bin/setfont -u def.uni"
This would be required if you load a raw font file without a
unicode map in it. Without that extra option, setfont would
eradicate the original unicode mapping. If this sounds a bit
cryptic: it means, amongst other things, that you will loose the
"high-ascii" characters (aka box-characters) used by many text-
based menuing systems (e.g. minicom).
Secondly, you can also tell the font program where the fonts are
If not specified, the font path defaults to no path: this assumes the
FontProg knows where to find its fonts.
Last but not least: you must let SVGATextMode know which font you want
used for which character cell size. This is accomplished by entering a
font table, as shown in the example below:
FontSelect "Cyr_a8x8" 8x8 9x8
FontSelect "8x12alt.psf" 8x12 8x13
FontSelect "Cyr_a8x16" 8x16 9x16
For each possible character cell size you intend to use, a font file
must be specified. You do not have to add a font file for ALL possible
combinations of fonts from 1 to 32 pixels high and 8 to 9 pixels wide.
But if you select a text mode with a font size that has no entry in the
font table, and font loading is enabled, SVGATextMode WILL put you in
the new text mode, but won’t change the font (since it doesn’t know
what font to load). It will issue a warning that font loading was
enabled, but no font specified.
When all things are configured as above, and you resize the screen to a
100x37, which uses a 9x16 font cell size (this information is in the
mode config line for the 100x37 mode), then SVGATextMode will issue the
following command after resizing the screen:
One final note on font sizes. VGA fonts are ALWAYS 8 pixels wide. But
those that are designed to work within an 8-pixel wide character cell,
will most probably not use the rightmost pixel column. Or in other
words: they will only use 7 (or even 6) of the available pixels, since
they are put back-to-back on the display in an 8-pixel wide font mode.
The extra space must be left open so the characters don’t stick
together, making them a bit fuzzy to read.
For 9-pixel wide character cells, the VGA font, still only 8 pixels
wide, can now use all 8 pixels of its width to define the font. The VGA
card will, when displaying it, add one extra (blank) pixel to get to
the 9-pixel width.
All this means that some VGA fonts are designed to be used in an
8-pixel wide cell, and others are designed for 9-pixel wide cells. BOTH
however DEFINE only 8 pixels.
To make some special characters connect (like IBM box characters)
without gaps, the VGA card can be made to copy the 8th bit into the
Depending on personal preference, and on the type of screen you work
on, the standard underscore cursor might be unsatisfactory. This type
of cursor for example is too small to be useful on laptop screens.
This keyword allows a fully programmable cursor size. To avoid needing
a cursor definition on each and every text mode definition line, there
is just ONE cursor definition in the TextConfig file, which is then
used for ALL text modes. Defining the cursor style for _every_ text
mode line would cause unnecessary clutter in those configuration lines.
The parameters define the starting and ending line of the cursor, but
this is not a 1:1 mapping! The size of the cursor depends on the size
of the selected font. If you selected a 16-line high font, and then
defining the cursor to show from line 7 to line 8, will put it smack in
the middle of the line. defining the same numbers for an 8-line font
would put the cursor on the bottom of the text line (= and underscore
That’s why the cursor definition as shown above will ALWAYS be relative
to a 32-line font (the largest possible font size). If the REAL font
size is smaller, it will be scaled to fit that font size. So defining
an underscore cursor for 32-line fonts will also get you an underscore
cursor for any other font size.
results in an underscore cursor for ALL text modes, while
will get you a block cursor.
The first example, when used in a 16-line font, is scaled with a factor
16/32, and thus will in reality be a cursor from line 14-15.
NOTE: Disabling cursor blinking is only possible on SOME SVGA cards, or
on all in monochrome mode. This feature is not implemented in
There is a kernel patch out that allows the cursor color and blink to
be selected differently for each console through a separate program
using vt200 style escape codes. It’s (at least) on the sunsite.unc.edu
and its mirrors in the package
HorizSync <from>[-<to>] [, ...]
VertRefresh <from>[-<to>] [, ...]
The HorizSync and VertRefresh lines allow you to protect your monitor
from getting a mode from the VGA card it cannot handle. This is useful
for both avoiding the problem of accidently getting into a non-syncing
mode, and also avoids the (very small) possibility of monitor damage
due to extremely out-of-range sync inputs (a monitor that gets
destroyed by out-of-spec input frequencies is a poor design, but
knowing that when it’s broke doesn’t help a lot)
The <from> and <to> are floating point numbers in kHz (for HorizSync)
or Hz (for VertRefresh). When a single number (= only <from>) is
defined, a margin of +/- 0.3 (kHz or Hz) will be allowed:
will allow a horizontal sync range of 55.7 to 56.3 kHz. This is useful
for fixed-frequency monitors (mostly workstation displays), or some old
standard VGA screens.
A more complex line could look like this:
allows horizontal frequencies from 30.5 to 32 kHz, 48.2 and 56 kHz.
Some dual- or triple-scan monitors can use this method.
A standard multisync screen could for example use the following line:
Not defining the HorizSync/VertRefresh variables implies the default
HorizSync 30-32 # 30 to 32 kHz
VertRefresh 50-80 # 50 to 80 Hz
Changing these values BEYOND what your monitor can handle, COULD result
in damage to the monitor! See your monitor’s user’s manual for details.
This line overrides the built-in maximum pixel clock speed for text
mode for the specified chipset. Since most VGA card manufacturers don’t
bother mentioning this value in their data sheets, the defaults were
"guessed" from reports from users. The values are by no means
"absolute", and they are no guarantee that staying below them will NOT
cause trouble (although it’s pretty sure), and also they are no
guarantee that anything ABOVE that frequency will NOT work...
Depending on the quality of your card, and especially of the speed of
the RAM chips used on it, the built-in limit can be either too high or
too low. The built-in ones are mostly on the safe side.
WARNING: The value you assign to DacSpeed is NOT the same that is
commonly defined by the graphics card vendor! It is almost always MUCH
The default DacSpeed values are:
VGA, TVGA9000, VIDEO7, PAVGA1 and NEOMAGIC
TVGA8900, WDC90C0X, WDC90C1X, WDC90C2X, WDC90C3X
Cirrus, ATI and ATIMACH32
ET6000, MATROX, OTI67, OTI77 and ATIMACH64
S3, ALI, OTI87
ET4000 90 MHz
The following chipsets have been assigned a default maximum text
mode clock that was "guessed", rather than tested. This is
because the author does not have access to such a card, and
nobody has reported on how well it performs, and how high the
clock speed can be before problems appear. If you have such a
card, you are encouraged to report your findings to the author,
so he can adjust the default limits to a more realistic value.
RealTek, NCR77C22E, GVGA, MX
ARK, SiS, AL2101, NCR77C32, ET3000
NOTE: The maximum text mode clock is increased by a factor of 9/8
when a 9-pixel wide font is used. A 60 MHz maximum clock is thus
increased to 67.5 MHz for those modes. This is due to the way
the VGA textmode hardware functions: the real limit for textmode
is not the pixel clock, but the actual number of characters that
must be fetched from the VGA memory per second. Since 9-pixel
fonts take 9/8 times as much time to draw as 8 pixel fonts, they
will allow an 9/8 times as high pixel clock as well. In other
words, with a maximum pixel clock defined at 60 MHz, you will
still be allowed to select modes with 9-pixel fonts and 67 MHz
Many apparent display problems when using SVGAtextMode with a
relatively high pixel clock are caused by the VGA card not being
able to cope with the high clock. TextMode clocks generally
cannot be as high as graphics mode clocks. Read the file
‘doc/FAQ’ in the SVGAtextMode distribution for a more in-depth
discussion about this.
The limits given above (and used as a default) are empirical.
This means they resulted from experiments, and are thus not
taken from the VGA chip maker’s specifications. This is the
correct place to introduce the expression "your mileage may
vary": your card may be better, or worse. VGA card makers
generally don’t mention maximum text mode clocks (as opposed to
max. graphics clocks, which are ALWAYS specified) in their data
If you see unstable characters, wrong characters (e.g. a "z"
where you expect an "e"), character crawling, Mighty Morphing
Power Characters (TM), columns of characters from the left of
the screen repeated towards the right, drop-outs (fixed
positions on the screen where characters won’t display)
characters shifted down by one pixel line relative to the
others, or something closer to noise than to text, you are most
probably over the limit for your card.
Only S3 cards using the IBM RGB RAMDACs (as a clockchip) need this
option. It tells the clockchip code what the reference frequency for
the PLL frequency generator is.
It is vitally important that this value is set correctly, or
SVGAtextMode will not be able to program the pixel clock correctly.
SVGATextMode does not provide a direct way to find out what to insert
here. The only way to find it out is to run the XFree86 3.1.2 server
(or any newer version), and copy the value that the server reports when
it starts up.
The X-server startup messages should contain the line
(**) S3: Using IBM RGB52x programmable clock
And just below it (or with one more line in between stating the memory
(**) S3: with refclock %1.3f MHz (probed %1.3f & %1.3f)
Where ‘%1.3f’ represents a floating point number.
This value should then be inserted into the TextConfig file.
If you do not have the X-server installed, you should probably not have
bought such an expensive VGA card in the first place. Send me that
card, and I will send you mine back: it’s a lot cheaper, it is just as
good in text mode, and it doesn’t need any fiddling with RefClocks and
the likes. You’ll have a better-supported VGA card, and I’ll have
something new to play with.
But in the unlikely case you want to keep this card, but not run X on
it, you could just insert any value (e.g. 20.0), and use
grabmode/clockprobe to find out by what ratio the clock is programmed
wrong, and then scale the RefClk accordingly.
E.g. if you just enter 20 MHz as the reference clock, and all text mode
clocks turn out to be wrong by a factor 0.716, then the REAL RefClk
value will probably be 20.0 * 0.716 = 14.32 MHz.
This method will of course give you a non-syncing display for many text
modes, but that is inevitable. Be prepared for it.
When using SVGATextMode with an IBM RGB RAMDAC together with the
XFree86 X-server, you must define the RefClk in your X
configuration file (XF86Config) also. The XFree86 server can
probe for this clock, but only does so reliably when being
started from a standard (80x25) text mode. After having run
SVGATextMode, you’ll probably be in a non-standard mode (that’s
what it’s made for after all), and then the X-server cannot
probe the RefClk correctly anymore. Don’t let it guess; specify
Some ClockChips allow changing the memory clock as well as the Pixel
clock. On those cards, the higher the memory clock, the faster that
card will become. Both in TextMode, svgalib or XFree86.
Specifying the MClk will instruct SVGATextMode to change the memory
clock to the new value (in MHz).
This is only possible on cards with a GenDAC (S3 GenDAC/SDAC, and the
ICS5301/5341 used on some W32 boards).
For text modes, this will in most cases allow you to use even higher
pixel clocks than before, and in graphics modes, you might find an
increase in speed of up to 30%. But...
EXTREMELY IMPORTANT WARNING:
If you try fiddling with the memory clock without reading this,
you’re sure gonna get suckered.
This option was created for those who just _need_ to tune their
machine until it just doesn’t melt, or beyond (like me). I am
not saying this could damage your VGA card, but I am also not
saying it won’t.
Primo, make sure you know how the memory clock was set BEFORE
attempting to change it. On most systems, this is in the order
of 50 (GenDAC) to 60 (SDAC) MHz. The XFree86 X-server reports
the MClk setting when it starts up. Increasing the MClk by 10,
maybe 15 MHz might still work. Setting it to 100 MHz will NOT.
Secundo, don’t try to set it too high. If you do, your system
will crash in a major way. Let me repeat this: your system will
crash as it has never crashed before. It has done so many times
while I tried it (though I never got any damage). BE PREPARED.
Sync your disks. Get an insurance.
Also, don’t set it too low. It’ll give the same results...
You have been warned. If you abhore unstable systems, DON’T
TOUCH THE MCLK!
Using this optional keyword, one can define which mode should be used
when SVGAtextMode is started without any mode label on the command
The only argument is a mode label which should be defined in one of the
mode definition lines in the rest of the config file. In fact,
SVGAtextMode will act as if the label in the DefaultMode line was typed
on the command line as the required mode.
This option could be especially useful when experimenting with
SVGAtextMode, and something goes wrong, causing the screen to become
unreadable. To restore a good mode, you’d then have to do some blind
typing. The DefaultMode would then allow you to restore a good text
mode without having to type too much.
Example: if the line
is in the TextConfig file somewhere, then just typing
at the shell prompt is exactly the same as typing
This option will set the screen border color to a different color than
the default (color 0, black). You can select one of the 256 possible
colors from the current palette.
If you set the border color to something different than black, a border
will be visible around the active screen area, about one character wide
left and right, and half a character wide on top and at the bottom of
The border may be slightly (or entirely) distorted (warped, compressed,
missing, ...) if your video mode is not centered correctly, or if the
video mode does not provide sufficient blanking on both sides, above
and below the screen.
Underlining is disabled by default, unless you define an underline
position with this option. The <Underline_position> must be a number in
the range 0..31, and it defines the relative position of the
The position given is always relative instead of absolute (as with the
cursor position parameters). Position 31 is always at the bottom-most
line, 0 is at the top-most line, 15 is in the middle, etc.
The normal everyday-use UnderLine value is 31 (which means: put the
line as low as possible).
Using this, you could change the underline to a strike-through
("UnderLine 15") or any other weird and totally useless underline
position (what about a line above the text when it is underlined?).
The single real benefit of this option is if you want to use too small
a font for the current VGA parameters: suppose you have a text mode
defined in its mode line to have an 18-pixel high font, but you load a
16-high font in it because you happen to like wide line spacing. In
that case the "normal" underline position will be at the bottom of the
18-character cell (as if you defined "Underline 31", which is the most
common one). In this particular case, setting UnderLine to 28 would be
much more nice to look at. This way the underlining character is just
below the character itself, and not at the bottom of the character cell
(which would look as if the line was actually ABOVE the next line of
As said above, not defining the underline position disables
underlining. Any characters that would be underlined, are not.
This doesn’t work for 32-pixel high character modes, since "no
underline" mode sets the underlining position to line 32, which is
never used in all other cases, but will still show underlining in 8x32
and 9x32 fonts.
Also note that many VGA cards have a bug (?) that causes the
underlining to be non-continuous on 9-pixel wide fonts. So you have a
fair chance that 8-pixel wide modes have good (continuous) underlining,
but 9-pixel modes not.
The string (enclosed in double quotes) is printed on the standard
output. This could be used for debugging purposes, or to add some
warning to the TextConfig file that is printed each time you run
It is used for example in the default TextConfig file to warn the new
user that he has installed SVGATextMode in its "standard VGA" mode,
which doesn’t use the full possible potential, and that he/she should
edit the TextConfig file to enable support for his/her chipset.
Until now, the following VGA chipsets are supported:
VGA Generic VGA chips. This can also be used for unsupported VGA
chips, but with very limited possibilities. Most portable VGA
computers (Compaq LTE, ...) should work with this also: VGA
LCD’s can’t use higher dot-clocks anyway.
ET4000 Probably any ET4000-based card: et4000, et4000ax, et4000w32,
et4000w32i and et4000w32p. Note that most ET4000 cards need the
Option "hibit_high" or Option "hibit_low".
ET6000 This can be used without "clockchip" line, in which case 8 pixel
clocks must be specified, or (and this is the preferred method)
using a "clockchip ET6000" line.
MATROX Only the Millennium and the Mystique are supported (the older
cards aren’t). Clockchip "ti3026" (for the Millennium) and
"mystique" (for the Mystique) are the clockchips for the
S3 any S3-based card, including those from Diamond, Number 9 and
SPEA/Video7. S3-801, 805, 864, 964, 928, 924, 911, 732 and 764
(S3-Trio), and S3 Virge _should_ all work.
CIRRUS Cirrus Logic chipsets (clgd542x, clgd543x, clgd546x, clgd62x5 --
with "x" representing any number).
Older Trident cards using the TVGA9000 chipset (those with max
All other non-accelerated Trident cards (tvga8800cs, tvga8900b,
tvga8900c, tvga8900cl). May also work with tvga92xx.
TGUI All accelerated Trident cards from TGUI9320LCD and up.
PVGA1 Western Digital Paradise chips.
Western digital. WDC 90C00.
Western digital. WDC 90C10
Western digital. WDC 90C20
Western digital accelerated SVGA chip. Most common is the WDC
90C33, also 90C31.
ATI All ATI cards BEFORE the MACH32
Only MACH64 with internal clockchips are supported.
VIDEO7 Headland Technologies based Video 7 boards only. Older V7 boards
use C&T or Cirrus chips. Newer V7/SPEA cards use S3.
Avance Logic chipsets. It’s not sure whether this will work on
ALL Avance Logic cards.
OTI67, OTI77, OTI87
Oak Technology chipsets.
SIS Sis chipsets.
ARK ARK1000 and ARK2000 chipsets.
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.
GVGA Genoa 6000 series cards. The 5000 and 7000 series are based on
resp. ET3000 and ET4000 chips. Use the ET4000 driver for those.
MX MX graphics chips. MX86000 and MX86010 chips should work.
Those NeoMagic laptop controllers
Should work on all RIVA128 derivatives (including ZX and TNT)
This section contains a list of all allowed special option flags, as
entered on an
line. They change the default behaviour for each card or function
programmed into SVGATextMode. Currently the following options are
allowed (for the specified chip sets):
If you are configuring SVGATextMode for the first time, it is best to
leave all special options at their default (i.e. no special "option"
lines). If something doesn’t work OK, THEN is the time to start trying
If you know your card needs the same option in XWindows, you could
insert it from the first time on. Most options behave the same way as
they do in the XConfig (XF86Config) file.
hibit_high, hibit_low (ET4000 only)
This flag inverts the meaning of the 4th clock selection bit of an
ET4000 card. See the XFree86 documentation or the SVGATextMode
distribution doc directory for more information. It has the same
meaning and function as the flag with the same name in the XF86Config
file for XFree86. A simple guideline (which doesn’t always apply) is
that ET4000W32 cards _all_ need the hibit_high flag.
The importance of this "hibit" stuff cannot be stressed enough.
It might be that your XFree86 X-server worked fine before you
started using SVGATextMode without this option in the XF86Config
file (or Xconfig). But unless you really specify it, using
SVGATextMode in combination with one of the upper 8 pixel clocks
from the "Clocks" line(s) will SURELY throw the X-server into a
non-syncing display when you start it up! Specify this option in
BOTH the XF86Config AND the TextConfig file, and you won’t have
any trouble. You have been warned.
swap_hibit (WDC90C1X, WDC90C2X, WDC90C3X)
Some WDC cards need this flag. It inverts the meaning of the third
clock selection bit (bit #2). It has the same meaning as in the XFREE
config file (XF86Config). If your clock ordering doesn’t seem OK, try
This selects an alternative clock selection method for some very rare
ET4000 based cards that don’t work with the normal clock selection
method. These cards can only use their 8 lowest clocks under X-Windows
(the X-server does NOT support the alternate clock selection method
Such a card can be recognized by the fact that no clocks over 80 MHz
are available in XFree86 (the X-server uses a clock selection method
that is only partly compatible with the one used on this type of card).
This option should allow them to use all 16 clocks (i.e. those reported
by the DOS utility "dmode.exe" which is delivered with most ET4000
boards. NOTE that XFree86 does NOT report the correct clocks!).
If you think you have such a board, you should really read the
doc/README.ET4000.AltClockSel file in the SVGATextMode distribution
directory for an in-depth explanation of this problem.
UPDATE: Use XFree86 version 3.1.2C or later, and this problem will be
gone. You will get 32 clocks from its new clock probe, and the
standard SVGATextMode ET4000 clock selection mechanism will be able to
cope with those.
Legend (ET4000, S3)
ET4000 or S3-based Sigma Legend boards need this option for correct
XFAST_DRAM, FAST_DRAM, MED_DRAM, SLOW_DRAM (CIRRUS, TGUI and S3)
Most VGA cards can take higher pixel clocks (especially in text mode)
when you increase the default DRAM speed. This may cause display memory
corruption if set too fast.
Some Cirrus cards crash your machine when DRAM speed is set too
high. It will at least do all sorts of very funny stuff, like
beeping forever. If you plan to tweak the DRAM speed, consider
using the "syncDisks" option described below until you are sure
the increased DRAM speed is no danger to your machine.
Use this option to tune the speed to your card. The higher you can set
the DRAM speed, the better. "XFAST_DRAM" is the fastest, and the most
dangerous. This particular option works on most CLGD-5428 cards, and
it causes a hang on most 5422 cards... Use caution. Faster pixel clocks
usually need faster DRAM speed grades.
On S3 cards, this option doesn’t actually set the DRAM speed, but an
internal parameter which controls the DRAM FIFO balancing (sic). The
result is the same: the faster you set this option, the higher you will
be able to set the pixel clock without getting problems.
Only S3-based SPEA Mercury P64 cards could need this. They seem to use
the clockchip differently than the other S3 clockchip-based cards: they
reprogram clock number 6 instead of the default, number 2.
LoadFont (all cards)
When enabled, this will tell SVGATextMode to load a new font from the
specified FontPath (or the default one) using the specified font loader
(or the default one). See the font loading section.
ClockDiv2 (all cards)
This option will enable a standard VGA feature that can divide the
pixel clock by 2. Almost all VGA cards support this (except Cirrus
Logic, for which it has been disabled).
It gives you access to a wider range of clocks, especially in the low
ranges, since now all given clocks are also available divided by 2. It
also gives you more clocks in the "mid-range".
Enable it ONLY when you are sure SVGATextMode works for your card.
Since some cards might not work with this option set, it is disabled by
default in the default TextConfig file! Some modes (like the 50x15
ones) will only be allowed when this option is enabled, because most
card’s lowest clock is 25 MHz, and some of the 50x15 modes need a lower
A final warning: The division by two option is unknown to most other
programs, and could cause (additional) cooperation problems with those
programs. If you loose video when using SVGATextMode together with
other VGA-related programs, try disabling this option, and see if the
SyncDisks (all cards)
When this option is enabled, SVGATextMode will sync all disks (= flush
all cache buffers) before doing anything to the VGA hardware.
In all normal cases, this option is useless, but some cards seem to
have problems with the way SVGATextMode talks to them, and cause a
complete system hang (hard reset needed).
This is especially probable (but still very rare) when overriding the
default maximum DacSpeed, and severely overdriving the VGA card’s text
mode capabilities. As mentioned above, Cirrus Logic cards are dangerous
customers when you start tweaking the DRAM speed.
So, just to be on the safe side, use this option when tweaking DRAM
speed or RAMDAC speed, until you are confident that the system is
In this case, the SyncDisks option can at least avoid data loss when
the system hangs, although it cannot avoid the file system check that
will result from the reset.
The sync option is enabled by default in the configuration file. It
will cause an extra 2 second delay when running SVGATextMode, because
it waits for that long, allowing the sync to finish.
S3 cards have a "high-speed text font fetch mode". This is a mode that
uses a different system to access the VGA font memory (fast page mode),
so the access to the fonts is faster. This allows for higher pixel
clocks than could be attained in normal text mode.
There is one restriction to this: the font must be stored in memory in
a different format than would normally be used (i.e. the normal font
loading programs won’t be able to do this). The S3 designers provided a
special register for that purpose. This register, when set, will
automatically change the memory access so that the font can be loaded
in a normal fashion. This allows normal font loaders to do the job.
Due to that special register, font loading will only work when it is
executed from within SVGATextMode. This way, SVGATextMode can set this
special register before running the font loader, and reset it again
Some older S3 cards will benefit greatly from this option. Especially
S3 911, 924 and 928 cards couldn’t even cope with 40 MHz in normal text
mode. They use high-speed text mode if they are switched to 132x25 or
132x43 from the BIOS (e.g. through LILO).
If this option is not enabled, SVGATextMode will always use normal text
mode, because it is the most compatible mode, and is less prone to
problems (e.g. doing a "setfont" in high speed mode causes a corrupted
screen, unless you first let the VGA chip know about it).
If it is enabled, high-speed font mode will be used for all modes with
pixel clocks above 36 MHz.
NOTE: Using the High Speed Font mode will cause text screen corruption
on the screen where the output from SVGATextMode would appear:
Random characters will appear all over the screen. This is
caused by the S3 card being in a different memory access mode
while the font loader is running. Any messages from the font
loader will not be written on one line under the SVGATextMode
messages, but its characters will be written all over the
screen. After the font loader has finished, the normal memory
access mode is restored, and all characters are written to their
normal places again. This has been partially solved by storing
the output of the font loader in memory until the normal memory
access mode is restored, but the output of the ‘-d’ option
(debug) will still corrupt the screen.
Since high-speed text mode uses a different internal font
format, SVGATextMode will not allow you to switch between the
two modes when font loading is not enabled. In practice, it’s
wise to always enable font loading when you also enable the high
speed font mode. This way you will allow an easy escape (=re-run
SVGATextMode) when ill-behaved programs (or users...) load a
font without first telling the S3 chip about it, as SVGATextMode
clockchip_X (S3 + ICD2061a or ICS9161)
The ICD2061a and ICS9161 clockchips don’t cooperate very well with the
XFree86 X-server. When the X-server switches back to text mode (either
due to a VT-switch or completely stopping the server), it restores the
wrong textmode clock.
This is because both X and SVGATextMode use (i.e. reprogram) the same
clock index for their clock, and since the clock programming values
cannot be read back from the chip, the X-server is unable to restore
the correct clock when it stops. This causes wrong refresh frequencies,
or worse even, a non-syncing display.
The option "clockchip_X" will change SVGATextMode’s behaviour so that
it uses clock index #1 for the text mode clock instead of index #2.
This will allow the X-server to switch back to the correct textmode
There is a catch however... Clock #1 is a standard VGA clock, and is
supposed to be 28 MHz, and nothing else. Any program that relies on
that, will subsequently fail to set the correct video mode (svgalib,
the XFree86 clock probe and the DOS BIOS are just a few examples).
Especially when you reboot to DOS, clock #1 does not get reset by the
VGA card’s BIOS because it assumes it’s still at 28 MHz.
The solution here is to do an "SVGATextMode 80x25x9" just before
rebooting the machine. This will reset clock #1 to 28 MHz. The ideal
place for this is /etc/rc.d/rc.0, which is a script file that gets
called just before rebooting.
sync_on_green (S3 + Ti302X ClockChip/RAMDAC)
Enable the sync-on-green feature on these cards.
Normal VGA signals carry the H- and V-syncs on a separate wire,
requiring 5 signal wires (R, G, B, H, V) in total from VGA card to the
monitor. Some (mostly high-end) cards however allow connecting to a
monitor with just 3 wires instead. In that case, both sync signals are
embedded onto the green channel. This requires a monitor that knows how
to deal with this (in most cases, those monitors can only deal with
such signals. If you have such a setup, this option is for you.
Note: Although all Ti302X RAMDAC’s support sync-on-green, not all VGA
cards will work with it because of the way they were designed (dixit
16color (all cards)
The default Linux text console behaviour is to provide 8 possible
colors plus hardware blinking. This means you can produce blinking text
on the console.
The "16color" option changes that behaviour: all "blinking" attributes
get translated into "highlighting": instead of blinking text, you get
high-intensity text, which effectively translates into 16 possible
When this option is not specified, the standard 8-color + blinking mode
iso_font9 (all cards)
Even when using 9-bit wide fonts, the actual font data is always 8
bits, defining only the first (leftmost) 8 pixels of the character. The
9th pixel is "made up" by the VGA chip depending on a few rules.
Normally the 8th column is copied to the 9th column for character codes
in the range 0xC0 to 0xDF. This looks very good on most VGA fonts,
where characters in this range are line-graphic characters (aka box-
characters). However, this makes some ISO-compatible fonts look very
ugly: ISO does not have line graphics characters but normal fonts in
the region 0xC0 - 0xDF. This option disables the automatic pixel
replication feature so that the 9th column will always be blank for all
Move the textmode window to the top left of the screen. This is of
course only useful if it is smaller than the total display size.
This is a list of all allowed clock chips, per chipset. They are the
same as in Xfree86-3.1.2. In addition, the ICS5301/5341 GenDAC used on
some ET4000W32(p) cards is also included.
ibm_rgb5xx (Needs ‘RefClk’ line in config file)
Cirrus (If not specified, "Cirrus" is assumed)
Laguna (for the CL-GD546x chips. This is required for those
chips, otherwise the standard "Cirrus" is assumed, which will
not work on these cards)
ics5341 (For ET4000 cards with GenDAC. Also works for ICS5301)
et6000 (obviously -- it has a built-in clock generator)
tgui9320 (Trident TGUI9320LCD)
tgui9440 (Trident accelerators with a number higher than or equal to TGUI9440)
cyber938x (Trident CYBER938x)
MACH64 mach64 (internal programmable clockchips)
MODE CONFIGURATION LINES
This section describes the guts of the TextConfig file: the mode
description lines. It’s long, and probably not long enough...
First of all: if you are not familiar with configuring the X-server,
you’d better start off there, as it is MUCH more stable, MUCH less
buggy, and MUCH better documented. You will also learn how to use
several tools (vgaset, SuperProbe, ConfigXF86, ...) which can aid you
to design your own custom X-Windows mode. The same tools can then be
For people less familiar with monitor timing stuff, and unwilling or
unable to consult the XFree86 documentation, read the monitor-
timings.howto in the doc directory of the SVGATextMode distribution.
It’s a small (and incomplete) introduction on how monitors work, and
what you need to send it to get some sort of a picture on it.
You will probably need the X-server (e.g. to do ’X -probeonly’) to
determine your available pixel clocks, and maybe even to determine what
chipset you have. The distribution contains a script that can help you
determine the pixel clocks in case there is no way to get by them.
The text mode lines are the real thing: they set up the video card for
the mode you request. A TextConfig file can contain LOTS of
configuration lines. It would be best that you leave the "default"
config lines in the example TextConfig file as they are.
Add your own configuration lines at the end. If you patch a line, first
copy it to the end of the file, and change it there. You don’t have to
rename it, as SVGATextMode will take the LAST line with the same label
it finds. So if your custom line, with the same name as an "original"
one is at the end, the customized line will be used.
That way you will always have the original lines as a reference, in
case you screw your own line up. You can then always copy it again.
Now let’s analyse a new text mode:
"100x37" 50 800 872 976 1040 600 632 638 670 -Hsync +Vsync font 8x16
For compatibility with XFree86 mode lines, the mode line can optionally
be prepended with "modeline":
modeline "100x37" 50 800 872 976 1040 600 632 638 670 -Hsync +Vsync font 8x16
The entire mode line should be on a single line. Use SVGATextMode to
get a screen with at least a 100 chars on a line, and reformat the
manual page. This way it won’t look like a folder! Is this a chicken-
Below is a piece-by-piece examination of the different parts in the
This is the identification string for this text mode. If you the type
the program will try to program the mode described on this line.
This label means absolutely nothing to SVGATextMode! It’s not
because the label says "132x43" that you will get a 132x43 mode.
You will get the resolution and size described in the parameters
following the label. If those parameters result in a 100x37
mode, that’s what you will get. Just changing the label from
100x37 to 132x43 will NOT do anything useful (except renaming
the mode): it will still result in a 100x37 mode.
Also, remember that when you change the font size, this also affects
the number of text lines: if you were to change the font size in the
100x37 mode line described here from 8x16 to 8x32, you will get a
100x18 mode and NOT a 100x37 mode with a larger font.
The pixel clock frequency. It determines the clock frequency (in
MegaHertz) at which the pixels will be pushed towards the monitor. It
is entered as a floating point number.
Unless you have a freely programmable clock chip (using the ClockChip
line, or with a Cirrus Logic card) on your VGA card, SVGATextMode will
try to find the closest available pixel clock in the Clocks line,
allowing a slight deviation of a few MegaHertz: asking for a clock of
50 MHz, and having only a 49 MHz clock will make SVGATextMode use the
49 MHz clock. This shouldn’t be a problem, because monitors always
allow for a fairly large deviation of their input frequencies.
800 872 976 1040
Horizontal timing parameters: resp. active video size (number of active
or visible pixels per video line), start and stop position of the
Horizontal sync signal, and the full width of a video line, including
active size and blanked (unused) size.
See the XFree documentation for a thorough understanding of these, or
try the monitor timing tutorial in the distribution. See also below in
the section on 9-pixel fonts for some explanation on the effect of
selecting an 9-pixel font on these timings!
Your textmode will have one eighth the number of characters per line as
in the active video size (the first number of the horizontal timing
parameters) REGARDLESS of the font size specified. So in this case :
800/8 = 100
characters per line.
Calculating the horizontal frequency (which your monitor must be able
to cope with, if you want to use this particular mode) is easy: just
divide the pixel clock by the total amount of pixels on a single line:
50000000 / 1040 = 48076 Hz, or 48 kHz
This calculation is ONLY true for 8-pixel wide modes! If this were to
be a 9-pixel wide mode, and the clock remained at 50 MHz, then we’d
50000000 / 1040 * (8/9) = 42734 Hz, or 42.7 kHz
If you want a general purpose formula: here’s one:
Hor_freq = pixel_clock / total_hor_pix * (8 / font_width)
600 632 638 670
Vertical Timings. Equivalent to the horizontal ones. The number of text
lines (rows) in your text mode will depend on the font size selected:
number_of_textlines = number_of_active_lines / font_height
Here we have 600 active lines, and a font of 16 pixels high (see
below), so there will be 600/16 = 37 text lines.
Deriving the vertical refresh is even easier than horizontal: just do
Vert_freq = Hor_freq / total_vert_lines
In this case, we’d get 48076 / 670 = 71.75 Hz.
Mode line attributes
The following sections describe the possible attributes a mode line can
have. They define the sync polarities, the font size to use, and
Hsync and Vsync polarity (positive (+Hsync) or negative (-Hsync)).
Most modern monitors don’t care about sync polarities, BUT most USE
Simple fixed-frequency or dual frequency monitors (so non-multisync,
e.g. only 32 and 48 kHz, instead of the entire range from 32 to 48),
and some non-digital-control ones use the polarities to change their
vertical screen size.
Cheap monitors have the habit of not having a constant vertical image
size, independent of the vertical refresh frequency. So your monitor
might use the entire screen at a normal 60 Hz frequency, but the image
is larger (higher) at lower frequencies, and smaller (more flattened)
at higher ones.
These VGA monitors use the sync polarities to distinguish between
several vertical refresh frequencies, and to adapt their vertical size.
A MAG PMV1448 for example is a fixed 32/48 kHz dual-scan monitor. At
800x600@70Hz, the screen is either only half the vertical size, or the
entire screen, depending on sync polarity. So some experimenting with
polarities might give you a full screen, even with >70 Hz refresh
rates. (The same applies to the XF86Config as well!)
More expensive monitors, mostly with "digital control", use the sync
polarities COMBINED with the incoming horizontal and vertical
frequencies to determine whether they will take their screen parameters
(amongst which the vertical screen size) from a database of standard
resolutions, or from the (scarce!) user-settable modes. If you succeed
in using one of those default modes, that saves you one more free user-
settable mode. Taxan 875 monitors for example have only 4 programmable
modes, and when you’ve just tweaked X-windows into some weird modes,
you might run out of user-settable modes. It might be a good idea to
try to create standard SVGA timings for your text modes (including the
correct sync polarities), so your monitor recognises them, without
needing an extra entry in its screen parameter database.
The sync polarities are an option. They are not required: if none are
given, SVGATextMode will assign sync polarities according to the VGA
standards, depending on the number of active video lines:
0..399 lines: +Hsync -Vsync
400..479 lines: -Hsync +Vsync
480..767 lines: -Hsync -Vsync
768 and up: +Hsync +Vsync
Font size: "font HxV" selects the horizontal size (character width = H)
and vertical size (character height = V) of the text mode font. The
possible ranges are:
H = 8 or 9
V = 1 to 32
These are the hardware limits. Not all of them are as useful. Don’t be
surprised if you cannot read text of only 1 pixel high!
The VGA chip must know these values in order to render the font
correctly. The font size together with the H- and V-timings from (2)
and (3) determine the number of characters per line, and the number of
lines per screen.
If the font size is not defined, 8x16 will be assumed.
When this attribute is added to the mode line, DoubleScanning will be
enabled. This means each video line will be drawn TWICE instead of just
once. This is used on VGA cards to emulate CGA modes like 320x200.
If you would (and could) let a VGA monitor display just 200 real lines
for a 320x200 mode, it would look awful: a VGA monitor was designed to
display at least 350 lines, and at only 200 lines you would see a lot
of empty space between the lines. Most good monitors (especially 17
inch and up) even show this phenomenon at the standard VGA 640x480
The DoubleScan mode is used to overcome this problem: for a 200-line
mode, the VGA card actually outputs 400 lines, displaying each actual
line in the VGA memory twice.
There is one "side effect" with this little trick: the vertical refresh
frequency drops to half the value you would think from the timings you
enter in the modeline. Let’s look at such an example:
"S50x15" 32.5 400 432 496 512 240 241 242 256 font 9x16 DoubleScan
Calculating the refresh frequencies would give:
horizontal refresh = 32500000 / 512 * (8/9) = 56423 Hz
vertical refresh = 56423 / 256 = 220.4 Hz
Only, Doublescanning is enabled, so the VGA will actually output 256*2
= 512 lines to the monitor instead of 256. So the actual vertical
refresh is not 220, but 110 Hz.
This might be pretty useless, but the Doublescan option together with
the maximum font height of 32 lines results in an _actual_ maximum font
height of 64 lines...
Using 9-pixel wide font sizes
The VGA hardware is a strange thing. And using 9-pixel fonts is amongst
the stranger ones.
The timing parameters are the same for both 8 and 9-pixel wide fonts,
except for the clock. Horizontal timings in VGA cards are _always_
specified in 8-bit wide CHARACTERS, not in PIXELS, although the
TextConfig file format uses pixels.
Hence the restriction that horizontal timings should be a multiple of 8
(if they’re not, they will be rounded down).
When setting the character width of an existing 8-pixel wide mode to 9,
horizontal timings are still in 8-bit characters. So both modes will
result in the SAME amount of characters per line, but the VGA chip will
count 8 pixels per character in the first case, and 9 in the second
Take for example a standard 80x25 mode:
"80x25x8" 25.175 640 680 776 800 400 412 414 449 font 8x16
and its 9-pixel wide derivative:
"80x25x9" 28.3 640 680 776 800 400 412 414 449 font 9x16
Both modes produce the same screen size (80x25), using the same display
refresh frequencies (31.5 kHz, 70 Hz).
But in the first case, the total _actual_ pixel-count at the end of the
video-line is (800/8)*8, and (800/8)*9 in the second case !!! To
achieve the same horizontal frequency of 31.5 kHz, the second mode
needs a higher clock:
(9/8)*25.175 MHz = 28.3 MHz
and that happens to be the second standard VGA clock, which is
available on ALL VGA cards. Now you know why they added it in the first
This example should warn you about changing modes from 8-wide to 9-wide
or vice-versa: if you don’t change the clock with the same 8/9 ratio,
the display refresh rates will change, and they might fall outside the
allowable range for the monitor (i.e. it will not synchronize to the
new frequency, or SVGATextMode will suddenly not allow the mode
This is an optional parameter that requests an additional shift of the
display to the left. The <shift_amount> can be any value between 0 and
3. It shifts the screen to the left with an equal amount of character
cells (i.e. "HShift 0" doesn’t do anything).
This parameter is useful for mode lines where you can’t get the display
to move to the left side enough by changing the sync position. Take for
example this modeline:
"40x15x9" 14.15 320 376 400 400 240 241 242 25 font 9x16 DoubleScan
If this mode is still too much to the right of the monitor instead of
nicely centered, there is not much you can do to fix this: the sync is
already moved the the extreme end, and making it shorter (by moving the
second number (376) closer to the third (400) will probably make your
monitor go out of sync.
Enter the HShift parameter: with the same sync position, it moves the
screen 0, 1, 2 or 3 characters to the left. This has the same effect as
adding 0, 8, 16 or 24 to the HSYNC position numbers, except that it
still works if that would place the sync BEYOND the end of the maximum
There is another reason to use this parameter. Some VGA chips seem to
have problems with very-low-resolution modes (like the 40x15 one
above). If you put the sync too much to the right (but still "legal"),
you get lots of "snow" on the screen; almost the same stuff you get
when using a clock that is too high.
In this case, putting the sync close to the end of the active video
instead of close to the other end solves that problem. You can then use
the HShift parameter to get the display nicely centered again.
The S3 BIOS uses this exact method for their standard VGA low-res text
A configuration file has no bugs, of course. Any problems with it are
either your own, SVGATextMode’s, the man-file author’s, or Murphy’s
There are a few limitations. One of them being the 16K (16384)
characters-per-screen limit. This is a limit imposed by the way the
kernel sets up VGA textmode memory, and can be doubled if required (see
below). You would need to define an awesome screen size before running
into that limit: 160x100 or 180x80 characters per screen is still
Increasing the number of characters on the screen reduces the size of
the scroll-back buffer: since there are always (?) 16k chars on one
screen, the scroll-back buffer will get the remainder of the 16k. If
you have a screen size with 16k chars, there will be no scroll-back
The more hacker-minded among you might want to experiment with a
special #define in the kernel sources (VGA_CAN_DO_64KB, in
/usr/src/linux/drivers/char/vga.c), that allows more (32K) characters
per screen. This requires recompiling both the kernel and SVGATextMode
(and the latter needs the same define in the Makefile).
Another limit is the maximum amount of clocks in all the clocks lines
The program which needs the TextConfig file
The configuration file described here
SVGATextMode was written by Koen Gadeyne <email@example.com>, with
help from a lot of local and remote Linux fans. See the CREDITS file in
the distribution for a full list of all helping hands.
The XFree86 configuration file (Xconfig, XF86Config) has been the main
guideline in creating the TextConfig format.
Textmode manipulation/enhancement tool
An XFree86/SVGATextMode VGA mode grabber
Configuration file for XFree86
Non-accelerated SVGA X Window System servers for UNIX on x86
Accelerated X Window System servers for UNIX on x86 platforms
with an S3, Mach8, Mach32, Mach64, P9000, AGX, ET4000/W32 or
8514/A accelerator board
A description of common problems related to SVGATextMode.
Two files describing some ET4000 specific stuff
A short tutorial on the Real Meaning of Monitor Timings