April 21, 2005, Terry Loveall <loveall@iinet.com>

Linux debug is released under the terms of the GNU General
Public License version 2 (see LICENSE).

Thanks Patrick. ALD is a beautiful baseline POSIX debugger.

My thanks to Jeff Owen <http://sourceforge.net/projects/asmedit>
for his help in tracking down the glitches that always show up
in a new project.

If you are looking for the latest and greatest version of ALD,
debug aint it. This is a _simple_ interface with the addition
of some symbolic references in a single line assembler and the
unassembler. For the latest real version of ALD see:
<http://ald.sourceforge.net/>

Linux debug was developed using gcc-2.95.3 and Autoconf version 2.13.
It has compiled successfully on debian Xandros with gcc-3.3.2.

!!NOTE!!
Linux debug is a _simple_ _debugger_.

For the 's(tep) over' function, a 'halt' (int 3) is 
placed _after_ the current instruction.

If you have inline data stored after a 'call',
which accesses the return address for the data,
the 'halt' instruction will replace the inline data,
possibly causing a GPF. 

This is only a concern in pure assembly language
programs. Most 'C' programs do not inline data.

Getting started:

 ./configure
 make
 make install

Background:

My purpose in putting debug together was to create a 
functional equivalent to the old DOS debug.com with builtin 
disassembler/single line assembler.

At the same time I needed a simpler interface to the break 
point and step/trace functions. The original syntax of ALD
has been changed to more closely match that of DOS debug. Use
'?' or 'help' for the proper syntax.

Debug will recognize symbol addresses as listed in a debug
header. To be recognized, the symbol must show up in a 'file
symbols' listing. And of course, if you have no debug symbols
in the  header, you will have no symbols, period.

To lookup a symbol, copy the symbol with the mouse and paste
it into a debug command line. e.g. to lookup '_start" use:
debug> d -l 1 _start
This will generate the address of '_start' and display the
first byte at that address. 

Alternatively, you can just type in the symbol.

The u, d and a commands now accept a valid symbol or register
contents as a starting address. e.g. 'u eip' or 'a _start'.

The single line assembler is a rough fit of portions of NASM
0.98.33 into debug. The code used to find symbols from addresses
and addresses from symbols has enabled symbol use in the single 
line assembler.

Use the debug command:
'file symbols'
to list the addresses/values of symbols. 

Use the  mouse to copy/paste into the assembler. 

The write command (which was used to dump the contents of the
non-functional curses windows) has been changed to write an
image of the executable back to disk. A filename is required.
Syntax: 'w <filename>' or 'write <filename>'.

NOTE: you have to manually 'chmod +x <filename>' before the
saved image will work. If you write an image of a debug symbol
loaded file, the debug symbols are removed.

For further info see the man page doc/debug.8. 

Before installation use the command:
'man doc/debug.8'
After installation use the command:
'man 8 debug' or
'man debug' if you only have one debug in your man files.

And, yes, I know about the warnings in the nasm code. They are
the same warnings that a formal build of nasm-0.98.33
generates. Feel free to send me fixes for them.

NOTE:
This is an assembly level debugger. It behooves _you_ to
understand machine language programming. Read all of
the documentation: this file, the help screens,
doc/debug.8 and the source. Use the 'help' command.
WHEN ALL ELSE FAILS, READ THE SCREEN.

Please send detailed bug reports, fixes or improvements to
<loveall@iinet.com>

Original README
-----------------------------------------------------------
 "Congress shall make no law ... abridging the right of the
  people peaceably to assemble."

          -- First Ammendment to the Constitution of the U.S.

 Hopefully the above statement works for disassembly as well :-).

 All code in ald was coded by myself, Patrick Alken, unless
otherwise mentioned in the code/credits.
 I am releasing this software under the terms of the GNU General
Public License (see LICENSE). Should you choose to use and/or
modify my source code in any way, please do so under the terms
of this license, published by the Free Software Foundation.

 The Assembly Language Debugger is a tool for debugging programs
at the instruction level. It was born out of my frustration
with gdb's ability (or lack thereof) to debug assembly language
programs. I have tried to include as many useful features as
I could think of into ald, but I am very open to suggestions for
improvement. If you have a feature request or suggestion, please
do not hesitate to email me.

DISTRIBUTION

  There is a webpage for ald at: http://ald.sourceforge.net/
You may download the latest ald release there.

INSTALLATION

  Read the INSTALL file.

BUGS

 PLEASE email me any bugs you find. I cannot fix bugs if no one
reports them!! If you submit a bug, please supply as much
information as you can - if you can reproduce the bug at will,
please write down the steps you took.

LEGAL STUFF

 There is absolutely NO WARRANTY for this package. The author
will accept no responsibility, whatsoever, for any damage caused
by this program.

Enjoy, and happy assembling!

Patrick Alken <cosine@ellipse.mcs.drexel.edu>
