MAN page from RedHat Other SVGATextMode-1.8-1.i386.rpm

TextConfig

Section: File Formats (5)
Updated: November 1997
Index

NAME

TextConfig - Configuration file for SVGATextMode

DESCRIPTION

SVGATextMode uses a configuration file normally called `TextConfig' for itsinitial setup. The default place for it is

: /etc/TextConfig

It has a similar syntax as the configuration file for the XFree86 X-Windowsserver. 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 morestructured.

Config file syntax rules

Basically, the TextConfig file is scanned on a line-per-line basis, with nospecific ordering whatsoever forced upon the user. A line can appearenywhere 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 allothers ignored. The only exceptions to that rule are the definitions thatcan 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 areconsidered the same label.

Empty lines are allowed. The last line will always be ignored (make sure thelast line is an empty one).

Any text following a # (hash) character is comment, and will beignored.

You must enclose text strings in double quotes ("). E.g. modelinenames (modeline "my_80x25"), option names (Option "LoadFont"), DefaultModenames, ClockChip names, Chipset names, etc.

Configuration lines start with a keyword, which tells SVGATextModewhat this line is about. Modelines can have the prefix "modeline", but thisis not a requirement.

Mode description lines start with an opional `modeline', and then a modelabel, (any text enclosed in quotes), followed by at least 9 numbersdescribing the mode timings. A description of the meaning of these modetimings should be in the MODE TIMINGS section. Note that the mode label isjust what the name says: a label. Even if the label says "100x37", itdoes NOT mean this will actually produce a 100x37 text mode. The modetimings determine that.

Lines not complying with any of the above restrictions, or lines that use anundefined keyword will produce a parsing error. The most common error isforgetting 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 aswell. 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 firstnon-destuctively: use

: SVGATextMode -n <MyNewMode>

(note the '-n' option) before doing the real thing (=without '-n'). This waythe program will show you what the new mode will look like, WITHOUT reallychanging anything. This allows you to check if the H and V sync values willwork with your monitor. And it avoids a blank screen because some number waswrong, and the mode line got screwed up.

KEYWORDS

Several keywords are used by SVGATextMode to define what the line willdescribe. This section only describes the syntax of the keywords, and somegeneral explanation. The complete syntax, with all possible entries for eachlabel 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 themany types of S3 cards around.

S3, as well as many other chipsets, have a range of different subtypesaround, but they basically are the same, and SVGATextMode only needs a tinybit of its full array of features (imagine what amount of the chip's fullpotential you were using in text mode _before_ SVGATextMode was around, ifit's still only a tiny part of it _with_ STM ;-)

Roughly speaking, the pixel clock programming is all that is VGA chipdependent from SVGATextMode's perspective.

Some chipsets are subdivided into different chipset ID's. This probablymeans the subtypes _are_ different, and so they must be differentiated inthe config file.

See the ChipSet section for a detailed listing of supported chipsets.

ClockChip <some_clockchip>

Mostly for S3 chipsets, ET6000, Matrox, Cirrus, some ET4000's and someTrident cards. This tells SVGATextMode that the pixel clock for this chipsetdoes not come from the "default" clock generator with (e.g.) 16 discreteclocks, but from a programmable clock chip. All the clock chip drivers fromthe XFree86 version 3.1.2 X-server are available, plus theICS5301/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 thecurrent 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 clockchips built-in (The ICD2061a and ICS9161). When using on of those XFREE clockchips, 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 thisproblem.

ClockProg <path/to/ClockProg> [textclock]

This tells SVGATextMode that the clock is to be programmed using an externalclock setting program, not the default or ClockChip method.

This is especially useful for unsupported cards, or supported cards withunsupported clock chips, because the clock porgramming is about the onlything that needs to know what chip we're talking about.

It's also a useful stub for plugging in replacements for buggy or wrongSVGATextMode clock code.

The syntax is rougly the same as the syntax for the XFree clock program, andindeed any clock program written for XFree 3 should plug in without aglitch. In theory.

Example (note the second argument is not necessary, and is ignored bySVGATextMode):

: ClockProg "/usr/sbin/pixclock_prg" 2

The Following paragraph, from the XFree docs, shows how this program must beused:

: "This optional entry runs the specified command to set the clock on thegraphics board instead of using the internal code. The command string mustconsist of the full pathname (and no flags). When using this option, aClocks entry is required to specify which clock values are to be madeavailable to the server (up to 128 clocks may be specified). The optionaltextclock value is used to tell the server that command must be run torestore the textmode clock at server exit (or when VT switching). textclockmust match one of the values in the Clocks entry. This parameter is requiredwhen the clock used for text mode is a programmable clock."

Note for SVGATextMode:the [textclock] argument is not used in SVGATextMode, since we'realready talking about text mode. The XFREE server WILL use this, so theSVGATextMode mode will be restored properly.

Note for XFREE users:You MUST define the textclock in your XF86Config file when you are using aclock program. XFree86 will not be able to restore the correct textmodeclock, UNLESS you tell it what clock was used!

When the ClockProg is run by SVGATextMode, two arguments are passed to thecommand. The first is the clock frequency in MHz as a floating point numberand the second is the index of the clock in the Clocks entry. When setting anew text mode using a ClockProg, SVGATextMode will execute the followingshell command:

: <path/to/clockprog> <frequency in Mhz> <clock index>

The command should return an exit status of 0 when successful, and somethingin the range 1-254 otherwise.

NOTE:as mentionned in the text above, you need to specify a clocks line, althoughthe 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 forexternal clock programs that program an "old-style" clock chip with just afixed set of (mostly 16) clocks, like most "cheaper" VGA cards use. In thatcase, the program will probably ignore the frequency parameter passed to it,but will use the index number to select the appropriate clock. In the othercase, the index will be ignored, and the specified frequency will beprogrammed.

The clock program path must be a fully specified path to a clocksetting program that is SETUID ROOT! If it is not correctly SETUID ROOT, youwill get an error:

: ./SVGATextMode: ERROR: 'system' returned error code 35584

No environment variables will be used. If your clock selection program usesanother 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 fewVGA cards. Any option enabled in the config file that is NOT allowed for theVGA 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 andtheir meaning.

Clocks <clock0> <clock1> [ <clock2> ... ]

The most important section in the TextConfig file (at least for somecards) is (are) the Clocks line(s). This entry in the config filetells 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 possibleclock 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 thecorrect pixel clock, see the appropriate section in this manual page), theclocks line MUST be specified, even if the clock program is programming afully programmable chip. By requiring a clocks line, the ClockProg optioncan support both programmable clocks, as fixed clock from a list (i.e. theClocks line). See the Clockprog section for a full explanation of the use ofthe "ClockProg" keyword.

All cases not mentionned above will need a "Clocks" line, or a set of clockslines.

Any line in the TextConfig file that starts with "Clocks" will be used, andall clock values will be appended into one big list of available clocks. Inother 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 alsodetermine their order: most VGA clocks generators are connected to the VGAchips with a series of wires, constituting a bus. For 16 clocks, there are 4wires, which are driven from 4 pins on the VGA chip, which are then drivenby a register in the VGA chip. If your clocks line would suggest the 4thclock is a 45 Mhz clock, SVGATextMode will then put a "4" on that 4-bit busin order to select that clock. If you lied (=the actual 45 MHz is the 5thclock, selected by putting a "5" on that bus), then you will not be gettingthe 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 meansthat there is no clock with that number (index). It must be there in orderto get the correct indexes for the ones following them (a "placeholder"). A0 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. Theeasiest solution that is available on most systems is the XFree86 X-Windowsserver. Typing X -probeonly should give you (amongst others) a list ofclocks 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 onunsupported cards or on badly supported ones. The most notorious ones arethe ET4000 cards. If the hibit option is not set correctly fior thiscard in the Xconfig file, XFree86 WILL give wrong results! You have beenwarned. See also the `doc' directory in the SVGATextMode distribution formore explanation about this.
WARNING 2:: Just to be on the sure side, another warning: SVGATextMode assumes the clockVALUES are correct. All timing parameters that you are given at the end ofthe program are based on those numbers! Saying that clock number 3 is 40 MHzwill make SVGATextMode behave as if that is the Absolute Truth (TM). It willuse that clock as if it were 40 MHz.
WARNING 3:: The clocks lines in the distribution TextConfig are just examples, and onlywork 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 beaffected by a possible screen resize, and need to be resized. It will resizeall mentionned terminals after switching to another mode. This "resizing"consists of sending a `SIGWINCH' to all specified virtual terminals.

The usefulness of this option depends on the Linux kernel version you arerunning (as reported by `uname -r'). SVGATextMode detects the kernelversion, 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 kernelat all, and SVGATextMode will only allow you to select modes that have thesame 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' lineis defined, SVGATextMode will be able to detect which of the first 16virtual terminals is active, and resize all those. All VT's with a numberhigher than 16 (/dev/tty16 and up) cannot be detected, and so they would notbe resized automatically. If a `Terminals' line is defined, all terminalsspecified in that line will be resized. So, in this range of kernelversions, the `Terminals' line is only useful when you have more that 16active VT's.
: Linux kernels versions 1.3.3 and up do all this resizing automatically, sothis line is not needed in that case, and will be ignored.

If you need the `Terminals' line, enter the terminal devices without theleading "/dev/":

: Terminals "tty6" "tty5" "tty4" "tty3" "tty2" "tty1"

This is equivalent to typing stty rows <y> cols <x> atevery of those terminals. With the added advantage that any applicationsrunning in those terminals will be sent a SIGWINCH signal by thekernel. Many full-screen terminal applications will redraw their screen intothe new sizes upon receipt of that signal.

But some programs will NOT know about the new screen size, and will not workcorrectly anymore after a screen resize. They need a more drastic approach: theResetProg.

An example of such a programs is gpm. SIGWINCH only gets sent to tasksrunning with a virtual terminal (/dev/ttyX) as a controlling terminal (theps command shows in the TTY field what the controlling terminal of atask is). Gpm runs with a mouse device (e.g. a serial line) as itscontrolling terminal, and hence it doesn't get sent this SIGWINCH signal.

ResetProg </path/to/ResetProg>

The "reset program" is called when SVGATextMode has finished its jobsuccesfully, 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 affectedwhen the screen size changes due to using SVGATextMode. It could for examplebe a script that kills selection and restarts it, or sends an explicitSIGWINCH to gpm, or sends some other application an appropriate signal tolet it know the screen has changed.

The reset program will be called with TWO arguments: the H and V size of thenew text mode.

Example:: SVGATextMode 100x37

will first switch to a 100x37 mode (if the config line with that labelactually 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 thetextmode fonts are stored, and the font selection table.

SVGATextMode can be told to automatically load a new font when the text modehas 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 external program, thatwill be called with the specified font as an argument. It can for examplespecified 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, SVGATextMode will use the default path"/usr/bin/setfont".

The path may contain an entire command line within the quotes. This allowsyou to say:

FontProg "/usr/bin/setfont -u def.uni"

This would be required if you load a raw font file without a unicode map init. Without that extra option, setfont would irradicate the original unicodemapping. If this sounds a bit cryptic: it means, amongst other things, thatyou will loose the "high-ascii" characters (aka box-characters) used by manytext-based menuing systems (e.g. minicom).

Secondly, you can also tell the font program where the fonts arelocated:

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 usedfor which character cell size. This is accomplished by entering a fonttable, as shown in the example below:

FontSelect "Cyr_a8x8"  8x8 9x8FontSelect "8x12alt.psf"  8x12 8x13 ...FontSelect "Cyr_a8x16"  8x16 9x16

For each possible character cell size you intend to use, a font file must bespecified. You do not have to add a font file for ALL possible combinationsof fonts from 1 to 32 pixels high and 8 to 9 pixels wide. But if you selecta text mode with a font size that has no entry in the font table, and fontloading is enabled, SVGATextMode WILL put you in the new text mode, butwon't change the font (since it doesn't know what font to load). It willissue a warning that font loading was enabled, but no font specified.

When all things are configured as above, and you resize the screen to a100x37, which uses a 9x16 font cell size (this information is in the modeconfig line for the 100x37 mode), then SVGATextMode will issue the followingcommand after resizing the screen:

: /usr/bin/setfont /usr/lib/kbd/consolefonts/Cyr_a8x16

One final note on font sizes. VGA fonts are ALWAYS 8 pixels wide. But thosethat are designed to work within an 8-pixel wide character cell, will mostprobably not use the rightmost pixel column. Or in other words: they willonly use 7 (or even 6) of the available pixels, since they are putback-to-back on the display in an 8-pixel wide font mode. The extra spacemust be left open so the characters don't stick together, making them a bitfuzzy 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-pixelwide cell, and others are designed for 9-pixel wide cells. BOTH howeverDEFINE only 8 pixels.

To make some special characters connect (like IBM box characters) withoutgaps, 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, thestandard undercore cursor might be unsatisfactory. This type of cursor forexample is too small to be useful on laptop screens.

This keyword allows a fully programmable cursor size. To avoid needing acursor definition on each and every text mode definition line, there is justONE cursor definition in the TextConfig file, which is then used for ALLtext modes. Defining the cursor style for _every_ text mode line would causeunnecessary clutter in those configuration lines.

The parameters define the starting and ending line of the cursor, but thisis not a 1:1 mapping! The size of the cursor depends on the size of theselected font. If you selected a 16-line high font, and then defining thecursor to show from line 7 to line 8, will put it smack in the middle of theline. defining the same numbers for an 8-line font would put the cursor onthe bottom of the text line (= and underscore cursor).

That's why the cursor definition as shown above will ALWAYS be relative to a32-line font (the largest possible font size). If the REAL font size issmaller, it will be scaled to fit that font size. So defining an underscorecursor for 32-line fonts will also get you an underscore cursor for any otherfont 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 inSVGAtextMode (yet?).

There is a kernel patch out that allows the cursor color and blink to beselected differently for each console through a separate program using vt200style escape codes. It's (at least) on the sunsite.unc.edu and its mirrorsin 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 fromgetting a mode from the VGA card it cannot handle. This is useful for bothavoiding the problem of accidently getting into a non-syncing mode, and alsoavoids the (very small) possibility of monitor damage due to extremelyout-of-range sync inputs (a monitor that gets destroyed by out-of-spec inputfrequencies is a poor design, but knowing that when it's broke doesn't helpa lot)

The <from> and <to> are floating point numbers in kHz (forHorizSync) or Hz (for VertRefresh). When a single number (= only <from>) isdefined, 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 forfixed-frequency monitors (mostly workstation displays), or some old standardVGA 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. Somedual- or triple-scan monitors can use this method.

A standard multisync screen could for example use the following line:

: HorizSync 30-64

Not defining the HorizSync/VertRefresh variables implies the default values:

HorizSync 30-32          # 30 to 32 kHzVertRefresh 50-80        # 50 to 80 Hz

Changing these values BEYOND what your monitor can handle, COULD result indamage 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 forthe specified chipset. Since most VGA card manufacturers don't bothermentionning this value in their data sheets, the defaults were "guessed"from reports from users. The values are by no means "absolute", and they areno guarantee that staying below them will NOT cause trouble (although it'spretty sure), and also they are no guarantee that anything ABOVE thatfrequency will NOT work...

Depending on the quality of your card, and especially of the speed of theRAM 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 commonlydefined 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 clockthat was "guessed", rather than tested. This is because the author does nothave 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 sucha card, you are encouraged to report your findings to the author, so he canadjust 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 factor of 9/8 when a 9-pixelwide font is used. A 60 MHz maximum clock is thus increased to 67.5 MHz forthose modes. This is due to the way the VGA textmode hardware functions: thereal limit for textmode is not the pixel clock, but the actual number ofcharacters that must be fetched from the VGA memory per second. Since9-pixel fonts take 9/8 times as much time to draw as 8 pixel fonts, theywill allow an 9/8 times as high pixel clock as well. In other words, with amaximum pixel clock defined at 60 MHz, you will still be allowed to selectmodes with 9-pixel fonts and 67 MHz pixel clocks.

IMPORTANT NOTE:

Many apparent display problems when using SVGAtextMode with a relativelyhigh pixel clock are caused by the VGA card not being able to cope with thehigh clock. TextMode clocks generally cannot be as high as graphics modeclocks. Read the file `doc/FAQ' in the SVGAtextMode distribution for amore in-depth discussion about this.

The limits given above (and used as a default) are empyrical. This meansthey resulted from experiments, and are thus not taken from the VGA chipmaker's specifications. This is the correct place to introduce theexpression "your mileage may vary": your card may be better, or worse. VGAcard makers generally don't mention maximum text mode clocks (as opposed tomax. graphics clocks, which are ALWAYS specified) in their data sheets.

If you see unstable characters, wrong characters (e.g. a "z" where youexpect an "e"), character crawling, Mighty Morphing Power Characters (TM),colomns of characters from the left of the screen repeated towards theright, drop-outs (fixed positions on the screen where characters won'tdisplay) characters shifted down by one pixel line relative to the others,or something closer to noise than to text, you are most probably over thelimit 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 PLLfrequency generator is.

It is vitally important that this value is set correctly, or SVGAtextModewill 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 newerversion), 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 memoryclock):

: (**) 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 havebought such an expensive VGA card in the first place. Send me that card, andI will send you mine back: it's a lot cheaper, it is just as good in textmode, and it doesn't need any fiddling with RefClocks and the likes. You'llhave 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 tofind out by what ratio the clock is programmed wrong, and then scale theRefClk accordingly.

E.g. if you just enter 20 MHz as the reference clock, and all text modeclocks turn out to be wrong by a factor 0.716, then the REAL RefClk valuewill probably be 20.0 * 0.716 = 14.32 MHz.

This method will of course give you a non-syncing display for many textmodes, but that is inevitable. Be prepared for it.

WARNING:

When using SVGATextMode with an IBM RGB RAMDAC together with the XFree86X-server, you must define the RefClk in your X configuration file(XF86Config) also. The XFree86 server can probe for this clock, but onlydoes so reliably when being started from a standard (80x25) text mode. Afterhaving run SVGATextMode, you'll probably be in a non-standard mode (that'swhat it's made for after all), and then the X-server cannot probe the RefClkcorrectly 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 willbecome. Both in TextMode, svgalib or XFree86.

Specifying the MClk will instruct SVGATextMode to change the memory clock tothe new value (in MHz).

This is only possible on cards with a GenDAC (S3 GenDAC/SDAC, and theICS5301/5341 used on some W32 boards).

For text modes, this will in most cases allow you to use even higher pixelclocks than before, and in graphics modes, you might find an increase inspeed of up to 30%. But...

EXTREMELY IMPORTANT WARNING:

If you try fiddling with the memory clock without reading this, you're suregonna get suckered.

This option was created for those who just _need_ to tune their machineuntil it just doesn't melt, or beyond (like me). I am not saying this coulddamage 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 tochange 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 100MHz will NOT.

Secundo, don't try to set it too high. If you do, your system will crash in amajor way. Let me repeat this: your system will crash as it has nevercrashed before. It has done so many times while I tried it (though I nevergot 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!

DefaultMode <Mode_label>

Using this optional keyword, one can define which mode should be used whenSVGAtextMode 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 modedefinition lines in the rest of the config file. In fact, SVGAtextMode willact as if the label in the DefaultMode line was typed on the commandline as the required mode.

This option could be especially useful when experimenting with SVGAtextMode,and something goes wrong, causing the screen to become unreadable. Torestore a good mode, you'd then have to do some blind typing. TheDefaultMode would then allow you to restore a good text mode without havingto 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 different color than thedefault (color 0, black). You can select one of the 256 possible colors fromthe current palette.

If you set the border color to something different than black, a border willbe visible around the active screen area, about one character wide left andright, 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 videomode does not provide sufficient blanking on both sides, above and below thescreen.

UnderLine <Underline_position>

Underlining is disabled by default, unless you define an underline positionwith this option. The <Underline_position> must be a number in the range0..31, and it defines the relative position of the underlining.

The position given is always relative instead of absolute (as with thecursor 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 aslow as possible).

Using this, you could change the underline to a strike-through ("UnderLine15") or any other weird and totally useless underline position (what about aline above the text when it is underlined?).

The single real benefit of this option is if you want to use too small afont for the current VGA parameters: suppose you have a text mode defined inits mode line to have an 18-pixel high font, but you load a 16-high font init 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 youdefined "Underline 31", which is the most common one). In this particularcase, setting UnderLine to 28 would be much more nice to look at. This waythe underlining character is just below the character itself, and not at thebottom of the character cell (which would look as if the line was actuallyABOVE the next line of text).

As said above, not defining the underline position disables underlining. Anycharacters 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 allother cases, but will still show underlining in 8x32 and 9x32 fonts.

Also note that many VGA cards have a bug (?) that causes the underlining tobe non-continuous on 9-pixel wide fonts. So you have a fair chance that8-pixel wide modes have good (continuous) underlining, but 9-pixel modesnot.

Echo <Some_string>

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 theTextConfig file that is printed each time you run SVGATextMode.

It is used for example in the default TextConfig file to warn the new userthat he has installed SVGATextMode in its "standard VGA" mode, which doesn'tuse the full possible potential, and that he/she should edit the TextConfigfile 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 unsupported VGA chips, but withvery 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 andet4000w32p. 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 mustbe specified, or (and this is the preferred method) using a "clockchipET6000" 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) arethe 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, also90C31.
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 orCirrus chips. Newer V7/SPEA cards use S3.
ALI, AL2101: Avance Logic chipsets. It's not sure whether this will work on ALLAvance 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 notbenefit from this. They should work just as well with the generic VGAdriver.
GVGA: Genoa 6000 series cards. The 5000 and 7000 series are based on resp. ET3000and 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 enteredon an

: Option "option_string"

line. They change the default behaviour for each card or function programmedinto SVGATextMode. Currently the following options are allowed (for thespecified chip sets):

If you are configuring SVGATextMode for the first time, it is best to leaveall special options at their default (i.e. no special "option" lines). Ifsomething 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 itfrom the first time on. Most options behave the same way as they do in theXConfig (XF86Config) file.

hibit_high, hibit_low (ET4000 only)

This flag inverts the meaning of the 4th clock selection bit of an ET4000card. See the XFree86 documentation or the SVGATextMode distribution docdirectory for more information. It has the same meaning and function as theflag with the same name in the XF86Config file for XFree86. A simpleguideline (which doesn't always apply) is that ET4000W32 cards _all_ needthe hibit_high flag.

IMPORTANT NOTE:: The importance of this "hibit" stuff cannot be stressed enough. It might bethat your XFree86 X-server worked fine before you started usingSVGATextMode without this option in the XF86Config file (or Xconfig). Butunless you really specify it, using SVGATextMode in combination with one ofthe upper 8 pixel clocks from the "Clocks" line(s) will SURELY throw theX-server into a non-syncing display when you start it up! Specify thisoption in BOTH the XF86Config AND the TextConfig file, and you won't haveany trouble. You have been warned.

swap_hibit (WDC90C1X, WDC90C2X, WDC90C3X)

Some WDC cards need this flag. It inverts the meaning of the third clockselection 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 ET4000based cards that don't work with the normal clock selection method. Thesecards can only use their 8 lowest clocks under X-Windows (the X-server doesNOT support the alternate clock selection method used here).

Such a card can be recognized by the fact that no clocks over 80 MHz areavailable in XFree86 (the X-server uses a clock selection method that isonly 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 bythe DOS utility "dmode.exe" which is delivered with most ET4000 boards. NOTEthat XFree86 does NOT report the correct clocks!).

If you think you have such a board, you should really read thedoc/README.ET4000.AltClockSel file in the SVGATextMode distribution directoryfor 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 standardSVGATextMode ET4000 clock selection mechanism will be able to cope withthose.

Legend (ET4000, S3)

ET4000 or S3-based Sigma Legend boards need this option for correct clockselection.

XFAST_DRAM, FAST_DRAM, MED_DRAM, SLOW_DRAM (CIRRUS, TGUI and S3)

Most VGA cards can take higher pixel clocks (especially in text mode) whenyou increase the default DRAM speed. This may cause display memorycorruption if set too fast.

WARNING:: Some Cirrus cards crash your machine when DRAM speed is set too high. Itwill at least do all sorts of very funny stuff, like beeping forever. If youplan to tweak the DRAM speed, consider using the "syncDisks" optiondescribed below until you are sure the increased DRAM speed is no danger toyour machine.

Use this option to tune the speed to your card. The higher you can set theDRAM 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 hangon most 5422 cards... Use caution. Faster pixel clocks usually need fasterDRAM speed grades.

On S3 cards, this option doesn't actually set the DRAM speed, but aninternal parameter which controls the DRAM FIFO balancing (sic). The resultis the same: the faster you set this option, the higher you will be able toset the pixel clock without getting problems.

SPEA_Mercury (S3)

Only S3-based SPEA Mercury P64 cards could need this. They seem to use theclockchip differently than the other S3 clockchip-based cards: theyreprogram clock number 6 instead of the default, number 2.

LoadFont (all cards)

When enabled, this will tell SVGATextMode to load a new font from thespecified FontPath (or the default one) using the specified font loader (orthe default one). See the font loading section.

ClockDiv2 (all cards)

This option will enable a standard VGA feature that can divide the pixelclock by 2. Almost all VGA cards support this (except Cirrus Logic, forwhich it has been disabled).

It gives you access to a wider range of clocks, especially in the lowranges, since now all given clocks are also available divided by 2. It alsogives you more clocks in the "mid-range".

Enable it ONLY when you are sure SVGATextMode works for your card. Sincesome cards might not work with this option set, it is disabled by default inthe default TextConfig file! Some modes (like the 50x15 ones) will only beallowed when this option is enabled, because most card's lowest clock is 25MHz, and some of the 50x15 modes need a lower clock.

A final warning: The division by two option is unknown to most otherprograms, and could cause (additional) cooperation problems with thoseprograms. If you loose video when using SVGATextMode together with otherVGA-related programs, try disabling this option, and see if the problempersists.

SyncDisks (all cards)

When this option is enabled, SVGATextMode will sync all disks (= flush allcache buffers) before doing anything to the VGA hardware.

In all normal cases, this option is useless, but some cards seem to haveproblems with the way SVGATextMode talks to them, and cause a completesystem hang (hard reset needed).

This is especially probable (but still very rare) when overriding thedefault maximum DacSpeed, and severely overdriving the VGA card's text modecapabilities. As mentionned above, Cirrus Logic cards are dangerouscustomers when you start tweaking the DRAM speed.

So, just to be on the safe side, use this option when tweaking DRAM speed orRAMDAC speed, until you are confident that the system is stable enough.

In this case, the SyncDisks option can at least avoid data loss when thesystem hangs, although it cannot avoid the filesystem check that will resultfrom the reset.

The sync option is enabled by default in the configuration file. It willcause an extra 2 second delay when running SVGATextMode, because it waitsfor 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 usesa different system to access the VGA font memory (fast page mode), so theaccess to the fonts is faster. This allows for higher pixel clocks thancould be attained in normal text mode.

There is one restriction to this: the font must be stored in memory in adifferent format than would normally be used (i.e. the normal font loadingprograms won't be able to do this). The S3 designers provided a specialregister for that purpose. This register, when set, will automaticallychange 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 isexecuted from within SVGATextMode. This way, SVGATextMode can set thisspecial register before running the font loader, and reset it againafterwards.

Some older S3 cards will benefit greatly from this option. Especially S3911, 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 132x43from the BIOS (e.g. through LILO).

If this option is not enabled, SVGATextMode will always use normaltext mode, because it is the most compatible mode, and is less prone toproblems (e.g. doing a "setfont" in high speed mode causes a corruptedscreen, unless you first let the VGA chip know about it).

If it is enabled, high-speed font mode will be used for all modes withpixel clocks above 36 MHz.

NOTE:: Using the High Speed Font mode will cause text screen corruption onthe screen where the output from SVGATextMode would appear: Randomcharacters will appear all over the screen. This is caused by the S3 cardbeing 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 theSVGATextMode messages, but its characters will be written all over thescreen. After the font loader has finished, the normal memory access mode isrestored, and all characters are written to their normal places again. Thishas been partially solved by storing the output of the font loader in memoryuntil 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 internal font format,SVGATextMode will not allow you to switch between the two modes when fontloading is not enabled. In practice, it's wise to always enable font loadingwhen you also enable the high speed font mode. This way you will allow aneasy escape (=re-run SVGATextMode) when ill-behaved programs (or users...)load a font without first telling the S3 chip about it, as SVGATextModedoes.

clockchip_X (S3 + ICD2061a or ICS9161)

The ICD2061a and ICS9161 clockchips don't cooperate very well with theXFree86 X-server. When the X-server switches back to text mode (either dueto a VT-switch or completely stopping the server), it restores the wrongtextmode clock.

This is because both X and SVGATextMode use (i.e. reprogram) the same clockindex for their clock, and since the clock programming values cannot be readback from the chip, the X-server is unable to restore the correct clock whenit stops. This causes wrong refresh frequencies, or worse even, anon-syncing display.

The option "clockchip_X" will change SVGATextMode's behaviour so that ituses clock index #1 for the text mode clock instead of index #2. This willallow 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 issupposed to be 28 MHz, and nothing else. Any program that relies on that,will subsequently fail to set the correct video mode (svgalib, the XFree86clock probe and the DOS BIOS are just a few examples). Especially when youreboot to DOS, clock #1 does not get reset by the VGA card's BIOS because itassumes it's still at 28 MHz.

The solution here is to do an "SVGATextMode 80x25x9" just before rebootingthe 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 beforerebooting.

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 5signal 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 3wires instead. In that case, both sync signals are embedded onto the greenchannel. This requires a monitor that knows how to deal with this (in mostcases, those monitors can only deal with such signals. If you havesuch a setup, this option is for you.

Note: Although all Ti302X RAMDAC's support sync-on-green, not all VGA cardswill 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 colorsplus hardware blinking. This means you can produce blinking text on the console.

The "16color" option changes that behaviour: all "blinking" attributes gettranslated into "highlighting": instead of blinking text, you gethigh-intensity text, which effectively translates into 16 possible colors.

When this option is not specified, the standard 8-color + blinking mode isselected.

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 pixelis "made up" by the VGA chip depending on a few rules. Normally the 8thcolumn is copied to the 9th column for character codes in the range 0xC0 to0xDF. This looks very good on most VGA fonts, where characters in this rangeare line-graphic characters (aka box-characters). However, this makes someISO-compatible fonts look very ugly: ISO does not have line graphicscharacters but normal fonts in the region 0xC0 - 0xDF. This option disablesthe automatic pixel replication feature so that the 9th column will alwaysbe blank for all characters.

CLOCKCHIPS

This is a list of all allowed clock chips, per chipset. They are the same asin Xfree86-3.1.2. In addition, the ICS5301/5341 GenDAC used on someET4000W32(p) cards is also included.

S3

icd2061aics9161adcs2834 (Untested!)sc11412 (Untested!)s3gendacs3_sdacti3025 (Untested)ics2595ics5300ics5342ch8391 (Untested!)S3TrioS3Virgestg1703 (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 thesecards)

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

ti3026mystique

MODE CONFIGURATION LINES

This section describes the guts of the TextConfig file: the mode descriptionlines. It's long, and probably not long enough...

First of all: if you are not familiar with configuring the X-server, you'dbetter start off there, as it is MUCH more stable, MUCH less buggy, and MUCHbetter documented. You will also learn how to use several tools (vgaset,SuperProbe, ConfigXF86, ...) which can aid you to design your own customX-Windows mode. The same tools can then be used here.

For people less familiar with monitor timing stuff, and unwilling or unableto consult the XFree86 documentation, read the monitor-timings.howtoin the doc directory of the SVGATextMode distribution. It's a small (andincomplete) introduction on how monitors work, and what you need to send itto get some sort of a picture on it.

You will probably need the X-server (e.g. to do 'X -probeonly') to determineyour available pixel clocks, and maybe even to determine what chipset youhave. The distribution contains a script that can help you determine thepixel 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 themode you request. A TextConfig file can contain LOTS of configuration lines.It would be best that you leave the "default" config lines in the exampleTextConfig file as they are.

Add your own configuration lines at the end. If you patch a line, first copyit 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 ifyour custom line, with the same name as an "original" one is at the end, thecustomized line will be used.

That way you will always have the original lines as a reference, in case youscrew 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 beprepended 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 ascreen 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 modeline:

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 SVGATextMode! It's not because thelabel says "132x43" that you will get a 132x43 mode. You will get theresolution and size described in the parameters following the label. Ifthose parameters result in a 100x37 mode, that's what you will get. Justchanging the label from 100x37 to 132x43 will NOT do anything useful (exceptrenaming the mode): it will still result in a 100x37 mode.

Also, remember that when you change the font size, this also affects thenumber of text lines: if you were to change the font size in the 100x37 modeline described here from 8x16 to 8x32, you will get a 100x18 mode and NOT a100x37 mode with a larger font.

50.00

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 afloating point number.

Unless you have a freely programmable clock chip (using the ClockChipline, or with a Cirrus Logic card) on your VGA card, SVGATextMode willtry to find the closest available pixel clock in the Clocks line, allowing aslight deviation of a few MegaHertz: asking for a clock of 50 MHz, andhaving only a 49 MHz clock will make SVGATextMode use the 49 MHz clock. Thisshouldn't be a problem, because monitors always allow for a fairly largedeviation of their input frequencies.

800 872 976 1040

Horizontal timing parameters: resp. active video size (number of active orvisible pixels per video line), start and stop position of the Horizontalsync signal, and the full width of a video line, including active size andblanked (unused) size.

See the XFree documentation for a thorough understanding of these, or trythe monitor timing tuturial in the distribution. See also below in thesection on 9-pixel fonts for some explanation on the effect of selecting an9-pixel font on these timings!

Your textmode will have one eighth the number of characters per line as inthe 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 tocope with, if you want to use this particular mode) is easy: just dividethe 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 a9-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), sothere will be 600/16 = 37 textlines.

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 canhave. They define the sync polariries, the font size to use, and DoubleScanoperation.

-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 somenon-digital-control ones use the polarities to change their vertical screensize.

Cheap monitors have the habit of not having a constant vertical image size,independent of the vertical refresh frequency. So your monitor might use theentire 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 severalvertical refresh frequencies, and to adapt their vertical size. A MAGPMV1448 for example is a fixed 32/48 kHz dual-scan monitor. At 800x600AATT70Hz,the screen is either only half the vertical size, or the entire screen,depending on sync polarity. So some experimenting with polarities might giveyou a full screen, even with >70 Hz refresh rates. (The same applies to theXF86Config as well!)

More expensive monitors, mostly with "digital control", use the syncpolarities COMBINED with the incoming horizontal and vertical frequencies todetermine whether they will take their screen parameters (amongst which thevertical screen size) from a database of standard resolutions, or from the(scarce!) user-settable modes. If you succeed in using one of those defaultmodes, that saves you one more free user-settable mode. Taxan 875 monitorsfor example have only 4 programmable modes, and when you've just tweakedX-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 yourtextmodes (including the correct sync polarities), so your monitorrecognises them, without needing an extra entry in its screen parameterdatabase.

The sync polarities are an option. They are not required: if none aregiven, SVGATextMode will assign sync polarities according to the VGAstandards, depending on the number of active video lines:

  0..399 lines: +Hsync -Vsync400..479 lines: -Hsync +Vsync480..767 lines: -Hsync -Vsync768 and up:     +Hsync +Vsync

font 8x16

Font size: "font HxV" selects the horizontal size (character width = H) andvertical size (character heigth = V) of the textmode font. The possibleranges are:

H = 8 or 9V = 1 to 32

These are the hardware limits. Not all of them are as useful. Don't besurprised 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) determinethe number of characters 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, DoubleScanning will beenabled. This means each video line will be drawn TWICE instead of justonce. 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 a320x200 mode, it would look awful: a VGA monitor was designed to display atleast 350 lines, and at only 200 lines you would see a lot of empty spacebetween the lines. Most good monitors (especially 17 inch and up) even showthis 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 theVGA memory twice.

There is one "side effect" with this little trick: the vertical refreshfrequency drops to half the value you would think from the timings you enterin 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 Hzvertical refresh = 56423 / 256 = 220.4 Hz

Only, Doublescanning is enabled, so the VGA will actually output 256*2 = 512lines to the monitor instead of 256. So the actual vertical refresh is not220, but 110 Hz.

This might be pretty useless, but the Doublescan option together with themaximum font height of 32 lines results in an _actual_ maximum font heightof 64 lines...

Using 9-pixel wide font sizes

The VGA hardware is a strange thing. And using 9-pixel fonts is amongst thestranger ones.

The timing parameters are the same for both 8 and 9-pixel wide fonts, exceptfor the clock. Horizontal timings in VGA cards are _always_ specified in8-bit wide CHARACTERS, not in PIXELS, although the TextConfig file formatuses pixels.

Hence the restriction that horizontal timings should be a multiple of 8 (ifthey'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 resultin the SAME amount of characters per line, but the VGA chip will count 8pixels 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 displayrefresh frequencies (31.5 kHz, 70 Hz).

But in the first case, the total _actual_ pixel-count at the end of thevideo-line is (800/8)*8, and (800/8)*9 in the second case !!! To achieve thesame 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 onALL 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 orvice-versa: if you don't change the clock with the same 8/9 ratio, thedisplay refresh rates will change, and they might fall outside the allowablerange for the monitor (i.e. it will not synchronize to the new frequency, orSVGATextMode will suddenly not allow the mode anymore).

HShift <shift_amount>

This is an optional parameter that requests an additional shift of thedisplay to the left. The <shift_amount> can be any value between 0 and 3. Itshifts 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 tomove to the left side enough by changing the sync position. Take for examplethis 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 nicelycentered, there is not much you can do to fix this: the sync is alreadymoved the the extreme end, and making it shorter (by moving the secondnumber (376) closer to the third (400) will probably make your monitor goout of sync.

Enter the HShift parameter: with the same sync position, it moves the screen0, 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 ifthat 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 haveproblems with very-low-resolution modes (like the 40x15 one above). If youput 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 thatis too high.

In this case, putting the sync close to the end of the active video insteadof close to the other end solves that problem. You can then use the HShiftparameter to get the display nicely centered again.

The S3 BIOS uses this exact method for their standard VGA low-res textmodes.

BUGS

A configuration file has no bugs, of course. Any problems with it are eitheryour 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 kernelsets up VGA textmode memory, and can be doubled if required (see below). Youwould 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 thescroll-back buffer: since there are always (?) 16k chars on one screen, thescroll-back buffer will get the remainder of the 16k. If you have a screensize 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 perscreen. This requires recompiling both the kernel and SVGATextMode (and thelatter needs the same define in the Makefile).

Another limit is the maximum amount of clocks in all the clocks linestogether: 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 <koen.gadeyneAATTbarco.com>, with help from alot of local and remote Linux fans. See the CREDITSfile in the distribution for a full list of all helping hands.

The XFree86 configuration file (Xconfig, XF86Config) has been the mainguideline in creating the TextConfig format.