Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
avarice(1)		    General Commands Manual		    avarice(1)

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 al-
       lows gdb	to send	commands like "set/remove breakpoint" and  "read/write
       memory".

       AVaRICE	translates these commands into the Atmel protocol used to con-
       trol 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  environ-
       ment,  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  au-
	     thentication  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,  Mo-
       torola  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 ver-
	      sion.

       -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  em-
	      bedded 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 tar-
	      get  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, correspond-
	      ing 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,tar-
	      get_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 op-
	      tion.

       -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  se-
	      rial number, delimited from the usb by a colon.
	      The  AVR	Dragon,	 JTAGICE3, AtmelICE, and EDBG can only be con-
	      nected 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).  Normally, avarice autode-
	      tects the	device via JTAG	or debugWIRE.  If this option is  pro-
	      vided, 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  op-
	      tion.	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  de-
	      bugWire  protocol	to the target.	This option implies the	-2 op-
	      tion.  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.
	      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 op-
	      tion.

       -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 lo-
       cal port	4242.  This functionality is deprecated, and no	longer config-
       ured 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:

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

       o   Two 1-byte hardware watchpoints (but	each hardware watchpoint takes
	   away	one hardware breakpoint). If you set a watchpoint on  a	 vari-
	   able	 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.

       o   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 pro-
       gramming).  Note	that by	enabling this fuse, the	standard  reset	 func-
       tionality  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 us-
       ing 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 pro-
       tocol.

			       October 15, 2018			    avarice(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLE USAGE | DEBUGGING WITH AVARICE | DEBUGWIRE | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=avarice&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help