lib/3rdparty/softx86/readme.txt

   1 Softx86: Software x86 CPU emulator library v0.00.0032
   2
   3 UNPACKING THE SOURCE TARBALLS
   4 =============================
   5
   6 Softx86 is distributed as several tarballs. The base tarball,
   7 softx86-vx.xx.xxxx, contains the source code for softx86
   8 itself. No prebuild binaries are provided. The other source
   9 tarballs are meant to be obtained and then extracted in the
  10 same directory that you extracted softx86 itself.
  11
  12 The additional tarballs contain:
  13 - The sample binaries, already assembled
  14 - Prebuilt Win32 versions of the libraries
  15   and softx86dbg in DLL and static form.
  16
  17 The Softx86 make system automatically detects the
  18 presence of the softx87 directory (which exists
  19 only if you extracted the softx87 tarball correctly).
  20 If it is found, makefiles are modified so that
  21 softx86dbg is built and compiled to use it.
  22
  23 as of v0.00.0030 the softx87 source tree is now
  24 distributed with softx86.
  25
  26 EXAMPLE OF UNPACKING THE ENTIRE SOFTX86 PROJECT:
  27
  28 cd /usr/src
  29 tar -xzf softx86-v0.00.0032
  30 cd softx86
  31 make
  32 make install
  33
  34 PLATFORMS SUPPORTED
  35 ===================
  36
  37 Softx86 is carefully written and maintained so that the same source
  38 tree can be used to produce Win32 and Linux binaries as well as
  39 Win32 DLLs and Linux shared libraries. Compiler-specific optimizations
  40 are welcome though they will be separated with #ifdef...#else...#endif
  41 statements and macros for full portability. Optimizations and code
  42 organization sensitive to various characteristics of the platform can
  43 be controlled via #defines in include/config.h.
  44
  45 COMPILING FOR WIN32
  46 ===================
  47
  48 To compile the Win32 versions you will need Microsoft Visual C++ 32-bit
  49 for Visual Studio 6.0 or higher. Service pack 5 and the latest processor pack
  50 are recommended but not required.
  51
  52 From Visual Studio, select "open workspace" and open softx86.dsw. Select
  53 "softx86 - release", then hilight both projects in the workspace window.
  54 Right click and select "build selection only" from the popup menu.
  55
  56 This should make the following files:
  57
  58 bin/softx86dbg.exe      Win32 console application (NOT DOS!) not unlike
  59                     DOS DEBUG to test softx86.
  60
  61 lib/softx86.lib         Static library of softx86.
  62
  63 WARNING: The interfaces and structures can and will change! If you distribute
  64          a binary version of your program that uses Softx86, later versions
  65          may break your program! This is alpha software, the context structure
  66          has not been finalized!
  67
  68 To recompile the test COM programs, you will need the Win32 or DOS version of
  69 NASM installed somewhere referred to in your PATH= variable or in the same
  70 directory.
  71
  72 COMPILING FOR LINUX
  73 ===================
  74
  75 To compile for Linux you will need GCC 3.2.xx or higher, NASM 0.98 or higher,
  76 make 3.79 or higher, and GNU ld 2.13 or higher.
  77
  78 If you extracted the source tarball over the source of older versions please
  79 type "make distclean" to clean up the source tree.
  80
  81 Type "make" to compile the entire project.
  82 This will make the following files:
  83
  84 bin/softx86dbg          console application not unlike DOS DEBUG to test
  85                         softx86.
  86
  87 bin/softx86dbg-static   statically linked version of softx86dbg.
  88
  89 lib/libsoftx86.a        Static library of softx86.
  90
  91 lib/libsoftx86.so       Shared library of softx86.
  92
  93 Then, super-user to or logon as "root" and type "make install". This
  94 will run a bash shell script that copies libsoftx86.a and libsoftx86.so
  95 to your /usr/lib directory. This script will also copy softx86.h and
  96 softx86cfg.h to your /usr/include directory. If any errors occur during
  97 the installation process the script will immediately exit with a message.
  98
  99 WARNING: The interfaces and structures can and will change! If you distribute
 100          a binary version of your program that uses Softx86, later versions
 101          may break your program! This is alpha software, the context structure
 102          has not been finalized!
 103
 104 USING SOFTX86DBG
 105 ================
 106
 107 Softx86dbg is a DOS DEBUG-style debugger that uses Softx86. It allows
 108 very simple debugging of COM executable binary images written for DOS.
 109 It does *NOT* emulate directly from an assembly language listing!
 110
 111 Softx86dbg does not load a COM image by default. You must specify one
 112 on the command line.
 113
 114 DESIGN GOALS
 115 ============
 116
 117 The goal of Softx86 is to eventually become a full functioning software
 118 clone of the Intel 80x86 CPU. I want to stress, however, that this library is
 119 intended to become exactly that and no more. The interface between this
 120 library and the host application is designed so that this library is only
 121 responsible for fetching data and executing/decompiling instructions; the host
 122 application is responsible for emulating other aspects of the PC platform
 123 hardware (i.e. system timer or keyboard controller) and providing the
 124 simulated memory for the CPU to fetch data from or write data to, thus
 125 this library can be used to emulate ANY platform or environment involving
 126 some use of the x86.
 127
 128 WHY NOT C++
 129 ===========
 130
 131 I am writing the majority of this library in C (even though the softx86dbg
 132 program is in fact written in C++) so that it can be linked to either C or
 133 C++ programs (whatever your preference). Writing this library in C++ in
 134 contrast would render it unusable for C programs or require the use of
 135 "wrappers".
 136
 137 HOW DOES THE LIBRARY INTERACT WITH THE HOST APPLICATION?
 138 ========================================================
 139
 140 The host application allocates memory for a "context structure" that
 141 represents one CPU (of type struct softx86_ctx). The host app then calls
 142 softx86_init() to initialize the memebrs of that structure, given a value
 143 specifying which revision of the 80x86 to emulate. Once done, the host app
 144 can use other library API functions like softx86_set_instruction_ptr() to
 145 set the instruction pointer, register values, etc.
 146
 147 The library CPU does not automatically start executing instructions on
 148 it's own. It only executes instructions when the host app tells it to by
 149 repeatedly calling softx86_step() per instruction. Thus, how fast the
 150 software CPU runs is highly dependant on how efficient the host application
 151 is.
 152
 153 The library can (and will) request memory and I/O data from the host app
 154 via callback function pointers contained within the context structure. There
 155 is currently no API function to set them, it is assumed that the host
 156 application will assign to them the address of functions within itself that
 157 will fullfill the I/O request.
 158
 159 There are currently four callback functions to the host app:
 160
 161 void (*on_read_memory)(/* softx86_ctx */ void* _ctx,
 162         sx86_udword address,sx86_ubyte *buf,int size);
 163
 164 void (*on_read_io)(/* softx86_ctx */ void* _ctx,sx86_udword address,
 165         sx86_ubyte *buf,int size);
 166
 167 void (*on_write_memory)(/* softx86_ctx */ void* _ctx,sx86_udword address,
 168         sx86_ubyte *buf,int size);
 169
 170 void (*on_write_io)(/* softx86_ctx */ void* _ctx,sx86_udword address,
 171         sx86_ubyte *buf,int size);
 172
 173 on_read_memory:  called when the CPU wants to fetch from simulated memory
 174 on_write_memory: called when the CPU wants to store to simulated memory
 175 on_read_io:      called when the CPU wants to fetch from an I/O port
 176                  (typically the IN/INSB instruction)
 177 on_write_io:     called when the CPU wants to store to an I/O port
 178                  (typically the OUT/OUTSB instruction)
 179
 180 SOFTX86 DOESN'T SUPPORT FPU INSTRUCTIONS BY ITSELF
 181 ==================================================
 182
 183 Softx86 does not support FPU instructions by itself,
 184 following the design of the original chip. Instead,
 185 FPU opcodes are handed off to a callback function
 186 which can then call an external library that functions
 187 as the 8087. If the callback function is not assigned,
 188 the FPU opcodes D8h thru DFh are treated as unknown and
 189 invalid opcodes.
 190
 191 /* this is called when the CPU is asked to execute an FPU opcode */
 192 int (*on_fpu_opcode_exec)
 193         (/* softx86_ctx */void* _ctx,sx86_ubyte opcode);
 194
 195 /* this is called when the CPU is asked to decompile an FPU opcode */
 196 int (*on_fpu_opcode_dec)
 197         (/* softx86_ctx */void* _ctx,sx86_ubyte opcode,char buf[128]);
 198