README
vAVRdisasm - Version 1.9 - 04/03/2011
Vanya A. Sergeev - <vsergeev@gmail.com>
================================================================================
Table of Contents

1. ABOUT vAVRdisasm
2. LICENSE
3. COMPILING vAVRdisasm
4. USING vAVRdisasm
5. Ghetto Address Labels
6. Shortcomings
7. Source Code
8. Sample Disassembly Outputs  
================================================================================

1. ABOUT vAVRdisasm
================================================================================
vAVRdisasm is an Atmel 8-bit AVR firmware disassembler. This single-pass
disassembler can read Atmel Generic, Intel HEX8, and Motorola S-Record formatted
files containing valid AVR program binaries.

It supports all 142 8-bit AVR instructions as defined by the Atmel AVR
Instruction Set, revision 0856I-AVR-07/10.

vAVRdisasm features a handful of formatting options, including:
 - Printing the instruction address alongside disassembly, enabled by default
 - Printing the destination address of relative branch/jump/call instructions
   as comments alongside disassembly, enabled by default
 - Printing the original opcode data alongside disassembly
 - Ghetto Address Labels (see "Ghetto Address Labels" section)
 - Formatting data constants in different bases (hexadecimal, binary, decimal)
 - .DW data word directive for data not recognized as an instruction during
   disassembly. 
 - Piped input and output

vAVRdisasm should work on most *nix platforms, including a Cygwin or MinGW
environment. vAVRdisasm was written by Vanya A. Sergeev, and tested with the
GNU C Compiler on Linux. Feel free to send any ideas or suggestions to vsergeev
at gmail dot com.

2. LICENSE
================================================================================
vAVRdisasm is released under the GNU General Public License Version 2.
    You should have received a copy of the GNU General Public License
    along with this program; see the file "COPYING".  If not, visit
    http://www.gnu.org or write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

3. COMPILING vAVRdisasm
================================================================================
Simply running,
$ make
 in the vAVRdisasm project directory should compile vAVRdisasm on most
*nix systems, including a Cygwin or MinGW environment. The Makefile is
configured to use GCC to compile vAVRdisasm.

vAVRdisasm should have no problem being compiled with "gmake".

4. USING vAVRdisasm
================================================================================

* File Input:
	For most purposes:
	 $ ./vavrdisasm <AVR program file>
	Example:
	 $ ./vavrdisasm sampleprogram.hex

	Use - for standard input.

* Option -t or --file-type
	vAVRdisasm will auto-recognize Atmel Generic, Intel HEX8, and Motorola 
	S-Record files by their first character. However, the -t or --file-type
	option can be used to explicitly select the file format.
	Example:
	 $ ./vavrdisasm -t generic sampleprogram

	The file type argument for this option can be "generic", "ihex", or 
	"srecord" for Atmel Generic, Intel HEX8, or Motorola S-Record formatted 
	files, respectively.

* Option -o or --out-file <output file>
	Specify an output file for writing instead of the standard output. The
	output file - is also synonymous for standard output.

* Option --original
	Print the original opcode data to the left of the disassembly.
	Note: this option is ignored if address labels are enabled (to ensure
	assemble-able code).

* Options --data-base-hex, --data-base-bin, --data-base-dec
	vAVRdisasm will default to formatting data constants in hexadecimal.
	However, data constants can be represented in a different base with one
	of the following options: --data-base-hex, --data-base-bin, and
	--data-base-dec.

* Options --no-addresses, --no-destination-comments.
	By default, vAVRdisasm will print the instruction addresses alongside 
	disassembly and destination comments for relative branch, jump, and call
	instructions. These formatting options can be disabled with the 
	--no-addresses and --no-destination-comments options.

* Option -l or --address-label	
	See the "Ghetto Address Labels" section.

* Options -h or --help, -v or --version
	The -h or --help option will print a brief usage summary, including 
	supported program options and file types.
	The -v or --version option will print the program's version number.

If you encounter any program bugs or problems, please notify the program
author by email: Vanya A. Sergeev - vsergeev at gmail dot com.

5. Ghetto Address Labels
================================================================================
vAVRdisasm supports a unique formatting feature: Ghetto Address Labels, which 
few, if not any, single-pass disassemblers implement.

With the -l or --address-label option and a supplied prefix, vAVRdisasm
will print a label containing the ideally non-numerical supplied prefix 
and the address of the disassembled instruction at every instruction. Also, 
all relative branch, jump, and call instructions will be formatted to jump
to their designated address label.

This feature enables direct re-assembly of the vAVRdisasm's disassembly.
This can be especially useful a for quick modification to the AVR program
assembly code without having to manually format the disassembly or adjust the
relative branch, jump, and call distances with every modification to the
disassembly.

The -l or --address-label option overrides the default printing of the
addresses alongside disassembly. Destination comments can still be printed.

Example:
$ ./vavrdisasm -l "A_" sampleprogram.hex
vAVRdisasm's disassembly will include address labels that will look like this:
A_0000:

For sample disassembly outputs by vAVRdisasm, see the "Sample Disassembly
Outputs" section.

6. Shortcomings
================================================================================
vAVRdisasm does not disassemble and display alternate versions of the same
encoded instruction (i.e. showing "eor" in additon to "clr"). This technically
means that the "cbr" instruction can never be displayed in the disassembly 
because the "andi" instruction precedes it in priority.

These features do not affect the accuracy of the disassembler's output, and 
may be supported in future versions of vAVRdisasm.

7. Source Code
================================================================================
vAVRdisasm's source code is heavily commented, because this disassembler was
also a personal learning project of the author.

Operand prefixes (such as "R" for register operands or "$" for data operands)
can be customized in the format.h header file. 

Field width spacing of the addresses printed alongside disassembly, and the
destination relative address comments can be customized in the ui.c
source file.

vAVRdisasm uses libGIS, a free Atmel Generic, Intel HEX, and Motorola S-Record
Parser library to parse formatted files containing AVR program binaries. libGIS
is available for free under both MIT and Public Domain licenses at:
http://dev.frozeneskimo.com/software_projects/libgis
libGIS is compiled into vAVRdisasm--it does not need to be obtained separately. 

8. Sample Disassembly Outputs
================================================================================
These output samples, produced by vAVRdisasm, are a disassembly of the program 
from the "Novice's Guide to AVR Development" article in the Atmel Applications
Journal.

$ ./vavrdisasm sampleprogram.hex 
   0:   rjmp .0         ; 0x2
   2:   ser R16
   4:   out $17, R16
   6:   out $18, R16
   8:   dec R16
   A:   rjmp .-6        ; 0x6

$ ./vavrdisasm --original sampleprogram.hex
   0:	C0 00		rjmp .0 	; 0x2
   2:	EF 0F		ser R16
   4:	BB 07		out $17, R16
   6:	BB 08		out $18, R16
   8:	95 0A		dec R16
   A:	CF FD		rjmp .-6 	; 0x6

$ ./vavrdisasm --no-destination-comments sampleprogram.hex
   0:   rjmp .0
   2:   ser R16
   4:   out $17, R16
   6:   out $18, R16
   8:   dec R16
   A:   rjmp .-6

$ ./vavrdisasm --no-addresses sampleprogram.hex
rjmp .0         ; 0x2
ser R16
out $17, R16
out $18, R16
dec R16
rjmp .-6        ; 0x6

$ ./vavrdisasm --no-addresses --no-destination-comments sampleprogram.hex
rjmp .0
ser R16
out $17, R16
out $18, R16
dec R16
rjmp .-6

$ ./vavrdisasm -l "A_" sampleprogram.hex

.org 0x000
A_000: rjmp A_002       ; 0x2
A_002: ser R16
A_004: out $17, R16
A_006: out $18, R16
A_008: dec R16
A_00A: rjmp A_006       ; 0x6

$ ./vavrdisasm -l "A_" --no-destination-comments sampleprogram.hex

.org 0x000
A_000: rjmp A_002
A_002: ser R16
A_004: out $17, R16
A_006: out $18, R16
A_008: dec R16
A_00A: rjmp A_006

The above program sample was modified slightly to illustrate vAVRdisasm's
ability to represent data constants in different bases:

$ ./vavrdisasm --data-base-bin sampleprogram2.hex
   0:   rjmp .0         ; 0x2
   2:   ser R16
   4:   out $17, R16
   6:   ldi R16, 0b00100011
   8:   out $18, R16
   A:   dec R16
   C:   rjmp .-6        ; 0x8

