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 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  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) (*)
	   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, 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 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 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>
	      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 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).  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 (or AVR Dragon),	talking	debugWire pro-
	      tocol 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,  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.
	      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 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.

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

			       December	15, 2011		    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+12.1-RELEASE+and+Ports>

home | help