avarice(1)avarice(1)NAMEavarice - Provides an interface from avr-gdb to Atmel's JTAGICE box.
SYNOPSISavarice [OPTIONS]... [[HOST_NAME]:PORT]
DESCRIPTION
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 con‐
trol 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 environ‐
ment, 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.
Supported Devices
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) (*)
atxmega32a4 (o) (*)
atxmega16d4 (o) (*)
atxmega128b1 (o) (*)
atxmega128b3 (o) (*)
atxmega64b1 (o) (*)
atxmega64b3 (o) (*)
o - Only supported by the JTAG ICE mkII and AVR Dragon device.
* - Xmega device, requires firmware version of at least 7.x (as shipped
with AVR Studio 5)
+ - debugWire, see below
Supported File Formats
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.).
OPTIONS-h, --help
Print this message.
-1, --mkI
Connect to JTAG ICE mkI (default).
-2, --mkII
Connect to JTAG ICE mkII.
-B, --jtag-bitrate <rate>
Set the bitrate that the JTAG box communicates with the AVR tar‐
get 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, correspond‐
ing 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,tar‐
get_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>
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 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 autode‐
tects the device via JTAG or debugWIRE. If this option is pro‐
vided, 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 (or AVR Dragon), talking debugWire pro‐
tocol 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.
-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.
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.
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.
EXAMPLE USAGEavarice--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.
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.
DEBUGGING WITH AVARICE
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 vari‐
able 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.
DEBUGWIRE
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 pro‐
gramming). Note that by enabling this fuse, the standard reset func‐
tionality 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.
SEE ALSOgdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),
ice-insight(1)AUTHORS
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).
December 15, 2011 avarice(1)
