
!!!!!!!!!!!!! READ THIS VERY CAREFULLY !!!!!!!!!!!!!!
!!!!!!!!!!!!! READ THIS VERY CAREFULLY !!!!!!!!!!!!!!
!!!!!!!!!!!!! READ THIS VERY CAREFULLY !!!!!!!!!!!!!!

----- Warning!!!

DOSEMU has all new video drivers for 0.61.

The code is contained is taken from SVGALIB 1.25.  I don't claim that any
of it will work at the moment.  Using any of the code could, potentially,
be very dangerous to your hardware.

----- What does the video code do?

The video code serves two purposes:  to allow you to switch virtual consoles
(especially in graphics mode) and to allow DOS programs to use the full
capacity of your video board.

----- What chipsets does DOSEMU currently support?

[If you test one of these and it works, please report it to the mailing list]

working:
  plain VGA
  Paradise/Western Digital

new, almost works:
  S3 (at least for the Trio64)

new, untested:
  ATI enhanced VGA chips
  ARK Logic ARK1000PV/2000PV
  Cirrus GD542x/3x
  ET3000 series (TSENG chips)
  ET4000 series (TSENG chips)
  TVGA 8900C/9000 Trident chips (and possibly 8800CS/8900A/B)
  OAK OTI-037/67/77/87
  EGA

unsupported:
  Mach32 chipsets
  ???

----- What chipset does DOSEMU think I'm using?

Run 'dos -D+v -o /tmp/video.log'  After running DOSEMU, it will contain a
whole slew of information about your video configuration.  At the beginning
of the file will be some lines trying to detect your video card and
configuration.  They should look something like:

VGA: Testing for "ATI VGA" driver
VGA: Testing for "S3" driver
VGA: Testing for "OAK" driver
...
VGA: Using driver "Vanilla VGA", going to IOPL(0)

----- What chipset DOES my card have?

A good question.  If your video card documentation doesn't tell (it usually
does, but it may be buried somewhere in a cryptic paragraph, micro-printed
in a smudge that looks like a printing error.)

MSD.EXE and several other similar programs can be used under DOS to extract
a fair amount of the information about your system configuration.  My
understanding is that the program "SuperProbe" serves a similar purpose
under Linux, though I can not attest to this.

----- I'm having problems!!!

First, if you know what chipset your video card uses, check it on the list
of supported hardware.

Second, if your card is on the list of supported hardware, check to make
certain that the chipset DOSEMU thinks your chip is and your chipset are
one and the same.  (If not, please tell us.)  You can force DOSEMU to
choose the correct chipset using the video { chipset xxx } command in
the DOSEMU.CONF file.

Third, time to appeal to the mailing list:

When having problems with your video configuration, please try to include
the following information:

1. what you tried to do (boot dosemu, look at a jpeg, change virtual consoles)
2. what happened (the screen went blank, started smoking, etc.)
3. your video card manufacturer, chipset, bios, bus type, etc.
   (much of 3 can be obtained via MSD.EXE run under real DOS, not DOSEMU)
4. your system configuration (version of Linux, version of DOSEMU, etc.)
5. what DOSEMU thought your video card type was (see above)

Look at the contents of the file /tmp/video.log.  It should contain a list
of video cards that DOSEMU was trying to detect for you.  If your card is
incorrectly detected, please send a note telling your video card,
manufacturer, chipset, etc. (MSD.EXE under DOS will tell most of this
information) and the chipset DOSEMU detected in your system to the DOSEMU
mailing list.  Note: MSD.EXE should be run under 'real' DOS and not DOSEMU.

---------------------- HACKER'S SECTION ------------------------

You can stop reading now if you don't feel like helping with the video code.

What you're still reading?  You want to help fix the bugs?  Bless you!

There are several sections to the video code in the various modules:

1.  Saving/restoring video state
2.  Virtualizing the registers
3.  Setting/removing up the I/O permissions

[1]   Saving/restoring video state

This code is handled by the SVGALIB modules extsave & extset procedures
at the moment.  This is actually not ideal because SVGALIB and DOSEMU
don't work in the same way.  SVGALIB knows which registers it's going to
set and when, so things are more or less predictable.  If they forget a
register or two, it's usually not too big of a deal.  In DOSEMU it'll
probably make a difference in your one of the spiffy 1024x768x65536 class
video modes.

If your card is making use of registers outside of the usual VGA registers,
they either be listed in the source code or else you will see a list of
"unknown port" values, especially in the section where your VBIOS is
initializing.

If the registers are not correctly saved or restored, when you try to switch
video consoles you will experience anything from seeing odd looking
characters (the mapping of pages 0-3 wasn't handled correctly), to garbage
(a register probably got dropped somewhere), to a blank screen (ditto), to
a screen that 'pops and crackles' (I've heard this one about the Mach chips.)

If you can swap text mode fine, then you can probably also swap the basic
video modes okay as well (anything in standard VGA.)  SVGA modes are likely
to start giving grief in terms of switching consoles because they start
using the special registers.

[2]  Virtualizing the registers

When you switch away from your virtual console in a video mode, DOSEMU does
not pause -- your program keeps running in the background.  Because of this,
DOSEMU needs to somehow maintain the video register state so as to be able
to correctly restore it when you switch back.  The standard VGA registers
are completely virtualized -- I have a 320x200x256 program called 'tunnel'
which draws a tunnel and then cycles through the color palette.  This
continues to run just fine when I switch away.

However, at the time of this writing, none of the SVGA registers are 
virtualized.  Virtualizing them just means taking the time to write the
code corresponding to vga_port_in() for the SVGA registers.

[3]  Setting/removing up the I/O permissions

Your video card may need registers beyond the standard VGA ports.  Most of
the newer chipsets do these days.  Once you have a list of ports, you have
a number of options.  The easiest way at the moment is to do the following:

In your SVGA card-specific *_init routine, set up a structure to register
a port handler for the extended ports on your video chip.  Don't forget
that ports are usually the same & 0x3ff, so you should double-check to
ensure that your chipset doesn't use some of the other bits for flags (like
the S3, Western Digital & other chipsets.)

In your video_port_* routine, as with vga_port_in, you do a safe port
write or read if (vga_enable is TRUE -- this is a flag telling whether or
not we own the console and thus the video chip) or virtualizes the video
read/write (see [2]).
