[NTVDM]

[reactos.git] / lib / 3rdparty / softx86 / doc / softx86.txt

Softx86 - Stock Software Intel 80x86 emulation library

Introduction
============

Softx86 is designed to be a simple library that one can
link into their program for 80x86 emulation purposes.
The primary goals of this project are:

* accurate emulation
* reasonably sized memory footprint
* modular design that closely models the actual
  hardware signals (Clocking, I/O, addressable
  memory, #INT and #NMI) using callbacks
  set up by the program

The Softx86 library itself is designed to emulate ONLY
the CPU, none of the surrounding hardware. Just like
the real thing the program using Softx86 is responsible
for providing RAM, I/O, and #INT/#NMI signals as
appropriate, and making the necessary calls to cycle the CPU.


+-----------------------------------------------+
| SOFTX86 LIBRARY IN A TYPICAL EMULATOR PROJECT |
+-----------------------------------------------+


 +-----------------------------------+
 | APPLICATION AS THE "MOTHERBOARD", |
 | "POWER SUPPLY", "RAM", AND "I/O   |         
 | DEVICES".                         |         +------------------------------+
 |                                   |         | SOFTX86 LIBRARY AS THE "CPU" |
 | MAIN LOOP                         |         |                              |
 |   |                               |         | CPU INSTRUCTION EXECUTIONEER |
 |   +-----------------------------------------------------------^        |   |
 |                                   |         |                          |   |
 | ADDRESSABLE RAM EMULATION<=====================(callback)==============|   |
 |                                   |         |                          |   |
 | I/O PORT EMULATION<============================(callback)==============/   |
 |                                   |         |                              |
 | INTERRUPT SIGNAL SOURCE           |         |                              |
 |   \/                 \/           |         |                              |
 | #INT LINE MODERATOR   --------------------->| #NMI handler                 |
 |   \/                              |         |                              |
 |    ---------------------------------------->| #INT handler                 |
 |                                   |         |                              |
 +-----------------------------------+         +------------------------------+

 Softx86 is like a lone CPU, it needs a "motherboard" to interact with.


The Softx86 API uses context structures to represent
a CPU, rather than internal variables, so that
it is possible to emulate more than one CPU
simultaneously using the same library. This also
puts the CPU's entire state in one location for both
Softx86 and the application using it, so that use
of numerous API calls are generally not needed to get
or set the CPU state (although some members should
not be modified directly).

STEP 1: CREATING A CPU
======================

To create a CPU, you first need to allocate a region
of memory of size sizeof(softx86_ctx).

----- C example -----
softx86_ctx* cpu;
cpu = (softx86_ctx*)(malloc(sizeof(softx86_ctx)));

----- C++ example -----
softx86_ctx* cpu;
cpu = new softx86_ctx;

Using memset() to fill the contents of that area with NULL
is advised but not absolutely necessary.

Then call API function softx86_init(), passing it the address
of the context structure and a constant from softx86.h
that represents which version of the 80x86 the context
structure represents.

------ C/C++ example -----
/* I want this CPU to act like a 80286. */
/* Act appropriately if there is an error. */
ser=softx86_init(cpu,SX86_CPULEVEL_80286);
if (ser == 0) {
        printf("ERROR: Unable to initialize CPU\n");
        return 0;
}

STEP 2: SET UP CALLBACKS
========================

You've made the CPU but now it needs to know who to call
for fetching RAM and I/O. Set that up now.

WARNING: This is grossly oversimplified, not including code
         to properly handle requests that fall outside the
         1MB range! YES IT CAN HAPPEN, ESPECIALLY IF EMULATING
         THE 286 WHICH CAN ADDRESS 16MB! See Softx86dbg source
         code for a better example!

----- C/C++ example -----
/* can hold the entire 1MB range supported by the 8086 */
unsigned char BIG_HUNK[1024*1024];

/* called when reading memory */
void on_read_memory(void* _ctx,sx86_udword address,sx86_ubyte *buf,int size)
{
        memcpy(buf,BIG_HUNK+address,size);
}

/* called when writing memory */
void on_write_memory(void* _ctx,sx86_udword address,sx86_ubyte *buf,int size)
{
        memcpy(BIG_HUNK+address,buf,size);
}

/* called when reading an I/O port */
void on_read_io(void* _ctx,sx86_udword address,sx86_ubyte *buf,int size)
{
        /* in this example there are no I/O ports */
        memset(buf,0xFF,size);
}

/* called when writing an I/O port */
void on_write_io(void* _ctx,sx86_udword address,sx86_ubyte *buf,int size)
{
        /* in this example there are no I/O ports */
}

/* function to set up the callbacks for given cpu */
void setup_callbacks(softx86_ctx *cpu)
{
        cpu.callbacks->on_read_memory   = on_read_memory;
        cpu.callbacks->on_write_memory  = on_write_memory;
        cpu.callbacks->on_read_io       = on_read_io;
        cpu.callbacks->on_write_io      = on_write_io;
}

Once everything is set up, you must call softx86_reset()
to reset the CPU.

----- C/C++ example -----
softx86_reset(cpu);

STEP 3: GIVE THE CPU SOMETHING TO EXECUTE
=========================================

For the CPU to execute something it must have valid instructions.
There are many sources that these can be obtained, starting with
simple MS-DOS .COM executables (which can be found on any web site
dedicated to ancient DOS programs and games), or perhaps whatever
happens to be on the hard drive of that old dusty 286 in the corner,
although you can also find some on many Windows 95/98-based systems.
By .COM executables I DO NOT MEAN COM/OLE ActiveX controls!
Anyway, best results can be obtained by using a COM program that is
simple (doesn't rely too much on direct hardware access or performs
a simple function).

Loading a COM executable into your program's simulated RAM should be
easy:

----- C/C++ example -----
void load_code()
{
        FILE *comfile;

        comfile = fopen("whatever.com","rb");
        if (!comfile) {
                printf("Unable to load program!\n");
                return 0;
        }

        /* remember BIG_HUNK[] ? */
        /* 0x100 offset because of PSP segment and such */
        /* CS:IP = 0x1000:0x0100 */
        /* (0x1000 << 4) + 0x100 = 0x10100 */
        fread(BIG_HUNK+0x10100,65280,1,comfile);
        fclose(comfile);

        /* set up a PSP and such... */
        /* I'll leave it up to you as an exercise :) */

        /* done */
        return 1;
}

Now that there is code to execute, we need to tell the CPU where
to start executing. To do this, we must redirect the INSTRUCTION
POINTER.

NOTE: The instruction pointer variables can be accessed directly
      through the context structure to obtain the values and
      the cached information (such as precalculated segment->linear
      conversion). HOWEVER you must not modify these values
      directly!

----- C/C++ example -----
softx86_set_instruction_ptr(cpu,0x1000,0x100);

Depending on the program, it is most likely that you will want
to set up the stack pointer as well so that the program has a
usable stack.

NOTE: The stack pointer must NOT be modified directly, although
      the values can be readily obtained through the context
      structure!

----- C/C++ example -----
softx86_set_stack_ptr(cpu,0x1000,0xFFF8);

Many DOS programs assume that DOS will set the segment registers
so that CS = DS = ES. Set the segment registers appropriately:

NOTE: The segment registers carry with them a cached copy of
      various state information (limits, precalculated
      segment->linear conversion, protected mode bits, etc).
      They may be directly accessed through the context
      structure but must not be modified directly!

----- C/C++ example -----
softx86_setsegval(cpu,SX86_SREG_DS,0x1000);     /* set DS */
softx86_setsegval(cpu,SX86_SREG_ES,0x1000);     /* set ES */

STEP 4: CYCLING THE CPU
=======================

Execution doesn't happen unless your program explicitly wants
it to happen, which it does by calling softx86_step(). For
each call to softx86_step(), one instruction is executed
and then control is returned to your program. The return
value indicates success or failure.

----- C/C++ example -----
x=softx86_step(cpu);
if (x == 0) {
        printf("The CPU failed to execute or recognize an instruction\n");
}

During the call, softx86_step() is likely to call your
memory and I/O callback routines (in fact it's guaranteed).
When softx86_step() returns the instruction pointer values
and all registers affected will be updated according to
whatever instruction was executed. On return, the instruction
pointer points to the next instruction that will be executed,
or points to the offending instruction if an error occured.


* FOR MORE DETAILS REFER TO THE SOFTX86DBG SOURCE CODE, OR
  E-MAIL ME AT jcampbell@mdjk.com.


FREEING/DISPOSING OF A CPU
==========================

Disposing of a CPU is simple. Call softx86_free()
and then free the memory you allocated for that
structure. That's it.

NOTE: It is very important to call softx86_free()
      because Softx86 itself allocates memory
      for CPU emulation purposes associated with
      that CPU. Freeing the structure and not
      calling softx86_free() may (very likely!)
      result in memory leaks!

----- C example -----
softx86_free(cpu);
free(cpu);

----- C/C++ example ----
softx86_free(cpu);
delete cpu;


HOW TO SIGNAL AN EXTERNAL HARDWARE INTERRUPT
============================================

Use API call softx86_ext_hw_signal() to emulate an #INT
signal from hardware.

NOTE: Do not assume that this function will succeed.
      If softx86_ext_hw_signal() has already been called
      but the CPU has not yet acknowledged the interrupt,
      softx86_ext_hw_signal() will return 0 (error).
      Otherwise, it will return 1 (success). If you plan
      on emulating a platform with multiple interrupt
      signals possible, consider writing a wrapper for
      this call in your program that moderates the
      signals somehow. For example, write a portion of
      your program that emulates the Programmable
      Interrupt Controller in IBM PC/XT/AT+ hardware, then
      write a general function your code can call that
      emulates IRQ signals being sent to the PIC. The PIC
      emulator can then act as a moderator that uses this
      function to pass the IRQ signals to the CPU.

----- C/C++ example, signalling INT 9 (PC/XT/AT+ IRQ 1) from hardware -----
int i,j;

/* loop until we can signal the interrupt we want */
/* ---or, until CPU failure */
i=1;
j=0;
while (i && !j) {
        i=softx86_step(cpu);
        if (i) j=softx86_ext_hw_signal(cpu,9);
}

HOW TO SIGNAL AN EXTERNAL NMI (NON-MASKABLE) HARDWARE INTERRUPT
===============================================================

Use API call softx86_ext_hw_nmi_signal() to emulate an
#NMI signal from hardware.

NOTE: Do not assume that this function will succeed.
      If #NMI has already been activated but the CPU
      has not yet acknowledged the interrupt, this
      function will return 0 (error). Otherwise, it
      will return 1 (success).

NOTE: This signal is processed immediately, even if
      #INT is active. #NMI has higher priority than
      #INT.

----- C/C++ example, signalling NMI from hardware -----
int i,j;

/* loop until we can signal the interrupt we want */
/* ---or, until CPU failure */
i=1;
j=0;
while (i && !j) {
        i=softx86_step(cpu);
        if (i) j=softx86_ext_hw_nmi_signal(cpu);
}

HOW TO FORCE SOFTWARE INTERRUPT
===============================

calling softx86_int_sw_signal() causes the CPU to branch to
an interrupt as if the INT instruction had just been executed
in the program.

NOTE: If the CPU is in protected mode, this function may fail
      if the interrupt is invalid according to the IDT or
      GDT/LDT!

----- C/C++ example, software interrupt INT 21h -----
softx86_int_sw_signal(cpu,0x21);

HOW TO USE THE DECOMPILER
=========================

In addition to providing the ability to execute instructions,
Softx86 provides an alternate API call to decompile instructions
at an alternate instruction pointer referred to as the
"decompiler instruction pointer".

First, you set the decompiler IP using
softx86_set_instruction_dec_ptr() or
softx86_decompile_exec_cs_ip().

NOTE: The decompiler instruction pointer, like the
      CPU instruction pointer, MUST NOT BE MODIFIED
      DIRECTLY!

----- C/C++ example, setting decompile CS:IP to specific values -----
sx86_udword seg,ofs;
softx86_set_instruction_dec_ptr(cpu,seg,ofs);

----- C/C++ example, setting decompiler CS:IP == current instruction pointer -----
softx86_decompile_exec_cs_ip(cpu);

Then, you call softx86_decompile() for each instruction, providing
for it a char array that is 256 bytes wide or larger.

----- C/C++ example, decompiling 10 instructions following CS:IP -----
char asmbuf[256];
int j;

softx86_decompile_exec_cs_ip(cpu);
for (j=0;j < 10;j++) {
        if (!softx86_decompile(cpu,asmbuf)) {
                printf("*decompiler error!\n");
                j=10;   /* terminate the loop */
        }
        else {
                printf("%s\n",asmbuf);
        }
}

HOW TO DETERMINE THE SOFTX86 VERSION
====================================

Obtaining the version of the Softx86 library your
program is using is simple. Have 3 integers ready
and call softx86_getversion() like this:

int x,major,minor,subminor;

x=softx86_getversion(&major,&minor,&subminor);
if (!x) {
        printf("Unable to obtain version!\n");
        return 1;
}

You can then determine if you're using the version
you were compiled for by matching them against the
constants (defined in softx86.h) SOFTX86_VERSION_HI,
SOFTX86_VERSION_LO, and SOFTX86_VERSION_SUBLO.

if (major != SOFTX86_VERSION_HI ||
    minor != SOFTX86_VERSION_LO ||
    subminor != SOFTX86_VERSION_SUBLO) {
    printf("ERROR: Version mismatch!\n");
    return 1;
}

HOW TO CHANGE THE GENERAL REGISTERS
===================================

All of the general registers (AX,BX,CX,DX,SI,DI,BP,SP)
are of type softx86_regval, which is a union that allows
either partial or complete access of the contents
(no matter what the native byte order is).

The general registers reside in
cpu->state.general_reg[], an array of softx86_regval
values which may be indexed using the constants defined in
softx86.h:

SX86_REG_AX,SX86_REG_BX,SX86_REG_CX,SX86_REG_DX,
SX86_REG_SI,SX86_REG_DI,SX86_REG_BP,SX86_REG_SP.

NOTE: You must not modify the SP register directly!
      Use softx86_set_stack_ptr()

Thus, you can read/modify AX like this:

cpu->state.general_reg[SX86_REG_AX].w.lo

or EAX like this:

cpu->state.general_reg[SX86_REG_AX].val

or AH like this:

cpu->state.general_reg[SX86_REG_AX].b.hi

*------------------------------------*
| softx86_regval union naming scheme |
*------------------------------------*
general_reg[idx].val =        the entire 32 bit register (e.g. EAX)
general_reg[idx].w.lo =       the lower 16 bit portion (e.g. AX bits 0-15)
general_reg[idx].w.hi =       the upper 16 bit portion (bits 16-31)
general_reg[idx].b.lo =       the lower 8 bit portion (e.g. AL bits 0-7)
general_reg[idx].b.hi =       the upper 8 bit portion (e.g. AH bits 8-15)
general_reg[idx].b.extra[0] = bits 16-23 as a byte
general_reg[idx].b.extra[1] = bits 24-31 as a byte

HOW TO CHANGE THE INSTRUCTION POINTER
=====================================

The instruction pointer lies in cpu->state.reg_ip (IP)
and cpu->state.segment_reg[SX86_SREG_CS].val (CS).

NOTE: You should NOT change this value directly! Use
      softx86_set_instruction_ptr() or
      softx86_set_near_instruction_ptr() instead!
      Changing reg_ip directly may cause problems
      with instruction prefetch emulation or
      any portion of the code that caches the
      instruction pointer.

cpu->state.reg_ip is a DWORD value that represents the
current offset in the code segment.
cpu->state.segment_reg[SX86_SREG_CS].val represents the
actual value of the CS segment register, along with the
precalculated linear and limit values for the segment/selector.

To change both CS and IP to known values, call
softx86_set_instruction_ptr() with the new CS:IP values.

NOTE: softx86_set_instruction_ptr() and
      softx86_set_near_instruction_ptr() will return
      0 (error) if the CS:IP values are invalid.

----- C/C++ example -----
x=softx86_set_instruction_ptr(cpu,0xF000,0xFFF0);
if (!x) {
        printf("Failed to set instruction pointer!\n");
        return 1;
}

If you only wish to change IP without changing CS,
you may call softx86_set_near_instruction_ptr().

----- C/C++ example -----
x=softx86_set_near_instruction_ptr(cpu,0x100);
if (!x) {
        printf("Failed to set instruction pointer!\n");
        return 1;
}

HOW TO CHANGE THE SEGMENT REGISTERS
===================================

The segment registers are stored in the context structure
under cpu->state.segment_reg[] and are of type
softx86_segregval. softx86_segregval is a special structure
that holds the value of the register as well as hidden
cached values related to the segment register.

typedef struct {
        sx86_uword      val;            /* visible to program---the value */
        sx86_udword     cached_linear;  /* hidden---linear address of segment */
        sx86_udword     cached_limit;   /* hidden---limit of segment */
} softx86_segregval;

A particular segment value may be obtained by using
constants SX86_SREG_ES, SX86_SREG_CS, SX86_SREG_DS,
SX86_SREG_SS as indices to the array.

NOTE: Do NOT modify these values directly. Use
      softx86_setsegval() instead!

To retrieve the current value in CS for example:

segment = cpu->state.segment_reg[SX86_SREG_CS].val;

To set the value of CS:

x=softx86_setsegval(cpu,SX86_SREG_CS,0xF000);
if (!x) {
        printf("Unable to set CS!\n");
        return 1;
}

NOTE: softx86_setsegval() will return 0 (error)
      if the CS value is invalid.