It works independently of what text modes are allowed from the BIOS. In theory, any text mode size is possible, as long as your VGA card is up to the job. Whether it is or not, depends greatly on the chipset.
SVGATextMode can resize the console screen on the fly, without rebooting, to any other size. The configuration file holds all the parameters needed for the new mode.
It needs kernel version 1.1.54 or newer if screen resizing is to be possible.
It is important to start from a standard VGA text mode (80x25...80x50) when using this "chipset" for unsupported chips. Otherwise the clock will not be programmed correctly.
SVGATextMode needs a configuration file with a similar syntax as Xconfig or XF86Config, the configuration file for XFree86, the X-Windows server. The default config file is /etc/TextConfig.
See the TextConfig(5) manual file for details on its syntax.
When running SVGATextMode with a new textmode, it will output a single line, describing what the new mode is, and what are the screen refresh rates.
A second "d" option will enable extended debugging, showing you all the data that was parsed from the config file, instead of just the most important things. More specifically, this will add all the mode lines and the font selection list to the debug output.
When a ResetProg is defined (and thus enabled) from the config file, SVGATextMode, without "-r", will attempt to run it whenever it has changed the screen size.
The reset program is normally used to signal or restart a program that depends on the current screen size, and that doesn't react to the SIGWINCH signal the kernel sends it upon a screen resize. Typical examples are gpm and selection; two very handy textmode-mouse handlers.
Resizing the screen from 80x25 to e.g. 116x48 without telling gpm or selection about it, will cause the mouse cursor to get stuck in the upper left 80x25 characters of the screen.
The "-r" option is useful when SVGATextMode is started from the system initialisation files (/etc/rc.d/...), because many of the programs that need to be reset through the ResetProg have not yet been started, so trying to send them signals, or trying to kill them, would fail. And trying to restart them would cause two copies of the same program running when the rest of the rc-files start them up.
This is particularly useful to create input to a script or program that lets you (for example) select a text mode from a menu.
WARNING: see the BUGS section for more information on the potential dangers of this method. Do not use this option unless it is absolutely necessary.
Under certain circumstances (see the BUGS section), it is desirable to resize the screen, even if the tty settings say the screen already has that size. This option will force the resizing code to "fake" a resize, and run all necessary code (set the tty settings again, tell the kernel about the resizing, and run the optional ResetProg).
As a side effect, none of the programs running on the console will be sent a SIGWINCH from the kernel, so they too will not know about the change. The ResetProg is still ran (unless when prohibited by the "-r" option of course), so it could be used to send explicit resize messages to console applications that otherwise relied on the kernel SIGWINCH signal.
There's only one problem with this. Most of these types of crashes leave the keyboard in raw (scan-code) mode, and thus you won't be able to type the command to restore text mode... You will have to do a "kbd_mode -a" from a remote terminal first. Unless you add "kbd_mode -a" to the file defined in the "ResetProg" label in the TextConfig file, and have "stm -o" under a mouse button combination with the GPM mouse package.
Another fun-stopper is the extended VGA registers, which this option does _not_ reset, because they are chipset-dependent. This means that the "-o" option might not help at all, depending on how sophisticated your card is. SVGATextMode knows about a few cards and how to kick them back into "normal" mode, but not all (due to lack of documentation and cards to test -- hint, hint).
Now suppose you have a mode description line in the config file that looks like this:
(the entire config line must be on a single line)
After correctly configuring the /etc/TextConfig file for your VGA card, typing
will produce an output similar to the following:
Loading 8x16 font from file /usr/share/consolefonts/Cyr_a8x16
Note the refresh timings at the end of the first output line: this mode would require an SVGA monitor capable of 56 kHz at 70 Hz (the same frequencies as a VESA 1024x768 @ 70 HZ mode).
The second output line actually comes from setfont, a program which SVGATextMode can be made to call automatically after resizing the screen, so the font is adjusted to the available space in the character cell.
Having SVGATextMode installed with the SETUID bits ON makes it run as root, even when a non-root user runs it. This is a potential security problem, since SVGATextMode can be made to execute external programs (font loader and ResetProg).
The default distribution will NOT renounce superuser rights EVER, so it'll run any external program as root also (if the setuid bits on SVGATextMode are on, of course). If you are administering a critical system, don't set the SETUID bits on SVGATextMode (which will have the side effect that non-root users cannot use SVGATextMode), or if you do, make sure that all externally called programs are secure.
If you want to have the SUID bits on, but don't trust the external program's security, then recompiling SVGATextMode with the compile-time option "RUN_SECURE" enabled will make SVGATextMode renounce superuser rights immediately after requesting rights to write to the VGA registers. Any program run thereafter will be run with the user ID of the one executing SVGATextMode.
If the programs called by SVGATextMode are not setuid root, they might fail, because they want to change things only root is allowed to tamper with.
The stm.exe program will do the same, and require the same as SVGATextMode does under Linux, with the following exceptions:
The downside of this is that it can only go from one text mode to another. In most cases, SVGATextMode cannot switch to text mode from a non-text screen (e.g. from graphics mode, or from a messed-up screen when some graphical application exits ungracefully).
X * Y * 2 * 64
bytes of memory, where X is the number of characters per line, and Y the number of text lines on the screen.
When the kernel fails to resize the screen because of a lack of the right kind of memory, SVGATextMode tries to free some more by temporarily requesting a large block of memory and freeing it immediately again, forcing some disk buffers to be flushed to disk, and forcing some programs to be swapped out.
If the resizing still fails, it tries to free twice that much memory, and if that fails, three times the amount. If you attempt to resize to a really big screen, this is resp. 2, 4 and 6 MB of memory that will be "freed" before trying to resize the screen. If all that fails, then SVGATextMode will finally give up, and announce this in a large, friendly error message.
The -m option is a way around this, but it has its own problems. When it temporarily switches to a 1x1 screen in order to free some more memory, some other process might snatch memory away from under it before SVGATextMode can switch back to the new mode, causing the final resize to the new size to fail. This is very unlikely to happen, but when it does, you are left with a 1x1 screen, which is rather small. When that happens, blindly stopping some jobs, and blindly resizing to a 80x25 mode (either through SVGATextMode or set80) is the only solution.
A much better option to avoid out-of-memory problems is to tell the kernel it needs to keep more memory free, by swapping a little sooner. This can be done only in Linux kernels from somewhere around the 1.3.60's and up, using /prov/sys/vm/freepages. The default contents of this configuration "file" are:
32 48 64
These numbers represent the amount of free pages (one page is 4096 bytes on an Intel platform) below which the kernel will begin to swap pages out or reduce buffer sizes aggressively, moderately and lightly, resp. All this means that in the default case, an unloaded machine will saturate towards 64 free pages (256k) free memory. Changing these settings to higher values, e.g.
cat 128 256 1024 >/proc/sys/vm/freepages
will cause an unloaded machine to have 4M free memory after a while. This will reduce the risk of running out of memory for SVGATextMode resizing significantly.
While experimenting with mode timings, at some point you could end up with a mode that the VGA card cannot handle, and it just stops outputting anything at all: no video, no sync, nothing.
SVGATextMode does its work in the vertical blanking interval, waiting for a vertical sync signal before starting to change VGA registers. But when there is no sync, it would wait forever. A timeout of one second prevents that, but shows up as a relatively long delay before the new mode becomes active.
In addition to that, the default TextConfig file has the "SyncDisks" option active, which makes SVGATextMode execute a "sync" instruction to flush all remaining data in the disk cache to disk. Since there is no way to know when that has finished, SVGATextMode just waits a good while (a few seconds), hoping that all data is flushed by the time it starts.
But that message will not be of much use, since leaving those VGA registers halfway programmed will most probably result in no video at all. So the message is there, telling you in all detail what went wrong, but you will not be able to see it...
The author has been made aware of this problem on various occasions, and future versions will not be as unforgiving.
In the mean time, make sure nothing will go lost when you first experiment with SVGATextMode and you have to reboot to get back into a visible text mode. Preferably use `savetextmode' from svgalib to enable a future `textmode' restore command when something goes wrong. Also consider redirecting standard error to a file when you expect trouble. You can then inspect the result when (or "if" ;-) you get back your screen.
There are some nasty interactions with other programs that do VGA programming. Amongst them are: the XFree86 XWindows server, svgalib, dosemu and probably others. The most common effect is a distorted screen when such a program switches back to text mode. The real reason for this mostly lies with that program, because it doesn't restore all VGA chip registers as they were before that program started. They were all written a long time before SVGATextMode saw the light of day, so how could they know?
SVGATextMode cannot really solve this problem, since it exits after setting the new mode, and so it doesn't stay active to restore the mode whenever another one screws it up.
For a more in-depth discussion of these kinds of problems, read the doc/FAQ file in the SVGATextMode distribution.
X has restored the VGA register contents of when it started, which are not the same that you programmed with SVGATextMode. But the kernel still thinks you are in the new mode, since X didn't tell it about the restoration to the old values, and thus the kernel draws its characters in the wrong place in the video memory.
Result: screen completely garbled. Solution: re-running SVGATextMode whenever you switch back from X to text mode, or exit X, and restart it after re-programming the new text mode.
The former case will need the -a option to tell SVGATextMode to force a full resize. When X restores the VGA register contents, it doesn't restore the tty settings, nor the kernel screen size parameters. Thus SVGATextMode is made to believe that the screen is not resized, and thus doesn't do all the resizing code, leaving the kernel parameters and tty settings as they were: wrong.
A general rule of thumb to avoid interaction-problems with the X-server is to specify as much as possible, thus allowing the server as little guesswork as possible. This is recommended by the XFree86 manuals also, even without SVGATextMode. In practice this means you let the server guess for all hardware parameters just once, i.e. when you first install it on a new VGA card, and preferably from a non-tweaked textmode (no SVGATextMode). You then copy as much parameters from the probe to the XF86Config file as possible. The reason for this is that some probing routines in the XFree86 server work well only under a standard text mode (e.g. the S3 IBM RGB RAMDAC RefClk probe).
They _assume_ you start from a 80x25 screen, and will always return to a 80x25 screen when doing a VT-switch or when exiting the server. Since they don't tell the linux kernel what they've just done, the linux kernel, still thinking it's in some weirdo text mode, will draw its characters all over the place, except in the right one... A partial solution is to change the `startx' script to make it re-run SVGATextMode after the server exits. But this doesn't solve the VT-switching problem.
DOSEMU might not be clever enough to reset all your card's VGA registers (including the clock setting registers) when it starts up in VGA-mode. In that case, any non-standard SVGATextMode mode could produce a non-syncing DOS display. The only cure in this case is to reset to a standard VGA text mode like 80x25 before starting DOSEMU.
A similar problem might pop up when exiting DOSEMU. If it doesn't restore all linux textmode registers, the linux console might get corrupted.
Both problems can be resolved by embedding the DOSEMU call in a script, which does something like this:
SVGATextMode 80x25x9 dos SVGATextMode My_SuperMode
This will not solve the problem when switching to another virtual terminal while DOSEMU is still running.
The reason for this is that some card's BIOSses don't care to reset all clocks to their defaults when they get a reset signal (i.e. when rebooting). Some die-hard cards won't even do that when you hit the cold-reset switch, and will only revert to the default clock values when you power-cycle the machine.
A simple solution to this is to put an SVGATextMode (or ClockProg) command in the system shutdown script. This is in most cases
If the programmed clock is the correct default clock value, your DOS problems will be solved. The only tricky part here is to find out what that default clock is...
Since SVGATextMode reprograms clock #2 (the third clock) on most clock chips, the default clock value depends on the clockchip type you're using.
Only clocks #0 and #1 are the same for (almost) all VGA chips, and thus this method is only really simple for those clock chips where clock #0 (default = 25.175 MHz) or #1 (28.3 MHz) is reprogrammed. This is currently only for the icd2061a (or the equivalent ics9161) clock chips when the "clockchip_x" option is used.
Much of the VGA code for SVGATextMode was borrowed (I will give it back :-) from the XFree86 3.1 server code (and also from newer versions). The S3 clock chip code and Cirrus Logic clock code was copied (with some improvements added) from the original XFree86 code.
See the CREDITS file in the distribution for a full list of all helping hands.
grabmode(8) - A XFree86/SVGATextMode VGA mode grabber
SVGATextMode-x.y/doc/FAQ - description of problems you could encounter when using SVGATextMode, and some solutions.
The 'doc' directory in the SVGATextMode distribution contains a lot of miscellaneous documentation on a range of topics related to configuring and using SVGATextMode.