avarice - Provides an interface from avr-gdb to Atmel's AVR
in-circuit debugging tools
avarice [OPTIONS]...
[[HOST_NAME]:PORT]
AVaRICE runs on a POSIX machine and connects to gdb via a TCP
socket and communicates via gdb's "serial debug protocol". This
protocol allows gdb to send commands like "set/remove breakpoint"
and "read/write memory".
AVaRICE translates these commands into the Atmel protocol used to
control the AVR JTAG ICE. Connection to the AVR JTAG ICE is via a serial
port on the POSIX machine.
Because the GDB <---> AVaRICE connection is via a TCP
socket, the two programs do not need to run on the same machine. In an
office environment, this allows a developer to debug a target in the lab
from the comfort of their cube (or even better, their home!)
NOTE: Even though you can run avarice and
avr-gdb on different systems, it is not recommended because of the
security risk involved. avarice was not designed to be a secure
server. There is no authentication performed when a client connects to
avarice when it is running in gdb server mode.
avarice currently has support for the following
devices:
at90can128
at90can32 (o)
at90can64 (o)
at90pwm2 (o) (+)
at90pwm216 (o) (+)
at90pwm2b (o) (+)
at90pwm3 (o) (+)
at90pwm316 (o) (+)
at90pwm3b (o) (+)
at90usb1287 (o)
at90usb162 (o) (+)
at90usb646 (o)
at90usb647 (o)
atmega128
atmega1280 (o)
atmega1281 (o)
atmega1284p (o)
atmega128rfa1 (o)
atmega16
atmega162
atmega164p (o)
atmega165 (o)
atmega165p (o)
atmega168 (o) (+)
atmega168p (o) (+)
atmega169
atmega16hva (o)
atmega16m1 (o) (+)
atmega2560 (o)
atmega2561 (o)
atmega32
atmega323
atmega324p (o)
atmega325 (o)
atmega3250 (o)
atmega3250p (o)
atmega325p (o)
atmega328p (o) (+)
atmega329 (o)
atmega3290 (o)
atmega3290p (o)
atmega329p (o)
atmega32c1 (o) (+)
atmega32hvb (o) (+)
atmega32m1 (o) (+)
atmega32u4 (o)
atmega406 (o)
atmega48 (o) (+)
atmega48p (o) (+)
atmega64
atmega640 (o)
atmega644 (o)
atmega644p (o)
atmega645 (o)
atmega6450 (o)
atmega649 (o)
atmega6490 (o)
atmega64c1 (o) (+)
atmega64m1 (o) (+)
atmega88 (o) (+)
atmega88p (o) (+)
attiny13 (o) (+)
attiny167 (o) (+)
attiny2313 (o) (+)
attiny24 (o) (+)
attiny25 (o) (+)
attiny261 (o) (+)
attiny4313 (o) (+)
attiny43u (o) (+)
attiny44 (o) (+)
attiny45 (o) (+)
attiny461 (o) (+)
attiny48 (o) (+)
attiny84 (o) (+)
attiny85 (o) (+)
attiny861 (o) (+)
attiny88 (o) (+)
atxmega128a1 (o) (*)
atxmega128a1revd (o) (*)
atxmega128a3 (o) (*)
atxmega192a3 (o) (*)
atxmega256a3 (o) (*)
atxmega32a4 (o) (*)
atxmega16d4 (o) (*)
atxmega128b1 (o) (*)
atxmega128b3 (o) (*)
atxmega64b1 (o) (*)
atxmega64b3 (o) (*)
o - Not supported by JTAG ICE mkI
* - Xmega device, requires firmware version of at least 7.x (as shipped
with AVR Studio 5)
+ - debugWire, see below
avarice uses libbfd for reading input files. As such, it
can handle any file format that libbfd knowns about. This includes the Intel
Hex, Motorola SRecord and ELF formats, among others. If you tell
avarice to read an ELF file, it will automatically handle programming
all of the sections contained in the file (e.g. flash, eeprom, etc.).
- -h, --help
- Print this message.
- -1, --mkI
- Connect to original JTAG ICE (default). This is sometimes also called
"mkI" to distinguish it from the more recent versions. Some
simple clones are also around talking this protocol version.
- -2, --mkII
- Connect to JTAG ICE mkII.
- -3, --jtag3
- Connect to JTAGICE3 running firmware 2.x.
- -4, --edbg
- Connect to an AtmelICE, or JTAGICE3 running firmware 3+, or embedded
debugger (EDBG). Requires that avarice has been compiled with
libhidapi support.
- -B, --jtag-bitrate <rate>
- Set the bitrate that the JTAG box communicates with the AVR target device.
This must be less than 1/4 of the frequency of the target. Valid values
are 1 MHz, 500 kHz, 250 kHz or 125 kHz for the JTAG ICE mkI, anything
between 22 kHz through approximately 6400 kHz for the JTAG ICE mkII.
(default: 250 kHz)
- -C, --capture
- Capture running program.
Note: debugging must have been enabled prior to starting the program. (e.g.,
by running avarice earlier)
- -c, --daisy-chain <ub,ua,bb,ba>
- Setup JTAG daisy-chain information.
Four comma-separated parameters need to be provided, corresponding to
units before, units after, bits before, and bits
after.
- -D, --detach
- Detach once synced with JTAG ICE
- -d, --debug
- Enable printing of debug information.
- -e, --erase
- Erase target. Not possible in debugWire mode.
- -E, --event <eventlist>
- List of events that do not interrupt. JTAG ICE mkII and AVR Dragon only.
Default is
"none,run,target_power_on,target_sleep,target_wakeup"
- -f, --file <filename>
- Specify a file for use with the --program and --verify options. If --file
is passed and neither --program or --verify are given then --program is
implied. NOTE: deprecated feature, must be enabled using the
--enable-target-programming configuration option.
- -g, --dragon
- Connect to an AVR Dragon. This option implies the -2 option.
- -I, --ignore-intr
- Automatically step over interrupts.
- -j, --jtag <devname>
- Serial port attached to JTAG box (default: /dev/avrjtag). If the JTAG_DEV
environmental variable is set, avarice will use that as the default
instead.
If avarice has been configured with libusb support, the JTAG ICE mkII
can be connected through USB. In that case, the string usb is used
as the name of the device. If there are multiple JTAG ICE mkII devices
connected to the system through USB, this string may be followed by the
(trailing part of the) ICE's serial number, delimited from the usb
by a colon.
The AVR Dragon, JTAGICE3, AtmelICE, and EDBG can only be connected through
USB, so this option defaults to "usb" in that case.
- -k, --known-devices
- Print a list of known devices.
- -L, --write-lockbits <ll>
- Write lock bits. The lock byte data must be given in two digit hexidecimal
format with zero padding if needed.
- -l, --read-lockbits
- Read the lock bits from the target. The individual bits are also displayed
with names.
- -P, --part <name>
- Target device name (e.g. atmega16). Normally, avarice autodetects
the device via JTAG or debugWIRE. If this option is provided, it overrides
the result from the autodetection.
- -p, --program
- Program the target. Binary filename must be specified with --file option.
NOTE: deprecated feature, must be enabled using the
--enable-target-programming configuration option.
- -R, --reset-srst
- Apply nSRST signal (external reset) when connecting. This can override
applications that set the JTD bit.
- -r, --read-fuses
- Read fuses bytes.
- -V, --version
- Print version information.
- -v, --verify
- Verify program in device against file specified with --file option.
NOTE: deprecated feature, must be enabled using the
--enable-target-programming configuration option.
- -w, --debugwire
- Connect to JTAG ICE mkII, JTAGICE3, or AVR Dragon, talking debugWire
protocol to the target. This option implies the -2 option. See the
DEBUGWIRE section below.
- -W, --write-fuses <eehhll>
- Write fuses bytes. ee is the extended fuse byte, hh is the
high fuse byte and ll is the low fuse byte. The fuse byte data must
be given in two digit hexidecimal format with zero padding if needed. All
three bytes must currently be given.
NOTE: Current, if the target device doesn't have an extended fuse
byte (e.g. the atmega16), the you should set ee==ll when writing the fuse
bytes.
- -x, --xmega
- The target device is an ATxmega part, using JTAG transport. Since the
ATxmega uses a different JTAG communication than other AVRs, the normal
device autodetection based on the JTAG ID does not work. If the device has
been explicitly selected through the -P option, it is not necessary to
also specify the -x option.
- -X, --pdi
- The target device is an ATxmega part, using PDI transport.
HOST_NAME defaults to 0.0.0.0 (listen on any interface) if
not given.
:PORT is required to put avarice into gdb server mode.
avarice --erase --program --file test.bin --jtag /dev/ttyS0
:4242
Program the file test.bin into the JTAG ICE (mkI) connected
to /dev/ttyS0 after erasing the device, then listen in GDB mode on the local
port 4242. This functionality is deprecated, and no longer configured by
default. Use GDB's "load" command instead.
avarice --jtag usb:1234 --mkII :4242
Connect to the JTAG ICE mkII attached to USB which serial number
ends in 1234, and listen in GDB mode on local port 4242.
The JTAG ICE debugging environment has a few restrictions and
changes:
- No "soft" breakpoints, and only three hardware breakpoints. The
break command sets hardware breakpoints. The easiest way to deal with this
restriction is to enable and disable breakpoints as needed.
- Two 1-byte hardware watchpoints (but each hardware watchpoint takes away
one hardware breakpoint). If you set a watchpoint on a variable which
takes more than one byte, execution will be abysmally slow. Instead it is
better to do the following:
watch *(char *)&myvariable
- which watches the least significant byte of myvariable.
- •
- The Atmel AVR processors have a Harvard architecture (separate code and
data buses). To distinguish data address 0 from code address 0,
avr-gdb adds 0x800000 to all data addresses. Bear this in mind when
examining printed pointers, or when passing absolute addresses to gdb
commands.
The debugWire protocol is a proprietary protocol introduced
by Atmel to allow debugging small AVR controllers that don't offer enough
pins (and enough chip resources) to implement full JTAG. The communication
takes place over the /RESET pin which needs to be turned into a
debugWire connection pin by programming the DWEN fuse (debugWire
enable), using a normal programmer connection (in-system programming,
high-voltage programming). Note that by enabling this fuse, the standard
reset functionality of that pin will be lost, so any in-system programming
will cease to work as it requires a functional /RESET pin. Thus it
should be made absolutely sure there is a way back, like a device (as
the STK500, for example) that can handle high-voltage programming of the
AVR. Currently, avarice offers no option to turn off the DWEN fuse.
However, avrdude offers the option to turn it off either through
high-voltage programming, or by using the JTAG ICE mkII to first turn the
target into an ISP-compatible mode, and then using normal ISP commands to
change the fuse settings.
Note that the debugWire environment is further limited, compared to JTAG. It
does not offer hardware breakpoints, so all breakpoints have to be
implemented as software breakpoints by rewriting flash pages using
BREAK instructions. Some memory spaces (fuse and lock bits) are not
accessible through the debugWire protocol.
Avarice (up to version 1.5) was originally written by Scott
Finneran with help from Peter Jansen. They did the work of figuring out the
jtagice communication protocol before Atmel released the spec (appnote
AVR060).
David Gay made major improvements bringing avarice up to 2.0.
Joerg Wunsch reworked the code to abstract the JTAG ICE
communication from the remainder, and then extended the code to support the
JTAG ICE mkII protocol (see Atmel appnote AVR067), as well as the JTAGICE3
protocol.