The Context

This archive contains Python scripts to process the output from avr-objdump. The main reason is the latter application¹ only shows numeric values instead of special register names, such as PORTA, UCSR0A, aso. This is relatively annoying when trying to debug a program or just verify how the generated assembly looks like, for instance. The idea of having special register names in a listing stemmed from that.

Usage

First off, adump.py --help shall tell everything there has to say about its use. It takes the exact same arguments as avr-objdump with the following exceptions:

• the first argument must be the processor name, e.g. atmega328, atmega328p, attiny44;
• an optional argument, --color is used to set the theme of the output result;
• option --dump-registers does exactly what it says, i.e. list all special registers supported by the selected processor (see the first argument), for example:

  $ adump.py atmega328 --dump-registers
  MCU: atmega328 [avr5]
          0xC6 : UDR0
          0xC5 : UBRR0H
          0xC4 : UBRR0L
          0xC2 : UCSR0C
          0xC1 : UCSR0B
          ...
  

Note: avr-objdump expects argument -m to designate a family instead of a specific processor name. The translation is done in avr/arch.py so you do not have to use it. It may happen that file to be outdated if Atmel/Microchip releases new microcontrollers though. See Questions/Answers as to how to updating the file on your own.

Examples:

adump.py atmega328 -D main.flash.hex
↳ Shows the disassembled code in a HEX file, as extracted with avr-objcopy².

adump.py atmega328 -SCt main.elf
↳ Prints the disassembled code and the symbol table from the compiled ELF file, as generated for a ATmega328. C++ function names are also "de-mangled" (see avr-objdump option -C).

adump.py attiny45 -D -b binary main.flash.bin
↳ Prints the disassembled code from a raw binary file, as read from an ATtiny45³ with avrdude -p t45... -U flash:r:-:r

Installation

Big warning : this code has been designed to run on a Linux machine and has not been tested on Windows. The rest of this section assumes you have a functional Python installation and you know how to install a few scripts on your system by hand.

On Linux

1. Unpack the archive in /usr/local/bin. You may also want to use /opt/ instead but then you'll also have to update the PATH environment variable accordingly, which is why the former option is less of a hassle, besides the fact that it is untouched by your package manager. Mind to include that directory tree in your backups⁴, of course!

2. Mark adump.py executable (i.e. chmod +x /usr/local/bin/adump.py).

Note: You might need to execute all the above actions under the super administrator account (root). Be sure to mark root the owner of all files in the archive to avoid security breaches.

Once you're done, adump.py can be run from anywhere.

On Windows

The biggest problem on Windows is the variety of ways one can setup a (working) Python environment. You should be familiar with basic system administration, which includes (though not limited to)

• running custom applications, such as Python or Command Shell scripts from a dedicated folder;

• executing commands without specifying the complete path, i.e. manage your PATH environment variable.

You might want to store the extracted files in a subfolder under your profile directory or in the system's C:\Program Files or C:\Windows (which you shouldn't). Check this guide on StackOverflow as to executing Python scripts without specifying the interpreter.

The archive also contains symbolic links, which I have no idea they will work on Windows, let alone extract correctly. Use the support page if they are not. Here's the list of links and files they designate:

avr/atmega16u4.py -> atmega32u4.py
avr/atmega64m1.py -> atmega32m1.py
avr/attiny841.py -> attiny441.py
avr/avr51.py -> avr5.py
avr/atmega128a.py -> atmega128.py
avr/atmega328p.py -> atmega328.py
avr/attiny45.py -> attiny85.py
avr/atmega168.py -> atmega328.py

Questions/Answers

Q. Will you provide a package for [insert distribution name] ?

Nope.

Q. Will you provide a pypy/pip/whatever package?

See above.

Q. How do I contact you?

If you are a regular SourceForge user, then you probably know ;-) .

Q. How can I contribute?

That is a good question. See the support page for the moment. I might turn the project into a full-fledged repository one day but there is no guarantee thus far.

Q. Does this run with Python 2.7?

With what?

Q. How do I add new architectures from Microchip?

First off the script is intentionally limited to AVR microcontrollers. I have never planned supporting other brands, such as STM32 or ESP... mostly because I don't use these. Consequently I don't know whether the corresponding tools do or not lack the ability to identify special registers, let alone if these processors have special registers at all.

Currently the "largest" support is ATmeta and ATtiny. The X-mega family is unknown to me and I haven't yet had any use for it either.

I update the tool everytime I use a new microcontroller, either to test my code or because I use it in my hardware projects. So it may be a while until I update the archive you are using.

If you want to update this tool for your own use, here's a few hints:

• files avr<number>.py are intended to provide, in a dictionary, a basic set of special registers for the corresponding AVR architecture name, e.g. avr5, avr25 — note that you can identify it with avr-gcc -E as it will dump all known macros;

• files named after the microcontroller expose processor-specific registers, which layout differs from the architecture-supplied list;

• if a processor-specific script is missing, then adump will use the architecture's;

• if neither the architecture- nor processor-specific module is found, then adump exits with an explicit error message.

• you can retrieve the list of registers for a given microcontroller using avr-gcc (the easiest) or from the datasheet. A few command line examples are given in avr/arch.py but they are not guaranteed to work at all times as they assume the structure of the datasheet is consistent across all documents...

Q. How do I retrieve the list of special registers with avr-gcc ?

Use this one-liner (on a Linux machine) to map special registers for the ATmega328 (Arduino Uno):

echo -e "#include <avr/io.h>\nvoid main() {}" | \
    avr-gcc -E -mmcu atmega328 -dM - | \
    sed -rn \
        -e 's/#define\s+([A-Z0-9]+)\s+_SFR_([IM])[A-Z]+([0-9]+)/\1\t\2\3/gp'

---

¹ It ships with avr-binutils.

² Refer to the manual for details.

³ Assuming lock bits weren't set, of course!

⁴ Because you do backups, don't you?