README file for DOSEMU debugger   PRELIMINARY	8/1/95
send comments to Max Parke     <mhp@light.lightlink.com>
================================================================

This is a preliminary release of the DOSEMU debugger, with the
following features:
* interactive
* display/disassembly/modify of registers and memory(0-1Mb)
* breakpoints (int3-style, and breakpoint on INT xx)
* symbolic debugging via microsoft linker .MAP file support
* read-only access to DOSEMU kernel via memory dump and disassembly
* uses /usr/src/dosemu/dosemu.map for above
* access is via telnet from another virtual console.  So, you have
  a "debug window" and the DOS window/keyboard, etc. are
  undisturbed.	VM86 execution can be started, stopped, etc.
* code base is on DOSEMU 0.60.1

I'm putting it out here to get comments and feedback!

================================================================
Hooks were added to these modules in the source tree:
./emu.c
./dosemu/sigsegv.c
./emumod/vm86.c
(I could not get diff to work, for some reason I *think* I messed up
the tabstops in the files.  The sources are based on DOSEMU 0.60.1 and
Linux Kernel version 1.2.8 was used.)

New modules:
./dosemu/mhpdbg.c
./dosemu/mhpdbgc.c
./dosemu/dis8086.c
./include/mhpdbg.h
================================================================
INSTALLATION:(I am very poor at Makefiles, so I didn't try to include
one)

1) replace modules emu.c, sigsegv.c, and vm86.c in the subdirectories
   as shown above.
2) Add the new modules mhpdbg.c, mhpdbgc.c, and dis8086.c to the
   ./dosemu subdirectory.
3) Add mhpdbg.h to the ./include directory.
4) Change your makefile to add mhpdbg.c mhpdbgc.c and dis8086.c to
   the make for the libdosemu.a portion.
   NOTE: mhpdbg.c and mhpdbgc.c must be compiled with a
   -DMHP_PRIVATE option.
5) run the make.  If OK the hardest part is behind.

================================================================
USAGE
To run, start up DOSEMU.  Then switch to another virtual console
and do:
telnet <your-host-name> 3456
(or)
telnet 127.0.0.1 3456
You should get connected and a banner message
It is not necessary to be running inetd to do this.

================================================================
COMMANDS (see mhpdbgc.c for code and cmd table)

(all numeric args in hex)

r		  list regs
e ADDR HEXSTR     modify memory (0-1Mb)
d ADDR SIZE	  dump memory (no limit)
u ADDR SIZE	  unassemble memory (no limit)
g		  go (if stopped)
stop		  stop (if running)
mode 0|1	  set mode (0=SEG16, 1=LIN32) for u and d commands
t		  single step (not fully debugged!!!)
r32		  dump regs in 32 bit format
bp addr 	  set int3 style breakpoint
bpint xx	  set breakpoint on INT xx
bcint xx	  clr breakpoint on INT xx
(rmapfile)	  (internal command to read /usr/src/dosemu/dosemu.map
		  at startup time)
rusermap org fn   read microsoft linker format .MAP file "fn"
		  code origin = "org".
		  for example if your code is at 1234:0, org would
		  be 12340.
Addresses may be specified as:
1) a linear address.  Allows 'd' and 'u' commands to look at both
   DOSEMU kernel and DOS box memory (0-1Mb).
2) a seg:off address (0-1Mb)
3) a symbolic address.	usermap is searched first, then dosemu map.
4) an asterisk(*): CS:IP
5) a dollar sign($): SS:SP

================================================================
PERFORMANCE

You do not absolutely *have* to make the emumodule changes, but then
the breakpoint portions of the debugger would stop working.

However if you do install them, then all INTxx's are now being
bounced back to 32-bit mode, not just the ones the kernel doesn't
want itself.  I don't know what performance hit this has, but there
must be some.

Also it calls a poll routine each pass thru the vm86 dispatch
loop in emu.c, don't know how bad that kills it, either...

================================================================
WISH LIST

Main wish is to add support for hardware debug registers (if someone
would point me in the direction, what syscalls to use, etc.)
Then you could breakpoint on memory reads/writes, etc!

================================================================
BUGS

There must be some.

================================================================
send comments to Max Parke     <mhp@light.lightlink.com>
