
 1. About
 
    This is a clone of the MS-DOS DEBUG command. Some minor things aren't
    implemented. OTOH it has many features not available in the original
    MS DEBUG. For details see below.


 2. Files Overview

    The files in this distribution are:

    debug.com     the executable binary.
    debugx.com    a DPMI aware version of debug.
    debug.asm     Assembler source code for DEBUG.  Assemble with nasm.
    debugtbl.inc  include file for debug.asm, generated by mktables
    instr.*       data files on the instruction set.
    mktables.c    C program to compile the internal instruction-set
                  tables into source file debugtbl.inc. It runs under
                  Linux or Turbo C (version 2.0, at least). 
                  Open Watcom v1.5 WCC works as well.
    readme.txt    this file.
    debug.txt     a DEBUG tutorial written by Michael Webster.
    SAMPLES       contains samples for 16 and 32-bit DPMI clients.


 3. Missing/Added Features
 
  a. The following are not implemented:

    - Loading of .HEX files.

  b. This debugger extends the MS-DOS version in the following ways:

   - You can do `r cx 1234' instead of having to put the `1234' on a
     separate line.

   - The assembler and disassembler support all publicly documented
     instructions for Intel chips through the Pentium Pro (P6), except for
     the MMX instructions.  The assembler and disassembler inform you if
     any instruction is inappropriate for the current processor.
    
   - FPU Opcodes are also supported. To specify size of memory operands
     use "FLOAT" or "DOUBLE". "REAL4", "REAL8", "DWORD" or "QWORD" won't be
     accepted in this context.

   - The current processor (for the purposes of assembler and disassembler
     warnings, above) can be declared to be something else via the following
     commands:

        m0  Declare current processor to be an 8088
        m1  Declare 80186
        m2  Declare 286
        m3  Declare 386
        m4  Declare 486
        m5  Declare Pentium
        m6  Declare Pentium Pro
        mc  Declare the existence of a math coprocessor
        mnc Declare the absence of a math coprocessor
        mc2 Declare that the math coprocessor is a 287 (only valid
            if the current processor is a 386)
        m?  Print currently declared processor type

   - When doing `debug < file', debug will not hang if it reaches an end of
     file before encountering a `q' command.

   - This debugger saves and restores the program's Control-C and critical
     error interrupts, providing for better isolation between the debugger
     and the program being debugged.

   - 'r register [value]' accepts 32-bit register names (for cpu 80386+).
   - 'rn' displays FPU register status (currently for cpu 80386+ only).
   - 'rx' switches among 8086 and 80386 register display (for cpu 80386+).
   
   - 'tm 0|1' sets trace command mode, 0 = process INTs (default),
     1 = single-step INTs (the MS-DOS debug compatible mode).
        
   - 'xr' allows to reallocate an EMS handle and 'xa' allows to allocate
     an "empty" EMS handle (with zero pages) - but only if an EMM v4.0
     is present.  
   - Besides 'i' and 'o' exist the variations 'iw', 'id', 'ow' and 'od'
     to read/write a WORD or DWORD value from/to a port. DWORD values
     require a 80386+ cpu.

   - 'h' can handle dword values.

   - A DPMI aware version of the debugger, DEBUGX, is available. It can
     debug real-mode applications and both 16-bit and 32-bit DPMI clients.
     To debug DPMI clients a DPMI host has to be installed *before* the
     debugger is launched, it won't work if the application to debug
     installs its own host during the debug process. Tested with cwsdpmi,
     hdpmi, WinXP NTVDM, 32rtm. In DosEmu and Windows 95/98/ME DOS boxes 
     it is required to single-step through the initial switch to
     protected-mode, else DEBUGX will loose control of the debuggee.

   - DEBUGX additionally understands the following commands:
     'dl': display LDT descriptor (protected-mode only)
     'di': display interrupt vector
     'dx': display extended memory (read via Int 15h, ah=87h). Requires
           a 80386 cpu.
   
   - register names can be used anywhere where a number is expected as
     input. That is, things like "u cs:ip" do work.

   - 'dm' displays the DOS memory control block (MCB) chain.

   - if DOS has set its InDOS flag, DEBUG will avoid to use int 21h 
     internally, which allows to single-step through DOS code.
     
   - 'd', 'dx', 't' and 'u' are automatically repeated if a blank line is
     entered.


 4. History

    0.95e [11 January 2003]  Fixed a bug in the assember.
    0.95f [10 September 2003]  Converted to NASM; fixed some syntax
        incompatibilities.
    0.98 [27 October 2003]  Added EMS commands and copyright conditions.

    0.99 [27 Septemb 2006]  bugfix: IF was not displayed correctly.
        FS and GS registers displayed if cpu is 80386+. 'rx' displays the 
        standard 32bit registers. R register [value] understands the
        standard 32bit registers.
    0.99a [28 Septemb 2006] bugfix: JECXZ had wrong prefix (66h,
        should be 67h). Assembler/Disassembler understand LOOP(Z|NZ|E|NE)D.
    0.99b [29 Septemb 2006] 'l' and 'w' now work with FAT32 drives.
    0.99c [29 Septemb 2006] 'rx' now switches among 16/32 bit register
        dump. 'rn' displays floating point register status.
    0.99d [02 October 2006] bugfix: 'rn' displayed error-pointer 
        registers wrong. 
    0.99e [12 October 2006] 'xr' command added to reallocate EMS handle.
        'xa' command allows to allocate zero pages on EMS 4.0. 'tm 0|1' added
        to be able to switch 't' to the ms-dos debug compatible behaviour
        (that is, 't' jumps into 'INT xx').
    0.99f [17 October 2006] debug's EMS functions may work even with a  
        "hidden" EMM. bugfix: display of mappable pages didn't account for
        amount of these pages == 0.
    0.99g [25 October 2006] bugfix: 'u' was unable to recognise [ESP]
        related memory operands (i.e. mov eax,[esp]).
    0.99h [07 November 2006] bugfix: 'r' trying to display content of
        effective address has caused a GPF in v86-mode if this address
        was FFFFh of FFFDh. 'iw', 'id', 'ow' and 'od' implemented.
    0.99i [14 November 2006] bugfix: a child PSP was created but not
        terminated, causing files not to be closed. It became obvious if
        stdin and/or stdout were redirected to files ("C:\>DEBUG >yyy")
    0.99j [16 November 2006] bugfix: using 't' if current instruction is
        an INT xx (and trace mode == 0) stopped debuggee one instruction
        *after* the INT (due to a x86 design weakness). bugfix: the 0.99i
        bugfix had some problems on FreeDOS.
    1.00 [25 November 2006] bugfix: debuggee's psp was saved after
        program load only, but this has to be done every time the debugger
        regains control. There is now a DPMI aware version of debug, DEBUGX,
        createable from the source. bugfix in disassembler: RETF did not 
        have a corresponding RETFD entry (to switch with prefix 66h)
    1.01 [26 November 2006] bugfix: MC2 didn't work. Register names
        can be used anywhere where a number is expected as input.
    1.02 [29 November 2006] bugfix: 'i d' and 'o d' didn't work because
        the parser assumed 'id' and 'od' commands.  bugfix: 't=' and 'g='
        didn't work in protected-mode. bugfix: loading a file at another
        location than cs:100h was not supported in versions 0.99 - 1.01.
        Debugger can be loaded high.
    1.03 [1 February 2007] bugfix: previous version of DEBUG.COM did not
        reliably reset "auto-reset" breakpoints (used for processing INTs).
        DEBUGX.COM was not affected by this bug. 'di' now works in real-mode
        as well. 'dm' command added.
    1.04 [2 March 2007] making single-step through the DOS kernel possible.
    1.05 [1 April 2007] program exit code displayed. 'dm' displays the
        PSP "name". 'dx' added. autorepeat for 'd', 'dx', 't' and 'u'.
    1.06 [21 May 2007] bugfix: SMSW didn't accept a 32bit operand.
        bugfix: OW/OD didn't accept the value parameter. '-' supported in
        'e' command.
    1.07 [3 November 2007] bugfix: entering ranges with upper bound was
        refused. bugfix: if help cmd waited for a keypress, it displayed
        garbage if cpu was in protected-mode and CWSDPMI was used.
        Tracing into an INT (TM 1) now works if interrupt vector points
        to ROM code.
    1.08 [23 November 2007] bugfix: segment prefix was lost for mnemonics
        without arguments (patch by Oleg O. Chukaev).
    1.09 [30 December 2007] several bugfixes for A and U handling 32bit
        code segments. bugfix: U split lines if instruction size exceeded 6.
        bugfix: M didn't work with "upper bound" ranges. change: in 32bit
        code segments, U displayed ECX as first operand for LOOPx to 
        indicate that ECX is used instead of CX. Now a 'D' is attached to
        the opcode (LOOPxD, x=Z|NZ|E|NE) instead. bugfix: A didn't choose
        the short (=signed) form of arith instructions (adc, add, ...) 
        if E/AX was first operand.


 5. Copyright
 
    This program is copyrighted, but feel free to distribute and use it
    as you wish.  For full copyright conditions, see the file debug.asm.

    Paul Vojta
    vojta@math.berkeley.edu

