Man Linux: Main Page and Category List


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


       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.

   Supported Devices
       avarice currently has support for the following devices:
           at90can32 (o)
           at90can64 (o)
           at90pwm2 (o) (+)
           at90pwm216 (o) (+)
           at90pwm2b (o) (+)
           at90pwm3 (o) (+)
           at90pwm316 (o) (+)
           at90pwm3b (o) (+)
           at90usb1287 (*)
           at90usb162 (o) (+)
           at90usb646 (*)
           at90usb647 (*)
           atmega1280 (*)
           atmega1281 (*)
           atmega1284p (*)
           atmega164p (o)
           atmega165 (o)
           atmega165p (o)
           atmega168 (o) (+)
           atmega168p (o) (+)
           atmega16hva (o)
           atmega2560 (*)
           atmega2561 (*)
           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 (*)
           atmega48 (o) (+)
           atmega48p (o) (+)
           atmega640 (*)
           atmega644 (*)
           atmega644p (*)
           atmega645 (*)
           atmega6450 (*)
           atmega649 (*)
           atmega6490 (*)
           atmega88 (o) (+)
           atmega88p (o) (+)
           attiny13 (o) (+)
           attiny167 (o) (+)
           attiny2313 (o) (+)
           attiny24 (o) (+)
           attiny25 (o) (+)
           attiny261 (o) (+)
           attiny43u (o) (+)
           attiny44 (o) (+)
           attiny45 (o) (+)
           attiny461 (o) (+)
           attiny48 (o) (+)
           attiny84 (o) (+)
           attiny85 (o) (+)
           attiny861 (o) (+)
           attiny88 (o) (+)
           atxmega128a1 (*)

       * - Only supported by the JTAG ICE mkII device.
       o - Only supported by the JTAG ICE mkII and AVR Dragon device.
       + - 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.).


       -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 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

       -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.

       -g, --dragon
              Connect to an AVR Dragon.  This option implies the -2 option.

       -I, --ignore-intr
              Automatically step over interrupts.
              Note:  EXPERIMENTAL.  Can not currently handle devices fused for

       -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)

       -p, --program
              Program the target.  Binary  filename  must  be  specified  with
              --file option.
              NOTE:  The  old  behaviour  of  automatically erasing the target
              before programming is no longer done. You must  explicitly  give
              the --erase option for the target to be erased.

       -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

       -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 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.  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.
              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 (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.

       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

       ·   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.   (Software  breakpoints  are currently not
       implemented by avarice.)  Some memory spaces (fuse and lock  bits)  are
       not accessible through the debugWire protocol.


       gdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),


       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

       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).

                              September 29, 2008                    avarice(1)