grabmode - a Textmode/XWindows mode grabber clockprobe - a Textmode/XWindows pixel clock probe
clockprobe [ -ndrhv ] [ -x <width> ] [ -y <height> ]
Grabmode basically does the same, but also grabs the entire state of the VGA controller, and shows it on the screen in a format compatible with the XF86Config file, the XFree86 X-server configuration file, or alternatively in the TextConfig file format, which is the config file format used by SVGATextMode.
Both programs are in fact the same, but depending on the name with which it is called, it does a clockprobe or a grabmode (clockprobe is a link to grabmode).
It does not change anything to the mode currently being probed. VGA registers are read only. This means it does NOT actually change pixel clocks like the X-server does when it probes for the clocks. This also implies that it should work on ANY VGA card, even if it is unsupported by either XFree86 or SVGATextMode. This is because it only uses standard VGA registers. No extended registers are used.
That also uncovers the biggest problem with grabmode: since it does not know about extended registers, it doesn't know about special chipset-dependent modes like 16/24/32-bit mode, or interlaced modes. See the BUGS section for more details. The mode grabber tries to be as clever as possible about interpreting the data retrieved from the VGA card, but it doesn't always get it right. Using grabmode requires some common sense from the user to interpret the data.
Of course, you could also grab the default Linux (and/or DOS) text modes to include them in your TextConfig file. So you can show your friends how the old modes looked, and how the SVGATextMode-"enhanced" modes look in contrast ;-)
Debugging XFree86 or SVGATextMode setups is another one. E.g. if SVGATextMode or XFree86 fails to show you the kind of screen you'd expect, and/or your monitor doesn't seem to like what you send it, then the most common reason for that is that the pixel clock is not programmed correctly, or not at all. Clockprobe or grabmode (even when typed blindly, redirected to a file for later viewing) should be able to tell you what clock you are ACTUALLY using. It's not because your "clocks" line says "50 MHz" for some clock, that that clock index actually IS 50 MHz. You could be using the wrong clocks line, or there could be a bug in the clock setting code. In either case, the clockprobe can tell you the ACTUAL clock.
Specifying the width and/or height for the mode grabber or the clock probe will bypass all the guessing (see "bugs" and "smart bombs" section) it would normally have to do in order to detect special modes (15/16/24 BPP, interlace, ...). This will result in a much more reliable mode line and/or clock frequency report.
This option is for the clockprobe only:
These options are for grabmode only:
Since graphical screens have nothing to do with hardware assisted font rendering (as from VGA text mode - let's forget about accelerators for a while), they set the "character height" to 1 pixel (in fact they have to, otherwise each line gets repeated 16 times, if they leave the "16" from the 9x16 character mode in there!). So font size given will of course be wrong. In most cases you will be presented with am 8x1 font (8x2 in some DoubleScan modes), and with a mode label equally distorted. grabbing a graphical 1024x768 mode this way would result in a mode line labelled "128x768" with a font size of 8x1. You'll have to change the font size (and the label) if you want to turn that into a useful text mode.
This could be used to create a text mode completely compatible with an X-Windows mode you already have. switching from one to the other would be much faster, since the monitor wouldn't have to re-synchronize.
clockprobe: Estimated vertical scanrate = 69.754 Hz. clockprobe: Estimated horizontal scanrate = 55.803 kHz. clockprobe: Estimated pixel clock = 74.83 MHz
Note that the clockprobe (both in clockprobe and grabmode) only measures the vertical refresh rate. The rest is calculated from the VGA register contents and the vertical refresh. Extended and special modes which could cause grabmode to mis-detect a mode, will also cause the horizontal frequency and/or the pixel clock to be wrong.
(the output comes on one line)
To remain chipset-independent, grabmode and clockprobe try to guess from what they can read in the standard VGA registers what mode you could actually be using.
A program can only be as intelligent as its creator (except by mistake). Well, grabmode is extremely stupid on some occasions. Because of that, it will report all non-trivial changes that it made to the original timings (as read from the VGA) before printing it out, and also WHY it did that.
That's why this section is called "smart bombs": When one of those gets confused...
The built-in smart (hah!) features are:
Doublescan displays each line twice, so there are actually 400 lines on screen, but only 200 different ones. In this mode, the VGA is programmed for 400 lines, but with Doublescan enabled, the ACTUAL line count is half that. Grabmode will thus divide all vertical timings by 2 before displaying them.
Although standard VGA has a "vertical double" mode bit, which multiplies all vertical values by 2, most SVGA drivers prefer to use extended (chipset dependent) registers to accomplish that. Grabmode cannot read these extended registers (we want to keep it chipset-independent, remember?), so it will show wrapped-around timings for those modes with around 1024 lines.
example:
"1280x1024" 110.34 1280 1328 1512 1712 1024 1025 1028 1054
"1280x1024" 3.131 1280 1328 1512 1712 1024 1 4 30
Grabmode will see that the sequence of vertical timings is wrong, and will assume that this was an extended mode, using extended registers. It will correct the sequence to make it look like the correct one.
This feature only works when the vertical timings happen to cross over the 10-bit standard VGA limit, which means it will only work for 1280x1024 modes. Far from perfect, but better than not at all...
640x480 modes have an aspect ratio of 640/480 = 1.333 (=4/3). 800x600, 1024x768, 1280x1024, 1600x1200: all those modes use an aspect ratio of 4/3 (or a close match) (anyone have a 16/9 computer display -- they exist) ?
If grabmode detects a mode that looks like double or triple that ratio, it assumes this is a special mode (see below), and divides the horizontal timings by 2 or 3. In most common cases, this is the correct result. An appropriate warning is given.
The golden ratio assumption is then used by the CGA emulation detector, the Hi-TrueColor mode detector and the interlace detector to adjust the mode timings.
Grabmode (and clockprobe) report the _actual_ pixel clock used at which data is being transferred from the VGA chip to the RAMDAC. This means that any special data transfer scheme will mislead the clock probe, causing a faulty report.
This ramdac programming is very RAMDAC-dependent, so it is impossible to detect what is going on without knowing the RAMDAC type. RAMDAC's with 16-bit interfaces (like the S3 SDAC) use this scheme for 24/32-bit modes: they transfer one 24-bit pixel in 2 clock periods, or, worse even, for 24-bit packed pixel modes, in 3/2 clock periods...
To make things even worse, grabmode will not even correctly report simple 256-color (8-bit) modes on some cards. Especially high-end cards (like #9, Diamond, ...) using special VGA DAC's (Bt485,...) with pixel multiplexing. They will report completely wrong clocks and refresh frequencies things on higher (>67.5 MHz, for example) pixel clocks. Such RAMDAC's can transfer 2 or more entire pixels in one clock period, the opposite of simple RAMDAC's in 16/24/32-bit modes.
In order to do this, they program the VGA chip with HALF the amount of actual lines on the screen, and set a special bit that tells the chip this is an interlaced mode.
This "interlace-bit" is, again, in the extended (non-standard) VGA registers, and can thus not be detected by the mode grabber. What _can_ be detected is that the amount of lines programmed in the VGA registers is only half of the height of the screen. This would be easy if there was a way to know how much lines the screen actually has...
But since there isn't, grabmode must resort to some assumptions: assuming that most graphics modes use one the standard screen sizes below:
640x480 800x600 1024x768 1152x900 1152x910 1280x1024 1600x1200
the mode grabber can then check if the current mode has exactly HALF the amount of lines of one of these modes: 240, 300, ..., 600 lines. If so, it ASSUMES (!) that this is an interlaced mode, and changes the timings accoringly before displaying them.
This immediately shows that the mode grabber will not be able to detect non-standard interlaced modes.
This pixel joining scheme is enabled by a certain bit in the VGA registers, which is detected by grabmode to trigger it to transform the mode into a "CGA" emulated mode. Easy.
BUT. Extended VGA modes use extended VGA registers, and those have priority over the standard VGA registers. Hence, even if this special CGA-emulation bit is set ON, it doesn't necessarily mean pixels are being combined.
All in all, even if this special mode is set in the standard VGA registers, the extended registers could override that. Detecting this mode is thus not trivial. This is why the "golden ratio" detection is used for this: after doublescan has been accounted for, the mode timings come out as 640x200, which triggers the golden ratio detector to transform this into 320x200, with an appropriate warning.
When there is no vertical retrace detected within a few seconds, the probe assumes it will never get one, and bail out with a message to that extent. This avoids that the probe hangs forever.
There's one caveat to this. Previous versions of the DOS grabmode were compiled using a commercial DOS C compiler, and required a lot of special code. The latest version was compiled using DJGPP version 2.0, the GNU C compiler for DOS. This required almost no special code, and thus it is a cleaner port. BUT... It needs DPMI (DOS Proteced Mode Interface). A DMPI environment can be found in MS-Windows (DOS boxes), OS/2, Windows-NT, qdpmi, 386max, etc. A free DMPI program is included in the distribution (The DJGPP DPMI program CWSDPMI).
Scanmode.exe scans all VGA modes from the DOS BIOS, including the VESA modes, and outputs two files in the currect directory: tconfig and xconfig. The text modes are stored in the tconfig file, and the graphics modes are stored in xconfig.
However, even busy machines should give a reasonable result, unlike the X clock probe. Even heavily loaded (swapping!) machines should give a rather close estimate (maybe a few MHz off, but that should be all). System loads to up to 3 or 4 will probably still yield results which are only a few MHz wrong.
The clockprobe first performs 100 measurements of the time between two vertical retraces, then calculates a histogram of those measurements. If the histogram does not have a nice peak (mostly due to heavy system load, causing many measurements to be wrong), the measurement is done all over again. After three failures, the clock probe will stop retrying, using the last measurement, but also warning you about the unreliability of the result.
In most cases, the clock probe will measure a value slightly higher or slightly lower than you expected. It might be for example that you programmed a mode line that specified a 70.000 MHz pixel clock, but the clock probe insists that it is 75.175 MHz. This is due to the fact that any clock generator cannot produce just _any_ clock you ask for, but must pick the closest available one, either from a list (the `Clocks' line in SVGATextMode or XFree86), or from the possible settings on a programmable clock chip.
If the clockprobe insists on the same value over and over, it means that that is the actual clock. If it insists on something far from the one you expected, then it's either a bug in the probe, or a misconception on your side.
Some special modes like CGA emulation, HiCilor, TrueColor, pixel multiplexing, ..., will cause grabmode to fail to detect the correct number of pixels per line. And because the horizontal sync and clock speed are all calculated from the H and V timings, they too are wrong. The vertical sync speed is ALWAYS correct, since it is MEASURED, independantly from ANY timing register.
When executed in an MSWindows DOS box, you will ALWAYS probe the VGA parameters from the full-screen DOS version, even when you are running the DOS box in a window and not full-screen. This is because MSWindows hides its VGA registers from normal programs (probably through the MMU address mapping), so the mode grabber gets fooled into believing this is still a text mode box.
For the same reason, doing a grabmode in a DOS window will even lie about the font size. Windows will give you an "appropriate" font size, which doesn't have to be the real one.
A Full-screen DOS box WILL give a correct probe, although there could be a warning about serious system-load and the resulting timing-inaccuracy.
Clock probing is a DOS window is a hoax. You will get extremely high clock rates, or even floating point overflows. Use the "-c" option (don't probe clock rate) to avoid this.
Conclusion: Probing a DOS window is TOTALLY USELESS. You get the wrong VGA register contents (those from the text mode, not those from the Windows mode), and the wrong pixel clock.
Most bugs not yet mentionned above result from the various assumptions the mode grabber has to make along the way, which in turn is caused by the wealth of different methods VGA chip makers come up with to make special mode programming non-standard.
As mentionned above, the following special modes could cause grabmode and/or clockprobe to get it all wrong:
Interlaced modes Hicolor modes TrueColor modes Pixel multiplexed modes Extended VGA modes ( > 1280x1024)
The reasons for this are explained in one of the sections above.
If you don't trust the result, use the "-r" (raw probing), and add some common sense. Then determine what the real mode parameters should be. In most cases, you know what the actual mode is (e.g. 1024x768), so you can use that knowledge to interpret the raw timing report.
Some IBM 8514 compatible cards (like ATI Mach) use a completely different set of registers than the normal VGA set when they are in graphics mode. Because of the chipset-independance of grabmode, grabmode will not notice this, and report the values which are in the now unused VGA register set. In most cases, this is the text mode from which the graphics program (XFree86, for example) was started.
The main reason for all these problems are the author's stubbornness (combined with a fair amount of lazyness) to keep grabmode chipset-independent.
See the CREDITS file in the distribution for a full list of all those who helped.
SVGATextMode(8) - Textmode manipulation/enhancement tool TextConfig(5) - Configuration file for SVGATextMode XF86Config(5) - Configuration file for XFree86
The `doc' directory in the SVGATextMode distribution contains a lot of
miscellaneous documentation on a range of topics related to configuring and
using SVGATextMode. The monitor timing tuturial in the SVGATextMode
distribution could be a handy reference for understanding mode timings.