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 atmega16
35 atmega162
36 atmega169
37 atmega323
38 atmega32
39 atmega64
40 atmega128
41 at90can128
42 atmega164p (o)
43 atmega324p (o)
44 atmega644 (*)
45 atmega329 (o)
46 atmega3290 (o)
47 atmega649 (*)
48 atmega6490 (*)
49 atmega640 (*)
50 atmega1280 (*)
51 atmega1281 (*)
52 atmega2560 (*)
53 atmega2561 (*)
54 at90usb1287 (*)
55 atmega48 (o) (+)
56 atmega88 (o) (+)
57 atmega168 (o) (+)
58 attiny13 (o) (+)
59 attiny2313 (o) (+)
60 at90pwm2 (o) (+)
61 at90pwm3 (o) (+)
62 attiny24 (o) (+)
63 attiny44 (o) (+)
64 attiny25 (o) (+)
65 attiny45 (o) (+)
66 attiny261 (o) (+)
67 attiny461 (o) (+)
68 attiny861 (o) (+)
69 * - Only supported by the JTAG ICE mkII device.
71 o - Only supported by the JTAG ICE mkII and AVR Dragon device.
72 + - debugWire, see below
73 Supported File Formats
75 avarice uses libbfd for reading input files. As such, it can handle any
76 file format that libbfd knowns about. This includes the Intel Hex,
77 Motorola SRecord and ELF formats, among others. If you tell avarice to
78 read an ELF file, it will automatically handle programming all of the
79 sections contained in the file (e.g. flash, eeprom, etc.).
80
82 -h, --help
83 Print this message.
84 -1, --mkI
86 Connect to JTAG ICE mkI (default).
87 -2, --mkII
89 Connect to JTAG ICE mkII.
90 -B, --jtag-bitrate <rate>
92 Set the bitrate that the JTAG box communicates with the AVR tar‐
93 get device. This must be less than 1/4 of the frequency of the
94 target. Valid values are 1 MHz, 500 kHz, 250 kHz or 125 kHz for
95 the JTAG ICE mkI, anything between 22 kHz through approximately
96 6400 kHz for the JTAG ICE mkII. (default: 1 MHz)
97 -C, --capture
99 Capture running program.
100 Note: debugging must have been enabled prior to starting the
101 program. (e.g., by running avarice earlier)
102 -c, --daisy-chain <ub,ua,bb,ba>
104 Setup JTAG daisy-chain information.
105 Four comma-separated parameters need to be provided, correspond‐
106 ing to units before, units after, bits before, and bits after.
107 -D, --detach
109 Detach once synced with JTAG ICE
110 -d, --debug
112 Enable printing of debug information.
113 -e, --erase
115 Erase target.
116 -f, --file <filename>
118 Specify a file for use with the --program and --verify options.
119 If --file is passed and neither --program or --verify are given
120 then --program is implied.
121 -g, --dragon
123 Connect to an AVR Dragon. This option implies the -2 option.
124 -I, --ignore-intr
126 Automatically step over interrupts.
127 Note: EXPERIMENTAL. Can not currently handle devices fused for
128 compatibility.
129 -j, --jtag <devname>
131 Port attached to JTAG box (default: /dev/avrjtag).
132 If avarice has been configured with libusb support, the JTAG ICE
133 mkII can be connected through USB. In that case, the string usb
134 is used as the name of the device. If there are multiple JTAG
135 ICE mkII devices connected to the system through USB, this
136 string may be followed by the (trailing part of the) ICE's
137 serial number, delimited from the usb by a colon.
138 The AVR Dragon can only be connected through USB, so this option
139 defaults to "usb" in that case.
140 -L, --write-lockbits <ll>
142 Write lock bits. The lock byte data must be given in two digit
143 hexidecimal format with zero padding if needed.
144 -l, --read-lockbits
146 Read the lock bits from the target. The individual bits are also
147 displayed with names.
148 -P, --part <name>
150 Target device name (e.g. atmega16)
151 -p, --program
153 Program the target. Binary filename must be specified with
154 --file option.
155 NOTE: The old behaviour of automatically erasing the target
156 before programming is no longer done. You must explicitly give
157 the --erase option for the target to be erased.
158 -r, --read-fuses
160 Read fuses bytes.
161 -V, --version
163 Print version information.
164 -v, --verify
166 Verify program in device against file specified with --file
167 option.
168 -w, --debugwire
170 Connect to JTAG ICE mkII (or AVR Dragon), talking debugWire pro‐
171 tocol to the target. This option implies the -2 option. See
172 the DEBUGWIRE section below.
173 -W, --write-fuses <eehhll>
175 Write fuses bytes. ee is the extended fuse byte, hh is the high
176 fuse byte and ll is the low fuse byte. The fuse byte data must
177 be given in two digit hexidecimal format with zero padding if
178 needed. All three bytes must currently be given.
179 NOTE: Current, if the target device doesn't have an extended
180 fuse byte (e.g. the atmega16), the you should set ee==ll when
181 writing the fuse bytes.
182 HOST_NAME defaults to 0.0.0.0 (listen on any interface) if not given.
184 :PORT is required to put avarice into gdb server mode.
186
188 avarice --erase --program --file test.bin --jtag /dev/ttyS0 :4242
189 Program the file test.bin into the JTAG ICE (mkI) connected to
191 /dev/ttyS0 after erasing the device, then listen in GDB mode on the
192 local port 4242.
193 avarice --jtag usb:1234 --mkII :4242
195 Connect to the JTAG ICE mkII attached to USB which serial number ends
197 in 1234, and listen in GDB mode on local port 4242.
198
200 The JTAG ICE debugging environment has a few restrictions and changes:
201 · No "soft" breakpoints, and only three hardware breakpoints. The
203 break command sets hardware breakpoints. The easiest way to deal
204 with this restriction is to enable and disable breakpoints as
205 needed.
206 · Two 1-byte hardware watchpoints (but each hardware watchpoint takes
208 away one hardware breakpoint). If you set a watchpoint on a vari‐
209 able which takes more than one byte, execution will be abysmally
210 slow. Instead it is better to do the following:
211 watch *(char *)&myvariable
213 which watches the least significant byte of myvariable.
215 · The Atmel AVR processors have a Harvard architecture (separate code
217 and data buses). To distinguish data address 0 from code address 0,
218 avr-gdb adds 0x800000 to all data addresses. Bear this in mind when
219 examining printed pointers, or when passing absolute addresses to
220 gdb commands.
221
223 The debugWire protocol is a proprietary protocol introduced by Atmel to
224 allow debugging small AVR controllers that don't offer enough pins (and
225 enough chip resources) to implement full JTAG. The communication takes
226 place over the /RESET pin which needs to be turned into a debugWire
227 connection pin by programming the DWEN fuse (debugWire enable), using a
228 normal programmer connection (in-system programming, high-voltage pro‐
229 gramming). Note that by enabling this fuse, the standard reset func‐
230 tionality of that pin will be lost, so any in-system programming will
231 cease to work as it requires a functional /RESET pin. Thus it should
232 be made absolutely sure there is a way back, like a device (as the
233 STK500, for example) that can handle high-voltage programming of the
234 AVR. Currently, avarice offers no option to turn off the DWEN fuse.
235 However, avrdude offers the option to turn it off either through high-
236 voltage programming, or by using the JTAG ICE mkII to first turn the
237 target into an ISP-compatible mode, and then using normal ISP commands
238 to change the fuse settings.
239 Note that the debugWire environment is further limited, compared to
240 JTAG. It does not offer hardware breakpoints, so all breakpoints have
241 to be implemented as software breakpoints by rewriting flash pages
242 using BREAK instructions. (Software breakpoints are currently not
243 implemented by avarice.) Some memory spaces (fuse and lock bits) are
244 not accessible through the debugWire protocol.
245
247 gdb(1), avrdude(1), avr-gdb(1), insight(1), avr-insight(1), ice-gdb(1),
248 ice-insight(1)
249
251 Avarice (up to version 1.5) was originally written by Scott Finneran
252 with help from Peter Jansen. They did the work of figuring out the
253 jtagice communication protocol before Atmel released the spec (appnote
254 AVR060).
255 David Gay made major improvements bringing avarice up to 2.0.
257 Joerg Wunsch reworked the code to abstract the JTAG ICE communication
259 from the remainder, and then extended the code to support the JTAG ICE
260 mkII protocol (see Atmel appnote AVR067).
261 August 5, 2006 avarice(1)