1avarice(1) General Commands Manual avarice(1)
2
6 avarice - Provides an interface from avr-gdb to Atmel's JTAGICE box.
7
9 avarice [OPTIONS]... [[HOST_NAME]:PORT]
10
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 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 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 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 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 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 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
134 -h, --help
135 Print this message.
136 -1, --mkI
138 Connect to JTAG ICE mkI (default).
139 -2, --mkII
141 Connect to JTAG ICE mkII.
142 -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 -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 -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 -D, --detach
161 Detach once synced with JTAG ICE
162 -d, --debug
164 Enable printing of debug information.
165 -e, --erase
167 Erase target. Not possible in debugWire mode.
168 -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 -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 -g, --dragon
182 Connect to an AVR Dragon. This option implies the -2 option.
183 -I, --ignore-intr
185 Automatically step over interrupts.
186 -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 -k, --known-devices
201 Print a list of known devices.
202 -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 -l, --read-lockbits
208 Read the lock bits from the target. The individual bits are also
209 displayed with names.
210 -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 -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 -R, --reset-srst
222 Apply nSRST signal (external reset) when connecting. This can
223 override applications that set the JTD bit.
224 -r, --read-fuses
226 Read fuses bytes.
227 -V, --version
229 Print version information.
230 -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 -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 -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 -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 -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 HOST_NAME defaults to 0.0.0.0 (listen on any interface) if not given.
262 :PORT is required to put avarice into gdb server mode.
264
266 avarice --erase --program --file test.bin --jtag /dev/ttyS0 :4242
267 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 avarice --jtag usb:1234 --mkII :4242
273 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
278 The JTAG ICE debugging environment has a few restrictions and changes:
279 · 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 · 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 watch *(char *)&myvariable
291 which watches the least significant byte of myvariable.
293 · 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
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
324 gdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),
325 ice-insight(1)
326
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 David Gay made major improvements bringing avarice up to 2.0.
334 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 December 15, 2011 avarice(1)