22. Software X386 emulation

This section written in a hurry by Alberto Vignani <vignani@mbox.vol.it> , Oct 20, 1997

22.1. The CPU emulator

The CPU emulator has been derived from <the Twin Willows libraries>. Only the relevant parts of the library, namely the /intp32 subdirectory and the needed include files, have been extracted from the Twin sources into the src/twin directory. The Twin reference version is 3.1.1. In the Twin code, changes needed for the dosemu interface have been marked with
        #ifdef DOSEMU

Here is a summary of the changes I made in the Twin libraries:

The second part of the cpuemu patch is the interface to dosemu, which is controlled by the X86_EMULATOR macro. This macro was probably part of a very old attempt to interface dosemu with Bochs, I deleted the old code and replaced it with the Twin interface.

The X86_EMULATOR macro enables the compilation of the two files (cpu-emu.c and emu-utils.c) in the src/emu-i386/intp32 directory, which contain the vm86 emulator call (taken from the kernel sources) and some utility/debug functions. These files are kept separate from the Twin directory but need it to compile.

For controlling the emulator behaviour, the file include/cpu-emu.h provides three macros:

DONT_START_EMU

if undefined, the emulator starts immediately; otherwise, a call to int 0xe6 al=0x90 is required to switch from the standard vm86 to it. To switch in and out from the emulator, the small utilities 'ecpuon.com' and 'ecpuoff.com' are provided.

TRACE_HIGH

controls the memory areas you want to include into the debug trace. The default value excludes the video BIOS and the HMA, but feel free to change it following your needs.

VT_EMU_ONLY

if defined, use of the emulator forces VT console mode, by ignoring the 'console' and 'graphics' statements in the video config line.

To enable the CPU emulator add
        cpuemu on
to compiletime-settings, or pass
        --enable-cpuemu
to configure.

To use the emulator, put
        cpu emulated
into /etc/dosemu.conf. Or start dosemu with -I 'cpu emulated'.

The 'e' flag was added to the debug control string, it has currently a value range from 1 to 4 and controls the level of detail the emulator writes into the dosemu debug log. WARNING - logs greater than 100Mbytes are the rule with cpu-emu!!!. As a safety measure, 'e' is not automatically added to the debug flags when you use 'a'; the 'e' parameter must be explicitly added. In addition, there is a new configuration parameter for /etc/dosemu.conf:
        logfilesize value
This will limit the file size of the logfile. Once the limit is reached, it truncates the file to zero and continues writing to it.