Provided by: avarice_2.13+svn372-2_amd64 bug

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

       -3, --jtag3
              Connect to JTAGICE3.

       -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>
              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 and JTAGICE3 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 hexadecimal 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 hexadecimal 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.

                                        December 15, 2011                              avarice(1)