Provided by: avarice_2.13+svn375-1_amd64 bug

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

                                         October 15, 2018                              avarice(1)