vAVRdisasm - Atmel AVR Disassembler

Visit the github repository for vAVRdisasm here: http://github.com/vsergeev/vAVRdisasm

Download the latest version of vAVRdisasm source here: vavrdisasm-2.0.tar.gz

Download the latest Linux x86 binary of vAVRdisasm here: vavrdisasm-linux-x86-2.0.gz

Visit the Arch Linux AUR Package here: http://aur.archlinux.org/packages.php?ID=46699

ChangeLog

• Release 2.0 - 09/24/2011
  • Changed address operand formatting for LDS, STS, JMP, and CALL instructions from byte addreses to word addresses, to make vAVRdisasm's output compatible with AVR assemblers.
  • Fixed signed relative branch/jump decoding: jumps in the reverse direction are now correctly decoded.
  • Thanks to Graham Carnell for the above two fixes!
  • Upgraded license from GPLv2 to GPLv3.

• Release 1.9 - 04/03/2011
  • CRITICAL FIX: Fixed S-Record reading bug that was ignoring valid data records.
  • Added output file support by -o/--out-file <output file> option.
  • Added standard input support with the ”-” file argument, meaning the disassembler now supports piped input.
  • Improved Atmel Generic / Intel HEX8 / Motorola S-Record auto-detection by first character rather than file extension.
  • Thanks to Thomas for all four of the above fixes and suggestions!
  • Added printing of original opcode data alongside disassembly with --original option.

• Release 1.8 - 01/26/2011
  • Fixed address decoding for LDS, STS, JMP, and CALL instructions. Reversed the modification from release 1.7.
  • Added support for XCH, LAS, LAC, LAT instructions, bringing the disassembler up to date with AVR Instruction Set revision 0856I - 07/10.

• Release 1.7 - 05/27/2010
  • Fixed address decoding for LDS, STS, JMP, and CALL instructions. Previously, vAVRdisasm was printing the disassembled address operands as twice the value they should have been for these instructions.

• Release 1.6 - 02/04/2010
  • Fixed the number-of-operands field for the SPM instruction. This bug was causing vAVRdisasm to crash as it was attempting to format a non-existing operand during disassembly.
  • Updated the README.

• Release 1.5 - 08/25/2009
  • Renamed source files to make more sense and for better organization of code.
  • Added support for DES, SPM #2, LDS (16-bit), and STS (16-bit) instructions, bringing the disassembler to support the AVR instruction set up to revision 0856H - 04/09.

• Release 1.4 - 06/27/2009
  • Fixed handling of newlines (sometimes found at the end of program files) so an “invalid record” error doesn't appear when a newline is read.
  • CRITICAL FIX: Fixed reading and disassembly of odd byte length records in Intel HEX8 and Motorola S-Record files. Special thanks to Ahmed for discovery and patch!

• Release 1.3 - 01/08/2009
  • Fixed a few small bugs/typos for cleaner compilation.
  • CRITICAL FIX: Corrected the absolute address calculation, used in instructions like absolute jump.

• Release 1.2 - 01/06/2007
  • Added formatting of data constants in different bases (hexadecimal, binary, decimal).
  • Fixed a small bug/typo: first operand of “out” instruction is actually an I/O register.

• Release 1.0 - 01/03/2007
  • Initial release.

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.

vAVRdisasm is released under the GNU General Public License Version 3.

    You should have received a copy of the GNU General Public License
    along with this program; see the file "COPYING".  If not, see 
    <http://www.gnu.org/licenses/>.

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”.

For most purposes:

$ ./vavrdisasm <AVR program file>

Example:

$ ./vavrdisasm sampleprogram.hex

Use - for standard input.

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.

Specify an output file for writing instead of the standard output. The output file - is also synonymous for standard output.

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).

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.

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.

See the Ghetto Address Labels section.

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.

Additional usage information from the program's help is provided below.

Usage: ./vavrdisasm <option(s)> <file>
 Disassembles AVR program file <file>. Use - for standard input.
 Written by Vanya A. Sergeev - <vsergeev@gmail.com>.

 Additional Options:
  -o, --out-file <output file>	Write to output file instead of standard output.
  -t, --file-type <type>	Specify the file type of the object file.
  -l, --address-label <prefix> 	Create ghetto address labels with 
				the specified label prefix.
  --original			Print original opcode data alongside
				disassembly.
  --data-base-hex		Represent data constants in hexadecimal
				(default).
  --data-base-bin		Represent data constants in binary.
  --data-base-dec		Represent data constants in decimal.
  --no-addresses		Do not display the address alongside
				disassembly.
  --no-destination-comments	Do not display the destination address
				comments of relative branch/jump/call
				instructions.
  -h, --help			Display this usage/help.
  -v, --version			Display the program's version.

Supported file types:
  Atmel Generic			generic
  Intel HEX8 			ihex
  Motorola S-Record 		srecord

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.

• 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.

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 here. libGIS is compiled into vAVRdisasm–it does not need to be obtained separately.

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