Provided by: avarice_2.14+svn427-1_amd64 
NAME
avarice - Provides an interface from avr-gdb to Atmel's AVR in-circuit debugging tools
SYNOPSIS
avarice [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 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.
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) (*)
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
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 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.
EXAMPLE USAGE
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.
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 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.
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 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.
SEE ALSO
gdb(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), as well as the JTAGICE3 protocol.
October 15, 2018 avarice(1)