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 (*)
44 at90usb162 (o) (+)
45 at90usb646 (*)
46 at90usb647 (*)
47 atmega128
48 atmega1280 (*)
49 atmega1281 (*)
50 atmega1284p (*)
51 atmega16
52 atmega162
53 atmega164p (o)
54 atmega165 (o)
55 atmega165p (o)
56 atmega168 (o) (+)
57 atmega168p (o) (+)
58 atmega169
59 atmega16hva (o)
60 atmega2560 (*)
61 atmega2561 (*)
62 atmega32
63 atmega323
64 atmega324p (o)
65 atmega325 (o)
66 atmega3250 (o)
67 atmega3250p (o)
68 atmega325p (o)
69 atmega328p (o) (+)
70 atmega329 (o)
71 atmega3290 (o)
72 atmega3290p (o)
73 atmega329p (o)
74 atmega32c1 (o) (+)
75 atmega32hvb (o) (+)
76 atmega32m1 (o) (+)
77 atmega32u4 (o)
78 atmega406 (*)
79 atmega48 (o) (+)
80 atmega48p (o) (+)
81 atmega64
82 atmega640 (*)
83 atmega644 (*)
84 atmega644p (*)
85 atmega645 (*)
86 atmega6450 (*)
87 atmega649 (*)
88 atmega6490 (*)
89 atmega88 (o) (+)
90 atmega88p (o) (+)
91 attiny13 (o) (+)
92 attiny167 (o) (+)
93 attiny2313 (o) (+)
94 attiny24 (o) (+)
95 attiny25 (o) (+)
96 attiny261 (o) (+)
97 attiny43u (o) (+)
98 attiny44 (o) (+)
99 attiny45 (o) (+)
100 attiny461 (o) (+)
101 attiny48 (o) (+)
102 attiny84 (o) (+)
103 attiny85 (o) (+)
104 attiny861 (o) (+)
105 attiny88 (o) (+)
106 atxmega128a1 (*)
107 * - Only supported by the JTAG ICE mkII device.
109 o - Only supported by the JTAG ICE mkII and AVR Dragon device.
110 + - debugWire, see below
111 Supported File Formats
113 avarice uses libbfd for reading input files. As such, it can handle any
114 file format that libbfd knowns about. This includes the Intel Hex,
115 Motorola SRecord and ELF formats, among others. If you tell avarice to
116 read an ELF file, it will automatically handle programming all of the
117 sections contained in the file (e.g. flash, eeprom, etc.).
118
120 -h, --help
121 Print this message.
122 -1, --mkI
124 Connect to JTAG ICE mkI (default).
125 -2, --mkII
127 Connect to JTAG ICE mkII.
128 -B, --jtag-bitrate <rate>
130 Set the bitrate that the JTAG box communicates with the AVR tar‐
131 get device. This must be less than 1/4 of the frequency of the
132 target. Valid values are 1 MHz, 500 kHz, 250 kHz or 125 kHz for
133 the JTAG ICE mkI, anything between 22 kHz through approximately
134 6400 kHz for the JTAG ICE mkII. (default: 250 kHz)
135 -C, --capture
137 Capture running program.
138 Note: debugging must have been enabled prior to starting the
139 program. (e.g., by running avarice earlier)
140 -c, --daisy-chain <ub,ua,bb,ba>
142 Setup JTAG daisy-chain information.
143 Four comma-separated parameters need to be provided, correspond‐
144 ing to units before, units after, bits before, and bits after.
145 -D, --detach
147 Detach once synced with JTAG ICE
148 -d, --debug
150 Enable printing of debug information.
151 -e, --erase
153 Erase target. Not possible in debugWire mode.
154 -E, --event <eventlist>
156 List of events that do not interrupt. JTAG ICE mkII and AVR
157 Dragon only. Default is "none,run,target_power_on,tar‐
158 get_sleep,target_wakeup"
159 -f, --file <filename>
161 Specify a file for use with the --program and --verify options.
162 If --file is passed and neither --program or --verify are given
163 then --program is implied.
164 -g, --dragon
166 Connect to an AVR Dragon. This option implies the -2 option.
167 -I, --ignore-intr
169 Automatically step over interrupts.
170 Note: EXPERIMENTAL. Can not currently handle devices fused for
171 compatibility.
172 -j, --jtag <devname>
174 Port attached to JTAG box (default: /dev/avrjtag). If the
175 JTAG_DEV environmental variable is set, avarice will use that as
176 the default instead.
177 If avarice has been configured with libusb support, the JTAG ICE
178 mkII can be connected through USB. In that case, the string usb
179 is used as the name of the device. If there are multiple JTAG
180 ICE mkII devices connected to the system through USB, this
181 string may be followed by the (trailing part of the) ICE's
182 serial number, delimited from the usb by a colon.
183 The AVR Dragon can only be connected through USB, so this option
184 defaults to "usb" in that case.
185 -k, --known-devices
187 Print a list of known devices.
188 -L, --write-lockbits <ll>
190 Write lock bits. The lock byte data must be given in two digit
191 hexidecimal format with zero padding if needed.
192 -l, --read-lockbits
194 Read the lock bits from the target. The individual bits are also
195 displayed with names.
196 -P, --part <name>
198 Target device name (e.g. atmega16)
199 -p, --program
201 Program the target. Binary filename must be specified with
202 --file option.
203 NOTE: The old behaviour of automatically erasing the target
204 before programming is no longer done. You must explicitly give
205 the --erase option for the target to be erased.
206 -R, --reset-srst
208 Apply nSRST signal (external reset) when connecting. This can
209 override applications that set the JTD bit.
210 -r, --read-fuses
212 Read fuses bytes.
213 -V, --version
215 Print version information.
216 -v, --verify
218 Verify program in device against file specified with --file
219 option.
220 -w, --debugwire
222 Connect to JTAG ICE mkII (or AVR Dragon), talking debugWire pro‐
223 tocol to the target. This option implies the -2 option. See
224 the DEBUGWIRE section below.
225 -W, --write-fuses <eehhll>
227 Write fuses bytes. ee is the extended fuse byte, hh is the high
228 fuse byte and ll is the low fuse byte. The fuse byte data must
229 be given in two digit hexidecimal format with zero padding if
230 needed. All three bytes must currently be given.
231 -x, --xmega
233 The target device is an ATxmega part. Since the ATxmega uses a
234 different JTAG communication than other AVRs, the normal device
235 autodetection based on the JTAG ID does not work. If the device
236 has been explicitly selected through the -P option, it is not
237 necessary to also specify the -x option.
238 NOTE: Current, if the target device doesn't have an extended
239 fuse byte (e.g. the atmega16), the you should set ee==ll when
240 writing the fuse bytes.
241 HOST_NAME defaults to 0.0.0.0 (listen on any interface) if not given.
243 :PORT is required to put avarice into gdb server mode.
245
247 avarice --erase --program --file test.bin --jtag /dev/ttyS0 :4242
248 Program the file test.bin into the JTAG ICE (mkI) connected to
250 /dev/ttyS0 after erasing the device, then listen in GDB mode on the
251 local port 4242.
252 avarice --jtag usb:1234 --mkII :4242
254 Connect to the JTAG ICE mkII attached to USB which serial number ends
256 in 1234, and listen in GDB mode on local port 4242.
257
259 The JTAG ICE debugging environment has a few restrictions and changes:
260 · No "soft" breakpoints, and only three hardware breakpoints. The
262 break command sets hardware breakpoints. The easiest way to deal
263 with this restriction is to enable and disable breakpoints as
264 needed.
265 · Two 1-byte hardware watchpoints (but each hardware watchpoint takes
267 away one hardware breakpoint). If you set a watchpoint on a vari‐
268 able which takes more than one byte, execution will be abysmally
269 slow. Instead it is better to do the following:
270 watch *(char *)&myvariable
272 which watches the least significant byte of myvariable.
274 · The Atmel AVR processors have a Harvard architecture (separate code
276 and data buses). To distinguish data address 0 from code address 0,
277 avr-gdb adds 0x800000 to all data addresses. Bear this in mind when
278 examining printed pointers, or when passing absolute addresses to
279 gdb commands.
280
282 The debugWire protocol is a proprietary protocol introduced by Atmel to
283 allow debugging small AVR controllers that don't offer enough pins (and
284 enough chip resources) to implement full JTAG. The communication takes
285 place over the /RESET pin which needs to be turned into a debugWire
286 connection pin by programming the DWEN fuse (debugWire enable), using a
287 normal programmer connection (in-system programming, high-voltage pro‐
288 gramming). Note that by enabling this fuse, the standard reset func‐
289 tionality of that pin will be lost, so any in-system programming will
290 cease to work as it requires a functional /RESET pin. Thus it should
291 be made absolutely sure there is a way back, like a device (as the
292 STK500, for example) that can handle high-voltage programming of the
293 AVR. Currently, avarice offers no option to turn off the DWEN fuse.
294 However, avrdude offers the option to turn it off either through high-
295 voltage programming, or by using the JTAG ICE mkII to first turn the
296 target into an ISP-compatible mode, and then using normal ISP commands
297 to change the fuse settings.
298 Note that the debugWire environment is further limited, compared to
299 JTAG. It does not offer hardware breakpoints, so all breakpoints have
300 to be implemented as software breakpoints by rewriting flash pages
301 using BREAK instructions. (Software breakpoints are currently not
302 implemented by avarice.) Some memory spaces (fuse and lock bits) are
303 not accessible through the debugWire protocol.
304
306 gdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),
307 ice-insight(1)
308
310 Avarice (up to version 1.5) was originally written by Scott Finneran
311 with help from Peter Jansen. They did the work of figuring out the
312 jtagice communication protocol before Atmel released the spec (appnote
313 AVR060).
314 David Gay made major improvements bringing avarice up to 2.0.
316 Joerg Wunsch reworked the code to abstract the JTAG ICE communication
318 from the remainder, and then extended the code to support the JTAG ICE
319 mkII protocol (see Atmel appnote AVR067).
320 September 29, 2008 avarice(1)