MAN page from openSUSE Leap 42 avarice-2.13-07.1.x86_64.rpm

avarice

Section: User Commands (1)
Updated: December 15, 2011
Index

NAME

avarice - Provides an interface from avr-gdb to Atmel's JTAGICE box.

SYNOPSIS

avarice[OPTIONS]... [[HOST_NAME]:PORT]

DESCRIPTION

AVaRICE runs on a POSIX machine and connects to gdb via a TCP socket andcommunicates via gdb's "serial debug protocol". This protocol allows gdb tosend commands like "set/remove breakpoint" and "read/write memory".

AVaRICE translates these commands into the Atmel protocol used to control theAVR JTAG ICE. Connection to the AVR JTAG ICE is via a serial port on the POSIXmachine.

Because the GDB <---> AVaRICE connection is via a TCP socket, the two programsdo not need to run on the same machine. In an office environment, this allowsa developer to debug a target in the lab from the comfort of their cube (oreven 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 wasnot designed to be a secure server. There is no authentication performedwhen a client connects to avarice when it is running in gdb server mode.

Supported Devices

avaricecurrently 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

avariceuses libbfd for reading input files. As such, it can handle any file formatthat libbfd knowns about. This includes the Intel Hex, Motorola SRecord andELF formats, among others. If you tell avarice to read an ELF file, itwill automatically handle programming all of the sections contained in thefile (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 target device.This must be less than 1/4 of the frequency of the target. Valid values are1 MHz, 500 kHz, 250 kHz or 125 kHz for the JTAG ICE mkI,anything between 22 kHz through approximately 6400 kHz for theJTAG 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 tounits before, units after, bits before, andbits 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 ispassed and neither --program or --verify are given then --program is implied..BNOTE:deprecated feature, must be enabled using the --enable-target-programmingconfiguration 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 environmentalvariable is set, avarice will use that as the default instead.
If avarice has been configured with libusb support, the JTAG ICEmkII 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 systemthrough 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 optiondefaults 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 hexidecimalformat with zero padding if needed.
-l, --read-lockbits: Read the lock bits from the target. The individual bits are also displayedwith 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 theautodetection.
-p, --program: Program the target. Binary filename must be specified with --file option..BNOTE:deprecated feature, must be enabled using the --enable-target-programmingconfiguration 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..BNOTE:deprecated feature, must be enabled using the --enable-target-programmingconfiguration option.
-w, --debugwire: Connect to JTAG ICE mkII (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 highfuse byte and ll is the low fuse byte. The fuse byte data must be givenin two digit hexidecimal format with zero padding if needed. All three bytesmust 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 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 thelocal port 4242.

avarice --jtag usb:1234 --mkII :4242

Connect to the JTAG ICE mkII attached to USB which serial number endsin 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 breakcommand sets hardware breakpoints. The easiest way to deal with thisrestriction is to enable and disable breakpoints as needed.

*

Two 1-byte hardware watchpoints (but each hardware watchpoint takes awayone hardware breakpoint). If you set a watchpoint on a variable which takesmore than one byte, execution will be abysmally slow. Instead it is betterto do the following:

: watch *(char *)&myvariable

which watches the least significant byte ofmyvariable.

*

The Atmel AVR processors have a Harvard architecture (separate code anddata buses). To distinguish data address 0 from code address 0,avr-gdbadds 0x800000 to all data addresses. Bear this in mind when examiningprinted pointers, or when passing absolute addresses to gdb commands.

DEBUGWIRE

The debugWire protocol is a proprietary protocol introducedby Atmel to allow debugging small AVR controllers that don't offerenough pins (and enough chip resources) to implement full JTAG.The communication takes place over the /RESET pin which needsto be turned into a debugWire connection pin by programming theDWEN fuse (debugWire enable), using a normal programmerconnection (in-system programming, high-voltage programming).Note that by enabling this fuse, the standard reset functionalityof that pin will be lost, so any in-system programming will ceaseto 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 handlehigh-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 eitherthrough high-voltage programming, or by using the JTAG ICE mkII tofirst turn the target into an ISP-compatible mode, and then usingnormal ISP commands to change the fuse settings.
Note that the debugWire environment is further limited, compared toJTAG.It does not offer hardware breakpoints, so all breakpoints have tobe implemented as software breakpoints by rewriting flash pagesusing BREAK instructions.Some memory spaces (fuse and lock bits) are not accessible throughthe debugWire protocol.

AUTHORS

Avarice (up to version 1.5) was originally written by Scott Finneran with helpfrom Peter Jansen. They did the work of figuring out the jtagice communicationprotocol 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 communicationfrom the remainder, and then extended the code to support the JTAG ICEmkII protocol (see Atmel appnote AVR067).

Index

NAME

SYNOPSIS

DESCRIPTION

Supported Devices
Supported File Formats

OPTIONS

EXAMPLE USAGE

DEBUGGING WITH AVARICE

DEBUGWIRE

SEE ALSO

AUTHORS

This document was created byman2html,using the manual pages.