**********************************************************************
** NOTE - This code is still under development and may be UNSTABLE ***
**********************************************************************

The current version of the CPU emulator, as of dosemu-1.1.x, has been
rewritten from scratch, and is now called simx86.

Dosemu started to introduce the emulator in version 0.97. The first step
was to port the vm86 kernel interface in November 1997. At that time, I
was only able to boot DOS (up to the C:> prompt) in plain console mode.
One year later, I implemented the DPMI interface and 32-bit code.

In dosemu-0.99 I ported part of the TWIN library from Willows Software
(http://www.willows.com). In Twin, only a very small fraction of the
time is spent emulating CPU instructions; most of the time is taken by
API calls. OTOH, in dosemu most of the work is done by the emulated CPU,
and a totally high-level language approach, while good for portability,
is unacceptably slow on any CPU <1GHz.

Two approaches remain:
1) scan the instruction flow for sensitive instructions and put
   breakpoints on them, executing the rest of the code natively.
   This is the fastest way but it is not portable.
   Please have a look at plex86 (http://www.plex86.org), it runs DOS.
2) try to speed up things with a binary compiler. Porting it to
   other architectures requires only to rewrite the backend.
   This is the way I choose for simx86.

The purposes of this emulator are:

1) porting dosemu on other CPUs (Alpha,PPC,...)
   The need for such a port is decreasing with time; first, who cares
   anymore about DOS programs today?; then, the only successful non-
   Intel platform out there is the iMac, where AFAIK no one ever asked
   for dosemu...
2) allowing us to run 'ring-0' protected-mode programs
   ... up to Win95? Hmmm, wine will be there LONG before us, and
   there is no way of doing this from user mode without a very slow
   explicit tasking+paging emulation.
   It will be feasible to run single-task programs, like DPMI servers,
   in pseudo-ring0 mode, by letting Linux do the paging in hardware;
   however, having more than one task will require _at_least_ a kernel
   module. IMHO it is better to switch to plex86.
3) being a debugging tool for DOS programs and for dosemu itself
   this is still the main reason for emulating an ix86 on
   an ix86 machine :-)
4) replacing Bart Oldemans instremu (part of vgaemu) with a more
   complete CPU emulation. The only feasible solution, which is here
   partially implemented, is to start dosemu in cpuemu mode and call
   vm86() and run_dpmi() from INSIDE the emulator (and not the other
   way as everyone thinks).

**********************************************************************

As of Jun 1,2001, I'm developing on a 350MHz Pentium II and an 800MHz Athlon.

The programs I saw working under the emulator include:
- IBM PC DOS 7.0
- ezedit
- Borland tasmx
- Norton Commander 5
- some djggp test pgms
- gcc (djgpp)
- doom[2]
- Norton Diagnostics
- WinOS2 (Win 3.1), more or less (mouse and timing problems?)

What will probably never work:
- serial code, sound code, and all sort of fast,realtime stuff
  (but who knows, 1GHz+ CPUs are already available)

Note that FPU diagnostic programs will likely always fail, because all
the FP instructions are emulated with double (64-bit) precision, instead
of long double (80-bits) as in the real FPU.

**********************************************************************

How to start dosemu with cpu-emu:

Set
	$_cpu = "emulated"

in your dosemu.conf file. This _enables_ the use of the CPU emulator
but doesn't _start_ it, unless you undefine DONT_START_EMU in cpu_emu.h
(don't do it unless you want do debug DOS itself!).
This was done to skip the (long and tiresome) boot phase of DOS and to
make dosemu compatible with the normal (non-cpuemu) usage without the
need of using extra parameters or editing dosemu.conf every time.

In the default cpuemu configuration, then, dosemu behaves in the normal
(real CPU) way until you explicitly switch it into CPU emulation mode.
The commands to switch the cpuemu on/off are
	ecpuon.com	and	ecpuoff.com
Put them in your autoexec.bat where necessary. They are an interface
to int0xe6 functions 0x90 and 0x91 (see src/base/async/int.c). You
can directly call these functions from inside a program.

You can edit the file src/include/cpu-emu.h to modify the emulator
configuration parameters before compiling dosemu. Please do not change
these settings unless you know what you are doing; see the included
comments.

There is an added debug option ('e') for the cpuemu. Note that using
'a' enables all debug options BUT this one, if you really want a full
debug trace you must use -Dae instead of -Da.
Any setting of 'e' greater than 2 is VERY HEAVY both for your CPU and
for the space on your hard disk, use this option with care if you need
it (but... do you really _need_ it? :-)

There are also some undocumented options, mainly for debugging cpuemu
itself, so they'll better stay undocumented.

Happy emulating.

Alberto Vignani	- Jun.11,2001