README for revava-0.3, Copyright (C) 2001, Daniel J. WinkerShort description:Disassembler for Atmel AVR microcontroller firmware.Full description:revava is a single pass disassembler that reads in a file containing aprogram intended for an Atmel AVR microcontroller and outputs assemblycode that can be input to an avr assembler.  The output of revavacontains assembler mnemonics where possible and dc.W declarations whereno mnemonic matches the data.  The comment field for each assemblyinstruction contains the address from the object code and thedestination address for branches, calls, jumps, etc.  In the case wherethere are multiple assembly instructions that assemble to the sameopcode, all choices are presented in a group with all but the firstchoice commented out.  make_labels.pl is a Perl script that's beenincluded.  It takes the output of revava and puts "jump to" and functionlabels in the code.This is an early release of revava.  Right now only Intel hex files aresupported for input.  It would not be hard to add support for otherformats.  See the file TODO for more ideas.I took a lot of the code (probably about half) from AVA Version 0.3bwhich was written by Uros Platise and is available fromhttp://medo.fov.uni-mb.si/mapp.  AVA is an Atmel AVR assembler.Compiling:The code is pretty vannilla C++.  It should build with just about anyC++ compiler.  I know Version 0.4 compiles easily with GCC 3.3.4 becausea user sent me a patch to make it so.  If you have compiling problemsit's usually just because of slight differences in which prototypes arein which include files.  You probably won't have to fix anything otherthat the offending #include line.After downloading the latest tarball (x.y is the version number)	tar -xvzf revava-x.y.tar.gz	cd revava-x.yHere you might want to edit the Makefile for your own preferences, then:	makeThis should make two executables: "revava" and "make_test_source".  revavais the disassembler.  make_test_source just spits out some AVR assembly codethat uses every instruction with different combinations of arguments.After that you might want to	strip revavaI thought not using -g as a compiler flag made the executable as smallas possible, but "strip revava" makes it even smaller.Testing:If you want to test it and you have AVA (which can be obtained athttp://medc.fov.uni-mb.si/mapp) you can execute the following:	# This makes some crazy assembly code.  Don't try to run it!	./make_test_source > test_source.s	# The following two lines create an Intel hex file named test.flash	ava test_source.s	ava --intel -o test test_source.o	# This creates another assembly file that should be equivalent	# to test_source.s	revava test.flash	# Try to assemble revava's output	ava out.s	ava --intel out.o	# See if we ended up back where we started	diff test.flash a.out.flashThere should be no difference.Installing:There is no "make install" target in the makefile.  (See TODO file).So, just copy or move the executable "revava" to /usr/local/bin orwherever you want to keep it.  This README file is the extent of thedocumentation (See TODO file), so keep it around when you use revava.Using:Just typing "revava" and hitting enter returns something like this:	Atmel Dis-Assembler 0.1	Syntax: revava [switches] file	Switches:	  -d         Dump Flash and exit.	  -D         Debug Dump Flash (maybe should be Dubious Dump).	  -e         Use little endian (Intel byte order).	  -o file    Output file name (to redirect to stdout -o stdout).	  --help     Print this help.	  --version  Output version information."file" is of course the object file that we want to disassemble.  I'llgo through the switches one at a time.-d	Dump Flash and exit.This does the (probably) familiar hex dump that looks something likethis:	04E0: 5000 570F 5F0F 5080  578F 5F8F 50F0 57FF  P.W._.P. W._.P.W.	04F0: 5FFF 9402 94F2 95F2  2000 20FF 23FF 95A8  _.......  . .#...	1000: FFFF 940E 940C ----  ---- ---- ---- ----  ......           The leftmost column is the address in hex.  Then we have the hex dataand finally an ASCII representation of the data if it seems appropriate.The '-' characters in the hex data area mean that that data did not showup in the input object file.  (There was data at addresses 1000 to 1005,but nothing from 1006 to 100F).  Similarily, there are no addressesshown from 0500 to 09FF because they didn't show up in the input file.This option in combination with the -e flag is actually very useful forfinding text strings embedded in the object file.-D	Debug Dump Flash and exit.This is mostly for debugging revava itself.  The output is prettysimilar to what you get with the -d flag, except the entire flash spaceis dumped - whether it was present in the input file or not - and thereis an extra field that is the flags that keep track of what parts offlash showed up in the input.  One problem with this output is that itis more than 80 columns wide.-e	Use little endian (Intel byte order)This flips the bytes in each word right after reading in the input file.This is useful because typically the way that works for disassembling isoppisite of the way that makes strings show up right with the -d flag.Try it once without -e and once with -e to see which one disassemblesright.  Then try the -d flag once without -e and once with -e to seewhich one displays any strings correctly.-o file	Output file nameShould be pretty straightforward.  I suppose redirecting to stdout with	revava -o stdout input.hexis a little strange.  Oh well.--help     Print this help.--version  Output version information.These two should also be pretty straightforward.make_labels.pl:Run this on the output of revava to add function labels and simple"jump to" labels.  This makes the output source a little easier to read.For instance, it will change this:	        clr     r16             ; 04E0	        ;eor    r16, r16        ; 04E0	        ldi     r16, 0x6        ; 04E2	        sts     0x0074, r16     ; 04E4	        rjmp    910             ; 04F8, Dest: 0888	        rcall   1528            ; 04FA, Dest: 0AF4into this:	L042:	        clr     r16             ; 04E0	        ;eor    r16, r16        ; 04E0	        ldi     r16, 0x6        ; 04EA	        sts     0x0074, r16     ; 04EC	        rjmp    L115            ; 04F0, Dest: 0888	Func005:	        rcall   Func008         ; 04F2, Dest: 0AF4make_labels.pl reads in a file and outputs to stdout, so typically youwould do something like this:	revava -o prog.s program.hex	make_labels.pl prog.s > program.sIf make_labels.pl can't find the "jump to" or function address it justadds "##### Dest BOGUS #####" to the end of the source line.  This meansthat the destination address is either in the middle of a double wordinstruction or the destination address was never included in theoriginal object file.  A section of the code with lots of"##### Dest BOGUS #####" comments is probably really a data section.Note, make_labels.pl is much less tested than revava.  You should use anassembler to make sure you can recreate the object code from your brandnew source.Contact:The website for revava is currently http://www.visi.com/~dwinker/revava.I can be contacted at dwinker@tiny.net.