Provided by: avarice_2.11-1.1ubuntu1_amd64 bug


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

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

       -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

       -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

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

       -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 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.  (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), ice-insight(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 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

                                        September 29, 2008                             avarice(1)