TextConfig(5)
NAME
TextConfig - Configuration file for SVGATextMode
DESCRIPTION
SVGATextMode uses a configuration file normally called
`TextConfig' for its initial setup. The default place for
it is
/etc/TextConfig
It has a similar syntax as the configuration file for the
XFree86 X-Windows server. It adheres more or less to ver-
sion 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
structured.
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 enywhere 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 ignored.
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. Modelines can have
the prefix "modeline", but this is not a requirement.
Mode description lines start with an opional `modeline',
and then a mode label, (any text enclosed in quotes), fol-
lowed 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 similar to:
./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.
Safety tip
When trying to create a new mode of your own, consider
"testing" it first non-destuctively: use
SVGATextMode -n <<MyNewMode>>
(note the '-n' option) before doing the real thing (=with-
out '-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.
KEYWORDS
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.
ChipSet <some_chip>
This keyword tells SVGATextMode which SVGA chipset needs
to be programmed. The syntax is straighforward:
Chipset "S3"
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 dif-
ferent 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 poten-
tial 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 sup-
ported chipsets.
ClockChip <some_clockchip>
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.
Example:
ClockChip "ICD2061a"
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 this problem.
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 sup-
ported cards with unsupported clock chips, because the
clock porgramming 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 rougly 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 SVGATextMode):
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 switch-
ing). 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 SVGA-
TextMode mode will be restored properly.
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 used!
When the ClockProg is run by SVGATextMode, two arguments
are passed to the command. The first is the clock fre-
quency 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 suc-
cessful, and something in the range 1-254 otherwise.
NOTE: as mentionned 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.
Option <option_string>
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 message.
Example:
Option "ClockDiv2"
See the separate OPTIONS section for a full list of all
options and their meaning.
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 sec-
tion in this manual page), the clocks line MUST be speci-
fied, even if the clock program is programming a fully
programmable chip. By requiring a clocks line, the Clock-
Prog option can support both programmable clocks, as fixed
clock from a list (i.e. the Clocks line). See the Clock-
prog section for a full explanation of the use of the
"ClockProg" keyword.
All cases not mentionned above will need a "Clocks" line,
or a set of clocks lines.
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 be used.
The order of the clocks in the one or more clocks line(s)
will also determine their order: most VGA clocks genera-
tors 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 oth-
ers) a list of clocks on your card. See the XFREE manuals
for more information: XF86Config(5), XF86_SVGA(1),
XF86_Accel(1).
WARNING 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 cor-
rectly fior this card in the Xconfig file, XFree86
WILL give wrong results! You have been warned. See
also the `doc' directory in the SVGATextMode dis-
tribution for more explanation about this.
WARNING 2:
Just to be on the sure side, another warning: SVGA-
TextMode 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.
WARNING 3:
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 mentionned termi-
nals after switching to another mode. This "resizing" con-
sists of sending a `SIGWINCH' to all specified virtual
terminals.
The usefulness of this option depends on the Linux kernel
version you are running (as reported by `uname -r'). SVGA-
TextMode detects the kernel version, and acts accordingly,
as described below.
There are three distinct cases:
Kernels older than 1.1.54: run-time terminal resiz-
ing 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 vir-
tual 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 be ignored.
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 con-
trolling terminal, and hence it doesn't get sent this SIG-
WINCH signal.
ResetProg <</path/to/ResetProg>>
The "reset program" is called when SVGATextMode has fin-
ished its job succesfully, but only when a ResetProg is
defined.
The path must be a fully specified path, as in
ResetProg "/etc/resize_gpm"
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.
Example:
SVGATextMode 100x37
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
FontProg <</path/to/Font_Loader>>
FontPath <</path/to/textmode/fonts>>
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
Option "LoadFont"
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 exter-
nal program, that will be called with the specified font
as an argument. It can for example specified as:
FontProg "/usr/bin/setfont"
Where "/usr/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, SVGA-
TextMode will use the default path "/usr/bin/setfont".
The path may contain an entire command line within the
quotes. This allows you to say:
FontProg "/usr/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 irradicate the original uni-
code 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. mini-
com).
Secondly, you can also tell the font program where
the fonts are located:
FontPath "/usr/lib/kbd/consolefonts"
If not specified, the font path defaults to
"/usr/lib/kbd/consolefonts".
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 warn-
ing 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:
/usr/bin/setfont /usr/lib/kbd/console-
fonts/Cyr_a8x16
One final note on font sizes. VGA fonts are ALWAYS 8 pix-
els 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 char-
acters 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 9th.
Cursor <<start>>-<<end>>
Depending on personal preference, and on the type of
screen you work on, the standard undercore 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 configura-
tion 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 cursor).
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.
example:
cursor 28-31
results in an underscore cursor for ALL text modes, while
cursor 0-31
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 SVGAtextMode (yet?).
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 /linux/kernel/patches/console/noblink.tar.gz
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 can-
not 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:
HorizSync 56
will allow a horizontal sync range of 55.7 to 56.3 kHz.
This is useful for fixed-frequency monitors (mostly work-
station displays), or some old standard VGA screens.
A more complex line could look like this:
HorizSync 30.5-32,48.2,56
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 fol-
lowing line:
HorizSync 30-64
Not defining the HorizSync/VertRefresh variables implies
the default values:
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.
DacSpeed <<Frequency>>
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 mentionning 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 lower.
The default DacSpeed values are:
VGA, TVGA9000, VIDEO7 and PAVGA1
45 MHz
TVGA8900, WDC90C0X, WDC90C1X, WDC90C2X, WDC90C3X
50 MHz
Cirrus, ATI and ATIMACH32
55 MHz
ET6000, MATROX, OTI67, OTI77 and ATIMACH64
60 MHz
S3, ALI, OTI87
70 MHz
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
50 MHz
ARK, SiS, AL2101, NCR77C32, ET3000
60 MHz
NOTE: The maximum text mode clock is increased by a fac-
tor 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 pixel
clocks.
IMPORTANT NOTE:
Many apparent display problems when using SVGA-
textMode 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
empyrical. This means they resulted from experi-
ments, 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 sheets.
If you see unstable characters, wrong characters
(e.g. a "z" where you expect an "e"), character
crawling, Mighty Morphing Power Characters (TM),
colomns of characters from the left of the screen
repeated towards the right, drop-outs (fixed posi-
tions 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.
RefClk <<Frequency>>
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 stat-
ing the memory clock):
(**) 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.
WARNING:
When using SVGATextMode with an IBM RGB RAMDAC
together with the XFree86 X-server, you must define
the RefClk in your X configuration file (XF86Con-
fig) 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 the RefClk.
MClk <<Frequency>>
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 Gen-
DAC/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 sys-
tems, 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 PRE-
PARED. 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 sys-
tems, DON'T TOUCH THE MCLK!
DefaultMode <<Mode_label>>
Using this optional keyword, one can define which mode
should be used when SVGAtextMode is started without any
mode label on the command line.
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
DefaultMode "80x25x9"
is in the TextConfig file somewhere, then just typing
SVGATextMode
at the shell prompt is exactly the same as typing
SVGATextMode 80x25x9
BorderColor <<Color_Index>>
This option will set the screen border color to a differ-
ent 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 screen.
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 pro-
vide sufficient blanking on both sides, above and below
the screen.
UnderLine <<Underline_position>>
Underlining is disabled by default, unless you define an
underline position with this option. The <Underline_posi-
tion> must be a number in the range 0..31, and it defines
the relative position of the underlining.
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: sup-
pose 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 text).
As said above, not defining the underline position dis-
ables underlining. Any characters that would be under-
lined, 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.
Echo <<Some_string>>
The string (enclosed in double quotes) is printed on the
standard output. This could be used for debugging pur-
poses, or to add some warning to the TextConfig file that
is printed each time you run SVGATextMode.
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 possi-
ble potential, and that he/she should edit the TextConfig
file to enable support for his/her chipset.
Supported CHIPSETs
Until now, the following VGA chipsets are supported:
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.
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".
ET3000
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 Millenium) and "mystique" (for the Mystique)
are the clockchips for the respective cards.
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
CIRRUS Cirrus Logic chipsets (clgd542x, clgd543x,
clgd546x, clgd62x5 -- with "x" representing any
number).
TVGA9000
Older Trident cards using the TVGA9000 chipset
(those with max 512k RAM)
TVGA8900
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.
WDC90C0X
Western digital. WDC 90C00.
WDC90C1X
Western digital. WDC 90C10
WDC90C2X
Western digital. WDC 90C20
WDC90C3X
Western digital accelerated SVGA chip. Most common
is the WDC 90C33, also 90C31.
ATI All ATI cards BEFORE the MACH32
ATIMACH32
ATIMACH64
Only MACH64CT 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, OTI87
Oak Technology chipsets.
SIS Sis chipsets.
RealTek
RealTek chipsets.
ARK ARK1000 and ARK2000 chipsets.
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.
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.
OPTIONS
This section contains a list of all allowed special option
flags, as entered on an
Option "option_string"
line. They change the default behaviour for each card or
function programmed into SVGATextMode. Currently the fol-
lowing 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 option flags.
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.
IMPORTANT NOTE:
The importance of this "hibit" stuff cannot be
stressed enough. It might be that your XFree86 X-
server worked fine before you started using SVGA-
TextMode 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 dis-
play 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 option.
ET4000_AltClockSel (ET4000)
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 used
here).
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 clock selection.
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.
WARNING:
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.
SPEA_Mercury (S3)
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 dis-
abled).
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 clock.
A final warning: The division by two option is unknown to
most other programs, and could cause (additional) coopera-
tion problems with those programs. If you loose video when
using SVGATextMode together with other VGA-related pro-
grams, try disabling this option, and see if the problem
persists.
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 men-
tionned 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 confi-
dent that the system is stable enough.
In this case, the SyncDisks option can at least avoid data
loss when the system hangs, although it cannot avoid the
filesystem 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_HSText (S3)
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 afterwards.
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 "set-
font" 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 char-
acters 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.
WARNING:
Since high-speed text mode uses a different inter-
nal 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 pro-
grams (or users...) load a font without first
telling the S3 chip about it, as SVGATextMode does.
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. repro-
gram) 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 pixel clock.
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 XF86_Accel).
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 "blink-
ing" attributes get translated into "highlighting":
instead of blinking text, you get high-intensity text,
which effectively translates into 16 possible colors.
When this option is not specified, the standard 8-color +
blinking mode is selected.
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-compat-
ible 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 fea-
ture so that the 9th column will always be blank for all
characters.
CLOCKCHIPS
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.
S3
icd2061a
ics9161a
dcs2834 (Untested!)
sc11412 (Untested!)
s3gendac
s3_sdac
ti3025 (Untested)
ics2595
ics5300
ics5342
ch8391 (Untested!)
S3Trio
S3Virge
stg1703 (Untested!)
ti3026 (Untested!)
ibm_rgb5xx (Needs `RefClk' line in config file)
Cirrus Logic
Cirrus (If not specified, "Cirrus" is assumed)
fBLaguna
otherwise the standard "Cirrus" is assumed, which
will not work on these cards)
ET4000
ics5341 (For ET4000 cards with GenDAC. Also works for ICS5301)
icd2061a
ARK
ics5342
ET6000
et6000 (obviously -- it has a built-in clock generator)
TGUI
tgui9320 (Trident TGUI9320LCD)
tgui9440 (Trident accelerators with a number higher than or equal to TGUI9440)
cyber938x (Trident CYBER938x)
MACH64 mach64ct
Matrox
ti3026
mystique
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, Super-
Probe, ConfigXF86, ...) which can aid you to design your
own custom X-Windows mode. The same tools can then be used
here.
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 incom-
plete) 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 distri-
bution 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 ref-
erence, 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 SVGA-
TextMode 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-and-egg problem?
Below is a piece-by-piece examination of the different
parts in the mode line:
100x37
This is the identification string for this text mode. If
you the type
SVGATextMode "100x37"
the program will try to program the mode descibed on this
line.
IMPORTANT NOTE:
This label means absolutely nothing to SVGA-
TextMode! 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.
50.00
The pixel clock frequency. It determines the clock fre-
quency (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 avail-
able 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 tuturial in the dis-
tribution. 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 charac-
ters per line as in the active video size (the first num-
ber 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 partic-
ular 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 get:
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 textlines (rows) in your textmode 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 textlines.
Deriving the vertical refresh is even easier than horizon-
tal: 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 polariries, the
font size to use, and DoubleScan operation.
-Hsync +Vsync
Hsync and Vsync polarity (positive (+Hsync) or negative
(-Hsync)). Most modern monitors don't care about sync
polarities, BUT most USE them.
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 hori-
zontal and vertical frequencies to determine whether they
will take their screen parameters (amongst which the ver-
tical screen size) from a database of standard resolu-
tions, 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
textmodes (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 8x16
Font size: "font HxV" selects the horizontal size (charac-
ter width = H) and vertical size (character heigth = V) of
the textmode font. The possible ranges are:
H = 8 or 9
V = 1 to 32
These are the hardware limits. Not all of them are as use-
ful. 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 charac-
ters per line, and the number of lines per screen.
If the font size is not defined, 8x16 will be assumed.
DoubleScan
When this attribute is added to the mode line, DoubleScan-
ning 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 mode.
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 pix-
els per character in the first case, and 9 in the second
case.
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 fre-
quency 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 place ;-)
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 anymore).
HShift <<shift_amount>>
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 modelines 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 sync
position.
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 modes.
BUGS
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 fault.
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
possible...
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 buffer...
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 together: 64.
FILES
/usr/sbin/SVGATextMode
The program which needs the TextConfig file
/etc/TextConfig
The configuration file 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. See the CREDITS file in the distri-
bution for a full list of all helping hands.
The XFree86 configuration file (Xconfig, XF86Config) has
been the main guideline in creating the TextConfig format.
SEE ALSO
SVGATextMode(8)
Textmode manipulation/enhancement tool
grabmode(8)
An XFree86/SVGATextMode VGA mode grabber
XF86Config(5)
Configuration file for XFree86
XF86_SVGA(1)
Non-accelerated SVGA X Window System servers for
UNIX on x86 platforms
XF86_Accel(1)
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
SVGATextMode/doc/FAQ
A description of common problems related to SVGA-
TextMode.
SVGATextMode/doc/README.ET4000*
Two files describing some ET4000 specific stuff
SVGATextMode/doc/monitor-timings.howto
A short tutorial on the Real Meaning of Monitor
Timings