1avarice(1)                  General Commands Manual                 avarice(1)
2
3
4

NAME

6       avarice - Provides an interface from avr-gdb to Atmel's JTAGICE box.
7

SYNOPSIS

9       avarice [OPTIONS]... [[HOST_NAME]:PORT]
10

DESCRIPTION

12       AVaRICE  runs  on  a POSIX machine and connects to gdb via a TCP socket
13       and communicates via  gdb's  "serial  debug  protocol".  This  protocol
14       allows   gdb   to   send  commands  like  "set/remove  breakpoint"  and
15       "read/write memory".
16
17       AVaRICE translates these commands into the Atmel protocol used to  con‐
18       trol  the  AVR JTAG ICE. Connection to the AVR JTAG ICE is via a serial
19       port on the POSIX machine.
20
21       Because the GDB <---> AVaRICE connection is via a TCP socket,  the  two
22       programs  do not need to run on the same machine. In an office environ‐
23       ment, this allows a developer to debug a target in  the  lab  from  the
24       comfort of their cube (or even better, their home!)
25
26       NOTE: Even though you can run avarice and avr-gdb on different systems,
27             it is not recommended because  of  the  security  risk  involved.
28             avarice  was  not  designed  to  be  a secure server. There is no
29             authentication performed when a client connects to  avarice  when
30             it is running in gdb server mode.
31
32   Supported Devices
33       avarice currently has support for the following devices:
34           at90can128
35           at90can32 (o)
36           at90can64 (o)
37           at90pwm2 (o) (+)
38           at90pwm216 (o) (+)
39           at90pwm2b (o) (+)
40           at90pwm3 (o) (+)
41           at90pwm316 (o) (+)
42           at90pwm3b (o) (+)
43           at90usb1287 (o)
44           at90usb162 (o) (+)
45           at90usb646 (o)
46           at90usb647 (o)
47           atmega128
48           atmega1280 (o)
49           atmega1281 (o)
50           atmega1284p (o)
51           atmega128rfa1 (o)
52           atmega16
53           atmega162
54           atmega164p (o)
55           atmega165 (o)
56           atmega165p (o)
57           atmega168 (o) (+)
58           atmega168p (o) (+)
59           atmega169
60           atmega16hva (o)
61           atmega16m1 (o) (+)
62           atmega2560 (o)
63           atmega2561 (o)
64           atmega32
65           atmega323
66           atmega324p (o)
67           atmega325 (o)
68           atmega3250 (o)
69           atmega3250p (o)
70           atmega325p (o)
71           atmega328p (o) (+)
72           atmega329 (o)
73           atmega3290 (o)
74           atmega3290p (o)
75           atmega329p (o)
76           atmega32c1 (o) (+)
77           atmega32hvb (o) (+)
78           atmega32m1 (o) (+)
79           atmega32u4 (o)
80           atmega406 (o)
81           atmega48 (o) (+)
82           atmega48p (o) (+)
83           atmega64
84           atmega640 (o)
85           atmega644 (o)
86           atmega644p (o)
87           atmega645 (o)
88           atmega6450 (o)
89           atmega649 (o)
90           atmega6490 (o)
91           atmega64c1 (o) (+)
92           atmega64m1 (o) (+)
93           atmega88 (o) (+)
94           atmega88p (o) (+)
95           attiny13 (o) (+)
96           attiny167 (o) (+)
97           attiny2313 (o) (+)
98           attiny24 (o) (+)
99           attiny25 (o) (+)
100           attiny261 (o) (+)
101           attiny4313 (o) (+)
102           attiny43u (o) (+)
103           attiny44 (o) (+)
104           attiny45 (o) (+)
105           attiny461 (o) (+)
106           attiny48 (o) (+)
107           attiny84 (o) (+)
108           attiny85 (o) (+)
109           attiny861 (o) (+)
110           attiny88 (o) (+)
111           atxmega128a1 (o) (*)
112           atxmega128a1revd (o) (*)
113           atxmega128a3 (o) (*)
114           atxmega32a4 (o) (*)
115           atxmega16d4 (o) (*)
116           atxmega128b1 (o) (*)
117           atxmega128b3 (o) (*)
118           atxmega64b1 (o) (*)
119           atxmega64b3 (o) (*)
120
121       o - Only supported by the JTAG ICE mkII and AVR Dragon device.
122       * - Xmega device, requires firmware version of at least 7.x (as shipped
123       with AVR Studio 5)
124       + - debugWire, see below
125
126   Supported File Formats
127       avarice uses libbfd for reading input files. As such, it can handle any
128       file  format  that  libbfd  knowns  about. This includes the Intel Hex,
129       Motorola SRecord and ELF formats, among others. If you tell avarice  to
130       read  an  ELF file, it will automatically handle programming all of the
131       sections contained in the file (e.g. flash, eeprom, etc.).
132

OPTIONS

134       -h, --help
135              Print this message.
136
137       -1, --mkI
138              Connect to JTAG ICE mkI (default).
139
140       -2, --mkII
141              Connect to JTAG ICE mkII.
142
143       -B, --jtag-bitrate <rate>
144              Set the bitrate that the JTAG box communicates with the AVR tar‐
145              get  device.  This must be less than 1/4 of the frequency of the
146              target. Valid values are 1 MHz, 500 kHz, 250 kHz or 125 kHz  for
147              the  JTAG ICE mkI, anything between 22 kHz through approximately
148              6400 kHz for the JTAG ICE mkII. (default: 250 kHz)
149
150       -C, --capture
151              Capture running program.
152              Note: debugging must have been enabled  prior  to  starting  the
153              program. (e.g., by running avarice earlier)
154
155       -c, --daisy-chain <ub,ua,bb,ba>
156              Setup JTAG daisy-chain information.
157              Four comma-separated parameters need to be provided, correspond‐
158              ing to units before, units after, bits before, and bits after.
159
160       -D, --detach
161              Detach once synced with JTAG ICE
162
163       -d, --debug
164              Enable printing of debug information.
165
166       -e, --erase
167              Erase target.  Not possible in debugWire mode.
168
169       -E, --event <eventlist>
170              List of events that do not interrupt.  JTAG  ICE  mkII  and  AVR
171              Dragon    only.    Default   is   "none,run,target_power_on,tar‐
172              get_sleep,target_wakeup"
173
174       -f, --file <filename>
175              Specify a file for use with the --program and --verify  options.
176              If  --file is passed and neither --program or --verify are given
177              then --program is implied.   NOTE: deprecated feature,  must  be
178              enabled   using  the  --enable-target-programming  configuration
179              option.
180
181       -g, --dragon
182              Connect to an AVR Dragon.  This option implies the -2 option.
183
184       -I, --ignore-intr
185              Automatically step over interrupts.
186
187       -j, --jtag <devname>
188              Port attached  to  JTAG  box  (default:  /dev/avrjtag).  If  the
189              JTAG_DEV environmental variable is set, avarice will use that as
190              the default instead.
191              If avarice has been configured with libusb support, the JTAG ICE
192              mkII can be connected through USB.  In that case, the string usb
193              is used as the name of the device.  If there are  multiple  JTAG
194              ICE  mkII  devices  connected  to  the  system through USB, this
195              string may be followed by  the  (trailing  part  of  the)  ICE's
196              serial number, delimited from the usb by a colon.
197              The AVR Dragon can only be connected through USB, so this option
198              defaults to "usb" in that case.
199
200       -k, --known-devices
201              Print a list of known devices.
202
203       -L, --write-lockbits <ll>
204              Write lock bits. The lock byte data must be given in  two  digit
205              hexidecimal format with zero padding if needed.
206
207       -l, --read-lockbits
208              Read the lock bits from the target. The individual bits are also
209              displayed with names.
210
211       -P, --part <name>
212              Target device name (e.g. atmega16).  Normally,  avarice  autode‐
213              tects  the device via JTAG or debugWIRE.  If this option is pro‐
214              vided, it overrides the result from the autodetection.
215
216       -p, --program
217              Program the target.  Binary  filename  must  be  specified  with
218              --file option.   NOTE: deprecated feature, must be enabled using
219              the --enable-target-programming configuration option.
220
221       -R, --reset-srst
222              Apply nSRST signal (external reset) when connecting.   This  can
223              override applications that set the JTD bit.
224
225       -r, --read-fuses
226              Read fuses bytes.
227
228       -V, --version
229              Print version information.
230
231       -v, --verify
232              Verify  program  in  device  against  file specified with --file
233              option.   NOTE: deprecated feature, must be  enabled  using  the
234              --enable-target-programming configuration option.
235
236       -w, --debugwire
237              Connect to JTAG ICE mkII (or AVR Dragon), talking debugWire pro‐
238              tocol to the target.  This option implies the  -2  option.   See
239              the DEBUGWIRE section below.
240
241       -W, --write-fuses <eehhll>
242              Write  fuses bytes. ee is the extended fuse byte, hh is the high
243              fuse byte and ll is the low fuse byte. The fuse byte  data  must
244              be  given  in  two digit hexidecimal format with zero padding if
245              needed. All three bytes must currently be given.
246
247       -x, --xmega
248              The target device is an  ATxmega  part,  using  JTAG  transport.
249              Since the ATxmega uses a different JTAG communication than other
250              AVRs, the normal device autodetection based on the JTAG ID  does
251              not  work.   If  the device has been explicitly selected through
252              the -P option, it is  not  necessary  to  also  specify  the  -x
253              option.
254
255       -X, --pdi
256              The target device is an ATxmega part, using PDI transport.
257              NOTE:  Current,  if  the  target device doesn't have an extended
258              fuse byte (e.g. the atmega16), the you should  set  ee==ll  when
259              writing the fuse bytes.
260
261       HOST_NAME defaults to 0.0.0.0 (listen on any interface) if not given.
262
263       :PORT is required to put avarice into gdb server mode.
264

EXAMPLE USAGE

266       avarice --erase --program --file test.bin --jtag /dev/ttyS0 :4242
267
268       Program  the  file  test.bin  into  the  JTAG  ICE  (mkI)  connected to
269       /dev/ttyS0 after erasing the device, then listen in  GDB  mode  on  the
270       local port 4242.
271
272       avarice --jtag usb:1234 --mkII :4242
273
274       Connect  to  the JTAG ICE mkII attached to USB which serial number ends
275       in 1234, and listen in GDB mode on local port 4242.
276

DEBUGGING WITH AVARICE

278       The JTAG ICE debugging environment has a few restrictions and changes:
279
280       ·   No "soft" breakpoints, and only  three  hardware  breakpoints.  The
281           break  command  sets  hardware breakpoints. The easiest way to deal
282           with this restriction is  to  enable  and  disable  breakpoints  as
283           needed.
284
285       ·   Two 1-byte hardware watchpoints (but each hardware watchpoint takes
286           away one hardware breakpoint). If you set a watchpoint on  a  vari‐
287           able  which  takes  more than one byte, execution will be abysmally
288           slow. Instead it is better to do the following:
289
290             watch *(char *)&myvariable
291
292           which watches the least significant byte of myvariable.
293
294       ·   The Atmel AVR processors have a Harvard architecture (separate code
295           and data buses). To distinguish data address 0 from code address 0,
296           avr-gdb adds 0x800000 to all data addresses. Bear this in mind when
297           examining  printed  pointers, or when passing absolute addresses to
298           gdb commands.
299

DEBUGWIRE

301       The debugWire protocol is a proprietary protocol introduced by Atmel to
302       allow debugging small AVR controllers that don't offer enough pins (and
303       enough chip resources) to implement full JTAG.  The communication takes
304       place  over  the  /RESET  pin which needs to be turned into a debugWire
305       connection pin by programming the DWEN fuse (debugWire enable), using a
306       normal  programmer connection (in-system programming, high-voltage pro‐
307       gramming).  Note that by enabling this fuse, the standard  reset  func‐
308       tionality  of  that pin will be lost, so any in-system programming will
309       cease to work as it requires a functional /RESET pin.  Thus  it  should
310       be  made  absolutely  sure  there  is a way back, like a device (as the
311       STK500, for example) that can handle high-voltage  programming  of  the
312       AVR.   Currently,  avarice  offers no option to turn off the DWEN fuse.
313       However, avrdude offers the option to turn it off either through  high-
314       voltage  programming,  or  by using the JTAG ICE mkII to first turn the
315       target into an ISP-compatible mode, and then using normal ISP  commands
316       to change the fuse settings.
317       Note  that  the  debugWire  environment is further limited, compared to
318       JTAG.  It does not offer hardware breakpoints, so all breakpoints  have
319       to  be  implemented  as  software  breakpoints by rewriting flash pages
320       using BREAK instructions.  Some memory spaces (fuse and lock bits)  are
321       not accessible through the debugWire protocol.
322

SEE ALSO

324       gdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),
325       ice-insight(1)
326

AUTHORS

328       Avarice (up to version 1.5) was originally written  by  Scott  Finneran
329       with  help  from  Peter  Jansen.  They did the work of figuring out the
330       jtagice communication protocol before Atmel released the spec  (appnote
331       AVR060).
332
333       David Gay made major improvements bringing avarice up to 2.0.
334
335       Joerg  Wunsch  reworked the code to abstract the JTAG ICE communication
336       from the remainder, and then extended the code to support the JTAG  ICE
337       mkII protocol (see Atmel appnote AVR067).
338
339
340
341                               December 15, 2011                    avarice(1)
Impressum