;=============================================================================
; DOS debug utility for intel i386,i486 and Pentium Processor
;
; copyright(c)1993-2001 takeshi kataoka. / email kata@who.net
;=============================================================================

 1. About this program
 2. Introduction 
 3. System requirements 
 4. The differences between symdeb.exe
 5. Command reference
 6. The restriction of MS-DOS debugger.
 7. References
 8. From the programmer.

;=============================================================================
; 1. About this program
;=============================================================================

   License agreement 

(1)This program is a freeware, but is copyrighted software.
(2)The author does not guarantee the damages at all.
(3)Support and range of support. Please email me.
(4)About the redistribution 
   You have to distribute with the compression file.

   Please send e-mail to  kata@who.net.

;=============================================================================
; 2. Introduction
;=============================================================================

This software is MS-DOS debugger just like SYMDEB.EXE which supports 386 
instructions.  The reason why I made this software is SYMDEB.EXE(Microsoft 
provided before) does not support 386 instructions.

;=============================================================================
; 3. System requirements.
;=============================================================================

Operating system requires above DOS 3.3 or later.
Processor requires above intel i386 or compatible processor.

;=============================================================================
; 4. The differences between symdeb.exe(version 3.01).
;=============================================================================

* Restrictions.

1) Cannot debug with source code (*.asm and *.c). 
2) There are some no-supported commands and some incompatible commands.
3) Requires i386 or higher.
4) Multi statement command is not supported.
5) It does not support the feature of symdeb.exe which PC/AT hardware related.

* Improvement

1) Supports i386,i486,Pentium processor instructions.
2) Supports address range from 0000h to ffffh.
3) When it uses debug register, it can break by memory access, or ROM code.
4) I/O port command can access 32bit.
5) Supports writing .hex file.
6) Program size is smaller than symdeb.exe.
7) Relocates symbol information.
   It really convenient, when you debug TSR program.
8) It can break by I/O Port access.(Pentium & Realmode Only)
9) You can dump memory with 32bit address.

* Others

It supports "sym" files that was made by mapsym.exe version3.10.
but there are some restrictions.

1) When you use single line assembler, you cannot use symbol as address.
2) The "Abs" definition in the Map file is not supported.
3) Supporting file size is less than 64k bytes.
4) The capital letter and small letter are not distinguished in symbol.

;=============================================================================
; 5. Command reference.
;=============================================================================
When you launch ddeb.exe ,then prompt character is displayed as follows

DOS Debugger for i386 1.16c copyright 1993-2001 takeshi.kataoka / kata@who.net
_

if you want to return DOS, type Q and hit "Enter" key.

Please refer belows.

;-----------------------------------------------------------------------------
; A : assembler
;-----------------------------------------------------------------------------
This is single line assembler, it supports i386,i486,Pentium instruction.

Form> a (address)

Example: 

_a 2345:0100
2345:0100 mov eax,1

;-----------------------------------------------------------------------------
; BC : clears breakpoint(s)
;-----------------------------------------------------------------------------
It clears the breakpoint.

Form> bc (breakpoint number)

Example:

_bc 1
_bc r0
_bc *

;-----------------------------------------------------------------------------
; BD :disable breakpoint
;-----------------------------------------------------------------------------
Disables breakpoint temporarily.

Form> bd (breakpoint number)

Example:

_bd 5
_bd r3

;-----------------------------------------------------------------------------
; BE :enable breakpoint
;-----------------------------------------------------------------------------
Enables breakpoint.

Form> be (breakpoint number)

Example:
_be 5
_be r3

;-----------------------------------------------------------------------------
; BL :shows breakpoint list
;-----------------------------------------------------------------------------
Shows the list of all breakpoints.

Form> bl

Example:
_bl

;-----------------------------------------------------------------------------
; BP :breakpoint setting
;-----------------------------------------------------------------------------
Sets up a breakpoint of you entered.

Form> bp <number> <address>

Example:

_bp 2345:1234

;-----------------------------------------------------------------------------
; BR :breakpoint setting using Debug Register
;-----------------------------------------------------------------------------
i386 processor has 4 debug register, it uses these register for debug.
You can break on ROM code, or when memory or port access happened.

Form> br <number> <address> <conditions>

Example:

_br xxxx:1234 e                  : executing code.
_br xxxx:1234 w2                 : accessing memory
_br 300 p4                       : accessing a port

;-----------------------------------------------------------------------------
; C : compares memory
;-----------------------------------------------------------------------------
Compares different memory address.

Form> c <source address> <offset> <destination address>

Example:
_c 8000:0 ffff 9000:0

;-----------------------------------------------------------------------------
; D : dump memory
;-----------------------------------------------------------------------------
It show memory with hexadecimal code(byte/word/double word).

Form> d<size>  <address> <offset>

Example:
_dw 9000:0 ffff                   :it show from 9000:0 to 9000:ffff

Speial feature:
It shows memory over 1MB address.(you can use this under the realmode DOS)

Example:
_dw #1000000

;-----------------------------------------------------------------------------
; E : edit memory
;-----------------------------------------------------------------------------
You can change the data of memory using this command.

Form> e<size> <address> <list>

Example:
_ew 9000:0
9000:0000 xxxx.                   : enter new value and hit Enter key.

;-----------------------------------------------------------------------------
; F :fill memory
;-----------------------------------------------------------------------------
When you fill memory with a pattern data, please use this command.

Form> f <address> <offset> <list>

Example:
_f 9000:0 6000 ff                 : it fills memory from 9000:0 to 9000:6000 with "ff"

;-----------------------------------------------------------------------------
; G :starts or re-starts the program
;-----------------------------------------------------------------------------
You can start the program from anywhere you want.

From> g =<start address> <finish address>

Example:
_g=100
_g 200

;-----------------------------------------------------------------------------
; I :inputs a port
;-----------------------------------------------------------------------------
It reads data from a port.(byte/word/double word)

Form> i<size>  <port address>

Example:
_id 30                            : it means reading dword data from 0x30
xxxxxxxx

_iw 20
xxxx

_ib 10
xx

;-----------------------------------------------------------------------------
; L :load a file 
;-----------------------------------------------------------------------------
It loads a file which you entered the name of the file with N command.
After loading, ECX register will show the file size.
It cannot re-load executable file.

From> l <address>

Example:
_l 9000:0                         : loads file to 9000:0

;-----------------------------------------------------------------------------
; M :copy memory data
;-----------------------------------------------------------------------------
It copies the memory image to different address.

Form> m <source address> <end offset> <destination address>

Example:
_m 9000:0 ffff a000:0            : it means copying 64kbytes data 
                                      from 9000:0 to a000:0

;-----------------------------------------------------------------------------
; N :file name setting
;-----------------------------------------------------------------------------
Enter a file name for L or W command.

Form> n <file name>

Example:
_n test.dat

_n
a:\tool\ddeb.exe

When you didn't enter a name, it shows the current name.

;-----------------------------------------------------------------------------
; O :output port
;-----------------------------------------------------------------------------
Writes data to a port. the size is byte/word/double word.

Form> o<size> <port address> <value>
 
Example:
_ow 30 1234

_od 20 12345678

_ob 10 ab

;-----------------------------------------------------------------------------
; P : single step execute
;-----------------------------------------------------------------------------
Executes only one instruction including CALL,LOOP....

Form> p <count>

Example:

_p 10


;-----------------------------------------------------------------------------
; Q : quit
;-----------------------------------------------------------------------------
Quit the program and return to DOS.

From> q

;-----------------------------------------------------------------------------
; R : show or edit register(s)
;-----------------------------------------------------------------------------
It show the values of registers like below.

eax00000000 ebx00000000 ecx00000000 edx00000000 esi00000000 edi00000000
ds2181 es2181 fs2181 gs2181 ss2181 spF000 ebp00000000 nv up ei pl nz na po nc
2181:0100 1010            adc     [bx+si],dl

Form> r <register name> <value>

Example:

_r ah ac

;-----------------------------------------------------------------------------
; S : searching
;-----------------------------------------------------------------------------
You can search a data from memory using thie command.

From> s <starting address> <end offset> <data>

Example:
_s 9000:0 ffff 'test'

_s 8000:0 100 0 1 2 3 


;-----------------------------------------------------------------------------
; T : trace
;-----------------------------------------------------------------------------
Executes only one instruction.

Form> t <count>

Example:
_t 10

;-----------------------------------------------------------------------------
; U :disassemble
;-----------------------------------------------------------------------------
Disassembles memory data.

Form> u <start address> <end offset>

Example:
_u 9000:0 ffff

[Extra feature]

_uw <address>   16bit disassemble

_ud <address>   32bit disassemble

Example:

_ud 24ad:0
24AD:~0000 FC              cld     
24AD:~0001 B809258EC0      mov     eax,C08E2509
24AD:~0006 BE8000AC3C      mov     esi,3CAC0080
24AD:~000B 007471E8        add     [ecx+esi*2-18],dh
24AD:~000F A101BF4908      mov     eax,[0849BF01]
24AD:~0014 AC              lodsb   
24AD:~0015 3C20            cmp     al,20
24AD:~0017 7203            jb      0000001C

;-----------------------------------------------------------------------------
; W : writes data to a file
;-----------------------------------------------------------------------------
When you save memory image into a file, please put the size into ECX register.
Also you need to put file name using N command before you do. 

Form> w <address>

Example:
_w 9000:0

;-----------------------------------------------------------------------------
; Y :re-locates symbol information.
;-----------------------------------------------------------------------------
 Relocates symbol information.
 It really convenient, when you debug TSR program.

Form> Y <segment>

Example:
_y 1234

;-----------------------------------------------------------------------------
; ? : command help, calculator
;-----------------------------------------------------------------------------
When you don't enter a parameter, it shows command reference.

Form> ?

Example:

<Hexadecimal calculating>
_? 2F*4
000000BCh (188) [00000000.00000000.00000000.10111100] ....

<Decimal calculating>
_?? 123*45
0000159Fh (5535) [00000000.00000000.00010101.10011111] ....

;-----------------------------------------------------------------------------
; I :shell execute
;-----------------------------------------------------------------------------
Execute "command.com"

Form> ! <command>

Example:
_!dir/w

;-----------------------------------------------------------------------------
; < :input command from file or device
;-----------------------------------------------------------------------------
Changes STD input to file or device.

Form> < <file or device>

Example:
_<test.txt

Note:You need to append "=CON" and of the file.
     If you didn't do that, you cannot continue operate.

;-----------------------------------------------------------------------------
; > : output command to file or device
;-----------------------------------------------------------------------------
Changes STD output to file or device.

Form> > <file or device>

Example:
_>out.txt

;-----------------------------------------------------------------------------
; = :input and output file or device
;-----------------------------------------------------------------------------
Changes STD input and output to file or device.

Form> = <file or device>

Example:
_=COM1

_=AUX1

Note: Usually this command is for debugging with RS-232C cable.

;=============================================================================
; 6. The restriction of MS-DOS debugger.
;=============================================================================
MS-DOS debugger cannot trace into INT21h, because it use INT21h for input key
and display strings. If you put a breakpoint in DOS kernel(INT21h),it will 
cause trouble, I think.

When the control move from the application to the debugger, it uses 6 bytes of 
application's stack. Because it saves CS,IP and Flag registers, when the 
interrupt happened.

;=============================================================================
; 7. References
;=============================================================================
1)386DX microprocessor programmers reference manual(second edition)
  (intel Japan)
2)i486DX microprocessor programmers reference manual.
  (intel Japan)
3)DOS PROGRAMMER'S REFERENCE 4TH EDITION (QUE)
4)THE UNDOCUMENTED PC.(ADDISON WESLEY)
5)Pentium processor architecture and programming[241430J-001](intel Japan)
6)Thoroughness understanding of Pentium architecture
   (interface '93/11 appendices CQ publication)

;=============================================================================
; 8. From the auther.
;=============================================================================
Hello Sir or Madam.

I've been studying English for 4 years. and I've been a programmer for 13 years.
I used to use MS-DOS,Windows3.x/95/98/Me/NT3.5/NT4, now I use Windows 2000.
I used to develop some VxD of Windows3.x and Windows9x, and sys of WindowsNT.
Of course, reacently I use visual C++ to make win32 applications.
I like Win32 application than MFC application. Now I want to make Win32 debugger
But I don't have enough time to make it. I'm quite busy recently.

I like using English, especially having conversation with foreign people.
So if you feel something about this program, and also if you noticed unappropriate
sentence, please let me know. I will appreciate your kindness.

takeshi kataoka from Osaka, Japan.

e-mail:kata@who.net
       tkata@dc5.so-net.ne.jp
       tkataoka@bha.co.jp


