This file describes some possible problems that you could encounter when
using SVGATextMode, and, if any, the suggested solution(s). It also
describes what you should do when you want to report a problem to the
author. 

It is rather new, and thus very incomplete. Let's hope it will improve in
the future.


General advice when something goes wrong... or even BEFORE it goes wrong
                        READ THIS FIRST!!!! 
------------------------------------------------------------------------

Before throwing either SVGATextMode or your computer out the window,
consider doing some tests to see what goes wrong.

When first trying out SVGATextMode, you might run into a bunch of problems.

Some general guidelines for configuring SVGATextMode correctly:

 - Make ABSOLUTELY sure the chipset selection is correct. Unlike the XFREE
   X-server program SVGATextMode does NOT check if you actually HAVE the
   chipset you defined in the config file!
   
 - Do NOT enable the Clocks lines in the TextConfig file just like that.
   They are true only for a CERTAIN card using that chipset. You should
   enter the CORRECT clocks, as derived from the X-server with
   
         "X -probeonly"
         
   If you enter the wrong clocks line, all modes above 80x25 will NOT work
   as expected. You've been warned. 
   
 - If you've already configured X-Windows on your system, take a look into
   the XF86Config file. It contains a lot of stuff that can be copied right
   into the TextConfig file!
   
 - To avoid a lot of non-functionning modes, fill in the correct monitor
   limits in the HorizSync and VertRefresh variables. Especially if you have
   a smaller/cheaper/older monitor.
   
   
And if all these points have been adequately taken care off, the time has
come to do some more extensive tests. 

You need to know WHAT exactly is going wrong. Don't send me a mail like
this (this is REAL. Someone really sent me this!) :
 
     Hi,
     
     I've just downloaded the latest version of SVGATextMode, and it doesn't
     work. What should I do? What am I doing wrong?
     
     Any help would be greatly appreciated
     
     Mr X.      (you didn't think I would print his name here, would you?)
     
I'm sorry, but my response (if any!) to that will be a rather angry one.

For heaven's sake, how do you think I can help you if you tell me NOTHING.
The example above is really the worst one I ever received, but some come
close.

My first advice is: READ THE DOCUMENTATION! I am really trying to put as
much usefull information in it as possible, so read it. I never read a lot
of docs myself when I try something new, but if it doesn't work, reading
docs is the thing to do!

And secondly: either be prepared to do some solid tests, or throw it away
right now. 

The best test to do, is to select a text mode that doesn't work, and then
grab it using "grabmode". If you need to do this blindly ('cause the stupid
piece of &^%#@* makes the screen go nuts), redirect the output to a file,
restore the text mode to a readable one (either through SVGATextMode or a
reboot), and COMPARE THE OUTPUT OF GRABMODE WITH WHAT YOU SELECTED FROM THE
CONFIG FILE.

See what's different. In fact, there should be NO BIG DIFFERENCES. If there
are, then you've probably found the cause of your trouble. As in any kind of
problem, locating the cause if half of the solution!

The font size and sync polarities reported by grabmode should be EXACTLY the
same as the selected text mode from the config file.

The vertical video timings (second group of 4 numbers) should be EXACTLY the
same, except for the first one, which was rounded to the nearest multiple of
the font height when programmed into the VGA chip.

The horizontal timings should be close: a maximum difference of 7 is
allowable (these numbers are rounded down to a multiple of 8 before sending
them to the VGA chip).

And the pixel clock should at least be close. There are two reasons for a
difference: first of all, when looking for a suitable clock in the clocks
line, SVGATextMode picks the CLOSEST clock, allowing for a 3 MHz difference.
And the second cause is the clock probe, which could, under very bad
conditions, add another  MHz or so to the error. So if the probed clock is
off by 4 or more MHz, then the clock selection code selected the wrong
clock.

This can have several causes:

  - a bug (but there are none... :-(
  
  - an incorrect clocks line: if it tells SVGATextMode that clock index 7 is
    a 50 MHz clock, and it is IN FACT 80 MHz, don't be surprized if it
    doesn't work. SVGATextMode sopposes the clocks line is reality, and will
    select the clock at index 7 when you select a nmode at 50 MHz.
    with the appropriate testing, you should be able to determine what
    entries in the clocks line are wrong, or what they should be. You could
    even make your own clock probing script by selecting each possible clock
    index, and doing clockprobe on each mode with that clock. That way you could
    eventually create a correct clocks line from it. It's rather cumbersome,
    but it might help. Until I add a real clock probe (as in X).

  - If you use an external clock program. through the "clockprog" line, it
    could be the wrong one (=designed for ANOTHER card, with probably
    ANOTHER clock chip one it), or the clock program doesn't interpret the
    arguments given to it correctly, or a million other reasons. Check the
    program WITHOUT SVGATextMode: use the clock probe to see what clock
    you're currently using, and then manually select the SAME clock with
    that external clock program. Nothing should change, since you replace the
    current clock with the same one. As long as this doesn't work, don't
    bother trying it in SVGATextMode.
      e.g.:
          command: ./clockprobe
          result: ./clockprobe: Estimated vertical scanrate = 70.07 Hz.
                  ./clockprobe: Estimated horizontal scanrate = 31.547 kHz.
                  ./clockprobe: Estimated pixel clock = 28.387 MHz.
                  
      so the clock is 28.3 MHz. try:
          <your_cloc_program> 28.3      (if it takes MHz as arguments).
          
      if nothing changes, it COULD work. Now try this from your other text
      modes also (especially the 132x... modes, since they use another
      clock: 40 or 45 MHz)
  
  - If you use a clockchip line, make sure it is the correct one (it should
    be the same one you use in X). If you're in doubt, try some of them, but
    prepare for some reboots!
    
  - The clock selection mechanism of your VGA chip simply isn't supported. 
    If the docs of SVGATextMode say it SHOULD be supported, try reading some
    more docs, they might give you some ideas.
    
  - If you're using an ET4000, watch that hibit_... option ! (it's in the
    docs).
    
  - ?
      

Example: 

  TextConfig mode:
  "B132x48" 75 1056 1088 1240 1336 768 775 776 800 +hsync +vsync font 8x16
                           
  grabmode report: 
  "132x48" 75.165  1056 1088 1240 1336  768 775 776 800  +Hsync +Vsync font 8x16
               >>   # 56.261kHz/70.33Hz
               
When you see this, you know the card is configured properly. All numbers are
roughly the same.

If your monitor doesn't show an image, maybe it cannot cope with the scan
rates this mode uses: SVGATextMode tells you those when loading the mode,
and grabmode adds them as a comment at the end of the mode line. If you have
no idea what I'm talking about: READ THE "monitor-timings.howto" FILE! 

If grabmode would e.g. report a 25 or 28 MHz clock in the example above (or
40/45 MHz when started from a 132x... mode), SVGATextMode probably didn't
change the clock at all. See above for some possibe causes. If any other
number comes out, 


When all this doesn't help you, you could try looking INSIDE SVGATextMode,
to see what it does to select your text mode. That's why the "-d" option was
added: it shows all steps and their results as SVGATextMode goes through the
process of parsing the TextConfig file, and finally selecting your mode. It
wasn't made to be easy-reading prose, but rather to contain as much as
possible information on the internals of SVGATextMode. Try patiently
browsing through the output, and maybe you'll find the reason for your
problems.

And if, after trying all this an more of your own ideas, you are still stuck
with a problem, THEN you can try asking the author. But make sure to add all
relevant information:

   - version of SVGATextMode used.
   - the part of the TextConfig file you enabled for your card (clocks,
     clockprog, clockchip, options, ...). Don't send the entire TextConfig,
     I know what it looks like ;-)
   - If you have tried configuring X before, add the relevant part of your
     Xconfig (or XF86Config for XFREE 3.x), and comment on the behaviour of
     X: what worked, and what didn't. 
   - your Linux kernel version number.
   - the type of VGA card!!!! (some forget this, can you imagine?)
     brand, chipset, memory, bus, ... any related or non-related problems
     you had with it, ...
     Mention your VGA card type in EVERY mail to me. This saves me a lot of
     mail-backtracking to find out what you're talking about!
   - which text modes worked, and which didn't. Also add the results from
     grabmode on each mode you mention (especially if that mode doesn't
     work).
   - If you suspect that SVGATextMode doesn't interpret the TextConfig
     correctly, prove it with the output from "SVGATextMode -d" (or part of
     it; don't send the output of SVGATextMode -d for EVERY text mode in the
     Config file. Just show your point with maybe a few modes).
   - any other information you consider relevant (like your sister's age ;-).
     
I know not everyone can understand the black magic of video cards, monitor
timings, and kisses that turn frogs into princes, but reading some
documentation, and using common sense can help a lot.

  

Various strange interactions with SVGALIB
-----------------------------------------

Yes, this is a major problem. Depending on the type of card you have,
Svgalib can do sereral things wrong. In most cases, svgalib is the real
culprit (because SVGATextMode does SO VERY LITTLE compared to SVGAlib).

The most common problemn is SVGAlib starting up with the wrong pixel clock
programmed. The result is a non-syncing monitor, or the display divided into
4 parts with each part showing the same original screen, or a very flickery
screen, or anything else a monitor can come up with...

If you suspect this is the case, you can check the clock used by that SVGAlib
mode using the clockprobe. When the screen does not sync, you can do that
from a remote terminal, or if you don't have one, start it with a delay:

    (sleep 5 ; ./clockprobe > probe.out) &

and then quickly start your SVGAlib application. After you get back to a
readable text mode, check the probe.out file to see what happened. 

I am of course unable to do much testing on this, since I don't own any
VGA card with those problems (just luck, I guess).

But the only real possibility would be that SVGAlib doesn't reprogram ALL
necessary registers to get to that specific graphics mode, and leaves some
of them untouched. The most obvious ones are the clock programming
registers/bits. And in that case, SVGAlib needs to be adapted to reprogram
ALL clock selection bits.

Since SVGATextMode uses approximately the same clock selection method as the
XFREE server (and will come closer and closer to it in the future), it is
likely that you encounter the same problem when using SVGAlib together with
X (e.g. switching from SVGAlib to X and vice versa).

Wouldn't the future be much brighter if SVGAlib, XFREE and SVGATextMode used
the SAME VGA programming library, so they cooperate instead of fight?

At least ET4000's and Trident cards have been known to show this problem.


ET4000:
-------

[ the following little theory MIGHT be wrong, but I didn't want to spend too
  much time browsing through the SVGAlib source code. I'm a little lazy :-(
  Many SVGATextMode users reported a similar phenomenon, and provided enough
  feedback to justify this. It seems to be mainly an ET4000 problem ]


SVGAlib has two different sets of modes: the standard VGA modes, and the chipset
specific ones. The most common standard mode is 320x200x256. Others,
commonly known as "VGA tweaked modes" are also available.

The standard modes use the standard clock selection machanism used in all
VGA cards: programming the clock to 25 or 28 MHz. ANd they DON'T program any
chipset-specific clock registers.

In order to use the ET4000 with SVGAlib, the authors included a program to
run from DOS, that gets you all the necessary data to complete the svgalib
config file. All the modes extracted in that way DO use all ET4000 clock
registers. In addition to the ones grabbed from DOS, SVGAlib also adds a
few "standard" modes of its own, independent of the chip set.

The problem creeps up when you run SVGAlib from an extended (non-standard)
SVGATextMode mode, with a non-standard clock (not 25 or 28 MHz). SVGATextMode
has changed the ET4000 extended clock selection bits to get the special
(mostly higher) clock needed for that text mode. But when you select a
standard SVGAlib mode (like 320x200x256), it only changes the standard clock
bits, and leaves the extended ones as they were. 

The result is obvious: you get a different pixel clock than was intended.
Many ET4000 cards will run at 50 MHz when in fact they had to run at 25 MHz
for that graphics mode (you can test that with the clockprobe). A real
problem for all those DOOM fans around!

When using a non-standard graphics mode (which came from the BIOS, using
that special program for example), the problem does not show, since then ALL
clock selection bits are programmed.



Various strange interactions with the XFREE X-server
----------------------------------------------------

ET4000: Most problems are caused by a missing "hibit_..." option in the
TextConfig file or the XF86Config file or both. The option must be present
in both files, and must be the same in BOTH files, otherwise either one
might not work properly, especially when switching vt's.



Text mode clock limits are mostly LOWER than graphics mode clocks
-----------------------------------------------------------------

This in an often misunderstood aspect of SVGATextMode. Imagine yourself in
the place of the poor dude that designed the SVGA chip you're about to fry. 

His boss wants it to be the FASTEST and CHEAPEST chip on the market. So what
do you do? You look at what users really USE about their chip. 

Ah! They want fast Windows performance? Good, let's accelerate JUST those
things that make the Windows performance increase. You've just invented the
Windows accelerator.

And of course, everybody wants high resolution modes, so thay can throw a
zillion open windows onto the desktop without cluttering it.

Oh, and don't forget: the new buzzword is "VESA modes". Damn, we'll need
high screen refresh rates. Well, let's spend some money so the GRAPHICS part
is fast, 'cause that's what needs the high resolutions at high refresh
rates: a white background with a few darker parts in it is MUCH more
prone to screen flicker than the opposite: how can a black screen flicker?

So, that's it. Most VGA chips can run AT LEAST at 85 MHz in graphics mode.
If you want to spend a little more money, you'll be able to get 110 MHz, or
even 135 MHz. Really expensive things can even go as high as 200 MHz. And
some workstation boards can churn out pixels at an amazing 500 (five
hundred!) Million 24-bit pixels per second. But you'll need to spend some
more money on those. 

And text mode? Oh well, Almost nobody uses it anymore, now that windowed
systems are taking over. Only some die-hard programmers consider text modes
to be superior to windows stuff (for programming). 

So let's make sure they can do a 132x43 screen, or even 132x60. That'll shut
them up. We won't lose customers on that, since all other VGA card
manufacturers do the same. There's no money in that.


End of story. The bottom line: graphics chip/card makers cry out load that
their thing can run at xxx MHz, and shut up about text modes. With a good
reason: they're not running at that same speed as graphics modes. They
didn't spend money on getting text mode performance up to speed, or make the
chip a cent more expensive than the other brand.

The result is that all common SVGA cards have a maximum _used_ text mode
clock of just 40 or 45 MHz, since that's all that VGA card makers put in
their video BIOS'ses. So why design them to be able to run at 90 MHz?

If you would be able to browse the data sheets on some cards, you'd see the
difference. Most data sheets ONLY mention the maximum GRAPHICS pixel clock,
and never even mention text mode maximum clock. S3 and Cirrus Logic are
examples of this (don't shoot me if I overlooked it). The only positive
exception is the ET4000W32i/p data book. And it says the maximum graphics
clock is 86 MHz, and the max. text mode clock is 56 MHz.


And this immediately shows my point: don't expect text mode clocks to work
as high as graphics clocks! They're almost NEVER designed to do that.

But also keep in mind you might get lucky. The ET4000W32 for example, being
the only one I know of explicitly stating a maximum text mode clock, can be
used WAY beyond that maximum: although the data book says 56 is the maximum,
it runs well upto even 90 MHz.

The opposite example is the Trident 8900 series: although its pixel clocks
can be over 90 MHz, most cards go bananas at any speed over 45 MHz in text
mode. 


