README for the plex86 ICE plugin
Ramon van Handel <vhandel@chem.vu.nl>

Introduction:

The ICE plugin is a debugger for use with plex86.  It is especially useful
for debugging a guest operating system, hence the name ICE: a "real" ICE
is an In-Circuit Emulator, a hardware debugger that is directly connected
to the CPU.  This code aims to provide similar functionality as the ICE for
the virtual environment.

The ICE plugin does not itself implement the debugger frontend; rather, it
is fashioned in such a way that it can interface with standard GDB over a
TCP/IP connection.  Thus, the guest code is debugged directly with GDB.
The code was modified from the GDBserver program by Stu Grossman and Fred
Fish, that is distributed with the GDB source distribution, which is
available from ftp at prep.ai.mit.edu.  The GDBserver program was slightly
modified to make it suitable for use with plex86; the main change was,
though, the addition of a low-plex86.c file that intefaces with the
guest running in the VM, which replaces low-linux.c which uses ptrace()
to control a child process to be debugged.

Usage (server (target) side):

In order to use the ICE plugin, add the following line to your plex86.conf
file:

	plugin = <location>/plugin-ice.so 3141

3141 is the TCP/IP port number to use (change this if a different port
suits better).  Now start up a VM with the guest code to be debugged.
plex86 starts up, and then prompts you to start up a remote GDB
connection.

Usage (host side):

You need an unstripped copy of the target program on your host system, since
GDB needs to examine it's symbol tables and such.  Start up GDB as you normally
would, with the target program as the first argument. After that, the only
new command you need to know about is `target remote'.  It's argument is a
HOST:PORT descriptor.  For example:

	(gdb) target remote localhost:3141

Note that you must start up the ICE plugin prior to using the `target remote'
command, otherwise you may get an error that looks something like `Connection
refused'.
