mirror of
https://github.com/reactos/reactos.git
synced 2025-02-24 17:34:57 +00:00
c8317ea346
Allow compilation warnings (the downsides are that it generates LOTS of warnings...) svn path=/branches/ntvdm/; revision=59247
237 lines
9.4 KiB
Text
237 lines
9.4 KiB
Text
Frequently Asked Questions v0.00.0033
|
|
|
|
Q. When will Softx86 become a full-fledged PC emulator?
|
|
|
|
A. It won't. It will however become a full-fledged Intel 80x86 CPU
|
|
clone that you can tie into your PC emulation software.
|
|
|
|
Q. Where are the sample DOS binaries used to test the emulator?
|
|
|
|
A. Prebuilt binaries are now distributed separately from the
|
|
source tarball. The source code is still provided, so you
|
|
can assemble them yourself if you have NASM (Netwide Assembler)
|
|
installed on your system.
|
|
|
|
Q. How do I use softx86dbg?
|
|
|
|
A. Bring up the command prompt (Windows or Linux), change to the
|
|
root directory of the source tree and type "bin/softx86dbg"
|
|
followed by a path to a DOS .COM executable.
|
|
|
|
For example, to run samples/test11.com in the emulator, type:
|
|
|
|
bin/softx86dbg samples/test11.com
|
|
|
|
Linux users may benefit from running the statically linked
|
|
version (especially if they cannot "su root" and "make install")
|
|
because a previous version of the library installed in
|
|
/usr/local/lib might be incompatible with the latest version
|
|
of softx86dbg. You can run the statically linked version by
|
|
typing:
|
|
|
|
bin/softx86dbg-static samples/test11.com
|
|
|
|
softx86dbg will let you know if it couldn't load the file.
|
|
|
|
Q. Softx86dbg is running and it found the COM file I want
|
|
to run. Now what?
|
|
|
|
Softx86dbg more or less follows the DOS DEBUG.COM style
|
|
interface. For each step, the values of the registers
|
|
are shown. Commands are parsed one line at a time and
|
|
each command is entered as one or more letters. The
|
|
commands are:
|
|
|
|
r [REGISTER] Change a register value
|
|
|
|
r Show the register contents
|
|
|
|
t Single-step (execute one instruction)
|
|
|
|
q Quit
|
|
|
|
d [[seg:]offset] Dump memory at given address. If no
|
|
address is given, ds:0x0000 is assumed.
|
|
If no segment value is given, the offset
|
|
is assumed to be within the current
|
|
data (DS) segment.
|
|
|
|
u [[seg:]offset] Unassemble (disassemble) instructions
|
|
at given address. If no address is given,
|
|
disassembly starts at the current location
|
|
of the instruction pointer (CS:IP). If
|
|
no segment value is given, the offset is
|
|
assumed to be within the current code
|
|
(CS) segment.
|
|
|
|
? print help.
|
|
|
|
Softx86dbg also recognizes commands that the original DOS DEBUG.COM
|
|
never had:
|
|
|
|
t [x] Single-step <x> times. In other words,
|
|
execute <x> instructions then return.
|
|
UPDATE: It turns out DEBUG.COM for Windows
|
|
XP has this feature after all
|
|
|
|
!reset Resets the virtual CPU.
|
|
|
|
!ramdump Dumps the virtual RAM to a file named
|
|
1MB_MEM.BIN
|
|
|
|
Q. What kind of environment does Softx86dbg emulate?
|
|
|
|
A. Softx86dbg emulates a very simple DOS-style environment. An INT 21h
|
|
interface is provided for the program to terminate by, and A simple
|
|
PSP structure is built for the program. Softx86dbg also demonstrates
|
|
the I/O port callback functions by emulating hypothetical hardware
|
|
that takes input and performs a simple calculation with it.
|
|
|
|
When the program terminates through INT 21h, softx86dbg prints a
|
|
notice on the screen indicating that the program terminated.
|
|
|
|
Q. How do I talk to the hypothetical hardware?
|
|
|
|
A. Currently (as of v0.00.0020) there are two I/O ports that the
|
|
hardware exists on.
|
|
|
|
Port 0x1234 is a simple register. Every time it is read, the value
|
|
is incremented by 0x22 or 0x2222 (depending on how much is read)
|
|
and then returned to the CPU. When written, the value is copied
|
|
verbatim to the register.
|
|
|
|
Port 0x9A is a byte-sized register. When written, the value is
|
|
incremented by 1 and then stored in the register. Then read,
|
|
the value of the register is returned as-is.
|
|
|
|
Since this can change in the future (not to mention conflicts with
|
|
actual PC hardware) do not rely on these I/O ports being emulated.
|
|
They are used only by samples/test04.com to test the I/O port
|
|
emulation of Softx86.
|
|
|
|
Q. I wrote a program that uses Softx86. How do I make it execute
|
|
instructions? Is there a call that starts a background thread?
|
|
|
|
A. Softx86 does not execute or decompile anything by itself. It expects
|
|
your program to execute instructions one at a time using
|
|
softx86_step().
|
|
|
|
Q. What is this "context structure" that every API function requires?
|
|
|
|
A. The context structure represents one CPU and it's current state.
|
|
All registers, modes, caches, and such are stored in that state.
|
|
The design favors this over the use of static variables so that
|
|
one copy of libsoftx86 can potentially emulate several CPUs at
|
|
once.
|
|
|
|
To "create" a CPU, allocate memory in your program for one
|
|
context structure and call softx86_init().
|
|
|
|
/* example of C code creating and initializing softx86 context structure */
|
|
softx86_ctx* cpu;
|
|
|
|
cpu = (softx86_ctx*)malloc(sizeof(softx86_ctx));
|
|
memset(cpu,0,sizeof(softx86_ctx)); /* recommended, not strictly necessary */
|
|
softx86_init(cpu);
|
|
|
|
/* example of C++ code creating and initializing softx86 context structure */
|
|
softx86_ctx* cpu;
|
|
|
|
cpu = new softx86_ctx;
|
|
memset(cpu,0,sizeof(softx86_ctx)); /* recommended, not strictly necessary */
|
|
softx86_init(cpu);
|
|
|
|
/* example of C++ code pushing softx86 to the extreme by creating 32 separate CPUs */
|
|
softx86_ctx* cpu;
|
|
int x;
|
|
|
|
cpu = new softx86_ctx[32];
|
|
memset(cpu,0,sizeof(softx86_ctx)*32); /* recommended, not strictly necessary */
|
|
for (x=0;x < 32;x++) /* 32 brains are better than one! */
|
|
softx86_init(&cpu[x]);
|
|
|
|
The Softx86 API functions require this context structure so
|
|
that they know what CPU to perform the operation on and so that
|
|
they have access to the CPU state. To execute an instruction
|
|
on cpu0 and decompile something on cpu1, for example, you would
|
|
write:
|
|
|
|
char cpu1_output[256];
|
|
softx86_step(&cpu0);
|
|
softx86_decompile(&cpu1,cpu1_output);
|
|
|
|
To delete a CPU and free the resources associated with it
|
|
(including caches stored in the context structure), pass
|
|
the context structure one last time to soft86_free().
|
|
Once it has been freed by softx86_free() you may free
|
|
the memory used by the context structure itself (or
|
|
do whatever you want to it).
|
|
|
|
/* example of C code freeing a CPU */
|
|
softx86_free(cpu);
|
|
free(cpu);
|
|
cpu=NULL;
|
|
|
|
/* example of C++ code freeing a CPU */
|
|
softx86_free(cpu);
|
|
delete cpu;
|
|
cpu=NULL;
|
|
|
|
/* example of hot-shot C++ code (above) freeing all 32 CPUs he created */
|
|
int x;
|
|
|
|
for (x=0;x < 32;x++)
|
|
softx86_free(&cpu[x]);
|
|
|
|
delete cpu;
|
|
cpu=NULL;
|
|
|
|
/* example of C code creating, freeing a CPU, then dancing on it's grave */
|
|
char *ptr;
|
|
softx86_ctx* cpu;
|
|
|
|
ptr = malloc(sizeof(softx86_ctx));
|
|
cpu = (softx86_ctx*)ptr;
|
|
softx86_init(cpu); /* create CPU */
|
|
softx86_step(cpu); /* execute something */
|
|
softx86_free(cpu); /* you've served your purpose now get outta here! */
|
|
strcpy(ptr, /* alright yeah! Now I can safely use the same area of memory */
|
|
"Blah Blah Yadda Yadda"); /* to store funny weird ASCIIZ strings! Whoo! */
|
|
free(ptr); /* but I have better things to do... */
|
|
|
|
Q. I get strange errors from make or Bash even though the scripts and Makefiles
|
|
look perfectly fine.
|
|
|
|
A. The install.sh script may have gotten munged with DOS-style CR LF line breaks.
|
|
This seems to happen when I pack the source code into a .tar.gz tarball then
|
|
copy the tarball to my Windows machine and unpack it using WinZIP or 7-Zip.
|
|
It doesn't immediately seem broken because Notepad and Wordpad show it perfectly,
|
|
but when the extracted files are tar and gzip'd and moved back to the Linux box
|
|
to be tested, the problems show up almost immediately. Bash expects to see
|
|
only LF line breaks, which is why it panics the way it does. GNU Make as far
|
|
as I know is generally tolerant of DOS CR/LF sequences so perhaps the
|
|
Makefile is corrupt in some way.
|
|
|
|
A quick fix can be done by changing to the directory containing Makefile and
|
|
install.sh and typing:
|
|
|
|
dos2unix install.sh; dos2unix Makefile
|
|
|
|
Bash shouldn't have any more problems.
|
|
NOTE: I've also found that WinZIP can't extract tar files properly if they
|
|
contain symlinks. 7-Zip does just fine.
|
|
|
|
Q. There are all these makefiles to make a static library and a DLL. There are
|
|
also two makefiles to produce the same program: Softx86dbg. What's the point?
|
|
why are you doing this?
|
|
|
|
A. Producing Softx86 as a static library AND a DLL allows software developers to
|
|
incorporate it into their programs in whatever flavor they like. Some people
|
|
especially those producting standalone programs, like statically linked
|
|
versions so that they don't have to deal with messy DLL dependencies or carry
|
|
extra luggage around with the main executable. Other developers, especially
|
|
those working on large projects, like modular designs so that DLLs and
|
|
resources can be loaded and unloaded dynamically (imagine a large project
|
|
that uses Softx86 as one of many emulation engines to simulate everything
|
|
ranging from a PC to a Z-80 to a Super-NES, for example). For these large
|
|
projects, Softx86 in DLL form is the best choice.
|