openocd.texi 286 KB
Newer Older
zwelch's avatar
zwelch committed
1
\input texinfo @c -*-texinfo-*-
ntfreak's avatar
ntfreak committed
2
3
@c %**start of header
@setfilename openocd.info
zwelch's avatar
zwelch committed
4
@settitle OpenOCD User's Guide
ntfreak's avatar
ntfreak committed
5
6
@dircategory Development
@direntry
zwelch's avatar
zwelch committed
7
* OpenOCD: (openocd).      OpenOCD User's Guide
ntfreak's avatar
ntfreak committed
8
@end direntry
zwelch's avatar
zwelch committed
9
@paragraphindent 0
ntfreak's avatar
ntfreak committed
10
11
12
13
@c %**end of header

@include version.texi

ntfreak's avatar
ntfreak committed
14
@copying
15

zwelch's avatar
zwelch committed
16
17
18
19
20
This User's Guide documents
release @value{VERSION},
dated @value{UPDATED},
of the Open On-Chip Debugger (OpenOCD).

21
22
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
23
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
24
25
@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
26
@item Copyright @copyright{} 2009-2010 David Brownell
27
28
@end itemize

ntfreak's avatar
ntfreak committed
29
30
31
32
33
34
35
36
37
38
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

ntfreak's avatar
ntfreak committed
39
@titlepage
zwelch's avatar
zwelch committed
40
41
42
43
@titlefont{@emph{Open On-Chip Debugger:}}
@sp 1
@title OpenOCD User's Guide
@subtitle for release @value{VERSION}
ntfreak's avatar
ntfreak committed
44
@subtitle @value{UPDATED}
zwelch's avatar
zwelch committed
45

ntfreak's avatar
ntfreak committed
46
47
@page
@vskip 0pt plus 1filll
ntfreak's avatar
ntfreak committed
48
@insertcopying
ntfreak's avatar
ntfreak committed
49
50
@end titlepage

51
@summarycontents
ntfreak's avatar
ntfreak committed
52
53
@contents

zwelch's avatar
zwelch committed
54
55
56
@ifnottex
@node Top
@top OpenOCD User's Guide
ntfreak's avatar
ntfreak committed
57
58

@insertcopying
zwelch's avatar
zwelch committed
59
@end ifnottex
ntfreak's avatar
ntfreak committed
60
61

@menu
oharboe's avatar
oharboe committed
62
* About::                            About OpenOCD
63
* Developers::                       OpenOCD Developer Resources
64
* JTAG Hardware Dongles::            JTAG Hardware Dongles
zwelch's avatar
zwelch committed
65
* About JIM-Tcl::                    About JIM-Tcl
66
* Running::                          Running OpenOCD
zwelch's avatar
zwelch committed
67
* OpenOCD Project Setup::            OpenOCD Project Setup
68
69
70
71
* Config File Guidelines::           Config File Guidelines
* Daemon Configuration::             Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration::              Reset Configuration
zwelch's avatar
zwelch committed
72
* TAP Declaration::                  TAP Declaration
zwelch's avatar
zwelch committed
73
* CPU Configuration::                CPU Configuration
zwelch's avatar
zwelch committed
74
* Flash Commands::                   Flash Commands
75
* NAND Flash Commands::              NAND Flash Commands
zwelch's avatar
zwelch committed
76
* PLD/FPGA Commands::                PLD/FPGA Commands
77
* General Commands::                 General Commands
zwelch's avatar
zwelch committed
78
* Architecture and Core Commands::   Architecture and Core Commands
79
* JTAG Commands::                    JTAG Commands
80
* Boundary Scan Commands::           Boundary Scan Commands
81
82
* TFTP::                             TFTP
* GDB and OpenOCD::                  Using GDB and OpenOCD
ntfreak's avatar
ntfreak committed
83
* Tcl Scripting API::                Tcl Scripting API
84
* FAQ::                              Frequently Asked Questions
ntfreak's avatar
ntfreak committed
85
* Tcl Crash Course::                 Tcl Crash Course
86
* License::                          GNU Free Documentation License
zwelch's avatar
zwelch committed
87

88
89
90
91
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
92
* OpenOCD Concept Index::            Concept Index
zwelch's avatar
zwelch committed
93
* Command and Driver Index::         Command and Driver Index
ntfreak's avatar
ntfreak committed
94
95
96
97
98
99
@end menu

@node About
@unnumbered About
@cindex about

zwelch's avatar
zwelch committed
100
101
102
103
104
105
106
OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
Since that time, the project has grown into an active open-source project,
supported by a diverse community of software and hardware developers from
around the world.

@section What is OpenOCD?
zwelch's avatar
zwelch committed
107
108
@cindex TAP
@cindex JTAG
zwelch's avatar
zwelch committed
109

110
111
112
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
devices.
ntfreak's avatar
ntfreak committed
113

114
@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
zwelch's avatar
zwelch committed
115
116
117
118
with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
A @dfn{TAP} is a ``Test Access Port'', a module which processes
special instructions and data.  TAPs are daisy-chained within and
between chips and boards.
ntfreak's avatar
ntfreak committed
119

ntfreak's avatar
ntfreak committed
120
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
oharboe's avatar
oharboe committed
121
based, parallel port based, and other standalone boxes that run
zwelch's avatar
zwelch committed
122
OpenOCD internally. @xref{JTAG Hardware Dongles}.
123

ntfreak's avatar
ntfreak committed
124
125
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
zwelch's avatar
zwelch committed
126
Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
oharboe's avatar
oharboe committed
127
debugged via the GDB protocol.
128
129

@b{Flash Programing:} Flash writing is supported for external CFI
130
compatible NOR flashes (Intel and AMD/Spansion command set) and several
131
internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
132
133
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
ntfreak's avatar
ntfreak committed
134

zwelch's avatar
zwelch committed
135
136
137
138
139
140
@section OpenOCD Web Site

The OpenOCD web site provides the latest public news from the community:

@uref{http://openocd.berlios.de/web/}

zwelch's avatar
zwelch committed
141
142
143
144
145
146
@section Latest User's Guide:

The user's guide you are now reading may not be the latest one
available.  A version for more recent code may be available.
Its HTML form is published irregularly at:

ntfreak's avatar
ntfreak committed
147
@uref{http://openocd.berlios.de/doc/html/index.html}
zwelch's avatar
zwelch committed
148
149
150

PDF form is likewise published at:

ntfreak's avatar
ntfreak committed
151
@uref{http://openocd.berlios.de/doc/pdf/openocd.pdf}
zwelch's avatar
zwelch committed
152
153
154

@section OpenOCD User's Forum

155
156
157
158
159
There is an OpenOCD forum (phpBB) hosted by SparkFun,
which might be helpful to you.  Note that if you want
anything to come to the attention of developers, you
should post it to the OpenOCD Developer Mailing List
instead of this forum.
zwelch's avatar
zwelch committed
160
161
162

@uref{http://forum.sparkfun.com/viewforum.php?f=18}

zwelch's avatar
zwelch committed
163

ntfreak's avatar
ntfreak committed
164
@node Developers
zwelch's avatar
zwelch committed
165
@chapter OpenOCD Developer Resources
ntfreak's avatar
ntfreak committed
166
167
@cindex developers

zwelch's avatar
zwelch committed
168
169
170
171
If you are interested in improving the state of OpenOCD's debugging and
testing support, new contributions will be welcome.  Motivated developers
can produce new target, flash or interface drivers, improve the
documentation, as well as more conventional bug fixes and enhancements.
ntfreak's avatar
ntfreak committed
172

zwelch's avatar
zwelch committed
173
174
The resources in this chapter are available for developers wishing to explore
or expand the OpenOCD source code.
ntfreak's avatar
ntfreak committed
175

176
@section OpenOCD GIT Repository
177

178
179
During the 0.3.x release cycle, OpenOCD switched from Subversion to
a GIT repository hosted at SourceForge.  The repository URL is:
180

181
@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
182

David Brownell's avatar
David Brownell committed
183
184
185
186
You may prefer to use a mirror and the HTTP protocol:

@uref{http://repo.or.cz/r/openocd.git}

187
188
189
190
191
With standard GIT tools, use @command{git clone} to initialize
a local repository, and @command{git pull} to update it.
There are also gitweb pages letting you browse the repository
with a web browser, or download arbitrary snapshots without
needing a GIT client:
192

193
@uref{http://openocd.git.sourceforge.net/git/gitweb.cgi?p=openocd/openocd}
194

David Brownell's avatar
David Brownell committed
195
196
@uref{http://repo.or.cz/w/openocd.git}

197
198
The @file{README} file contains the instructions for building the project
from the repository or a snapshot.
ntfreak's avatar
ntfreak committed
199

zwelch's avatar
zwelch committed
200
Developers that want to contribute patches to the OpenOCD system are
201
202
@b{strongly} encouraged to work against mainline.
Patches created against older versions may require additional
zwelch's avatar
zwelch committed
203
work from their submitter in order to be updated for newer releases.
ntfreak's avatar
ntfreak committed
204

zwelch's avatar
zwelch committed
205
@section Doxygen Developer Manual
ntfreak's avatar
ntfreak committed
206

207
During the 0.2.x release cycle, the OpenOCD project began
zwelch's avatar
zwelch committed
208
209
210
providing a Doxygen reference manual.  This document contains more
technical information about the software internals, development
processes, and similar documentation:
ntfreak's avatar
ntfreak committed
211

zwelch's avatar
zwelch committed
212
213
214
215
@uref{http://openocd.berlios.de/doc/doxygen/index.html}

This document is a work-in-progress, but contributions would be welcome
to fill in the gaps.  All of the source files are provided in-tree,
216
listed in the Doxyfile configuration in the top of the source tree.
zwelch's avatar
zwelch committed
217
218
219
220
221
222

@section OpenOCD Developer Mailing List

The OpenOCD Developer Mailing List provides the primary means of
communication between developers:

zwelch's avatar
zwelch committed
223
@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
zwelch's avatar
zwelch committed
224

225
Discuss and submit patches to this list.
226
The @file{PATCHES.txt} file contains basic information about how
227
to prepare patches.
zwelch's avatar
zwelch committed
228

229
230
231
232
233
234
235
@section OpenOCD Bug Database

During the 0.4.x release cycle the OpenOCD project team began
using Trac for its bug database:

@uref{https://sourceforge.net/apps/trac/openocd}

ntfreak's avatar
ntfreak committed
236

237
238
239
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@cindex dongles
ntfreak's avatar
ntfreak committed
240
@cindex FTDI
241
242
243
@cindex wiggler
@cindex zy1000
@cindex printer port
ntfreak's avatar
ntfreak committed
244
@cindex USB Adapter
zwelch's avatar
zwelch committed
245
@cindex RTCK
246
247
248
249
250
251
252

Defined: @b{dongle}: A small device that plugins into a computer and serves as
an adapter .... [snip]

In the OpenOCD case, this generally refers to @b{a small adapater} one
attaches to your computer via USB or the Parallel Printer Port.  The
execption being the Zylin ZY1000 which is a small box you attach via
253
254
255
256
an ethernet cable. The Zylin ZY1000 has the advantage that it does not
require any drivers to be installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
257
258
259
260


@section Choosing a Dongle

261
There are several things you should keep in mind when choosing a dongle.
262

263
@enumerate
264
265
266
267
268
269
270
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
Does your dongle support it?  You might need a level converter.
@item @b{Pinout} What pinout does your target board use?
Does your dongle support it?  You may be able to use jumper
wires, or an "octopus" connector, to convert pinouts.
@item @b{Connection} Does your computer have the USB, printer, or
Ethernet port needed?
271
@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
272
273
274
275
276
@end enumerate

@section Stand alone Systems

@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
277
278
279
280
dongle, but a standalone box. The ZY1000 has the advantage that it does
not require any drivers installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
and has a built in relay to power cycle targets remotely.
281
282
283

@section USB FT2232 Based

ntfreak's avatar
ntfreak committed
284
There are many USB JTAG dongles on the market, many of them are based
285
on a chip from ``Future Technology Devices International'' (FTDI)
zwelch's avatar
zwelch committed
286
287
288
289
known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
See: @url{http://www.ftdichip.com} for more information.
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
chips are starting to become available in JTAG adapters.
290
291
292

@itemize @bullet
@item @b{usbjtag}
293
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
294
295
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
296
297
@item @b{jtagkey2}
@* See: @url{http://www.amontec.com/jtagkey2.shtml}
298
@item @b{oocdlink}
duane's avatar
duane committed
299
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
300
301
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
302
303
304
305
306
307
308
309
310
311
312
@item @b{Stellaris Eval Boards}
@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
bundle FT2232-based JTAG and SWD support, which can be used to debug
the Stellaris chips.  Using separate JTAG adapters is optional.
These boards can also be used as JTAG adapters to other target boards,
disabling the Stellaris chip.
@item @b{Luminary ICDI}
@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
Evaluation Kits.  Like the non-detachable FT2232 support on the other
Stellaris eval boards, they can be used to debug other target boards.
313
314
315
316
317
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
zwelch's avatar
zwelch committed
318
319
320
@* See:
@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
@url{http://www.ethernut.de}
321
322
323
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
ntfreak's avatar
ntfreak committed
324
325
326
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
@* Axiom AXM-0432 Link @url{http://www.axman.com}
327
328
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
329
330
@end itemize

331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@section USB-JTAG / Altera USB-Blaster compatibles

These devices also show up as FTDI devices, but are not
protocol-compatible with the FT2232 devices. They are, however,
protocol-compatible among themselves.  USB-JTAG devices typically consist
of a FT245 followed by a CPLD that understands a particular protocol,
or emulate this protocol using some other hardware.

They may appear under different USB VID/PID depending on the particular
product.  The driver can be configured to search for any VID/PID pair
(see the section on driver commands).

@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
@* Link: @url{http://www.ixo.de/info/usb_jtag/}
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize

350
351
352
353
354
355
356
357
358
359
360
361
362
363
@section USB JLINK based
There are several OEM versions of the Segger @b{JLINK} adapter. It is
an example of a micro controller based JTAG adapter, it uses an
AT91SAM764 internally.

@itemize @bullet
@item @b{ATMEL SAMICE} Only works with ATMEL chips!
@* Link: @url{http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3892}
@item @b{SEGGER JLINK}
@* Link: @url{http://www.segger.com/jlink.html}
@item @b{IAR J-Link}
@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
@end itemize

364
365
366
367
368
369
370
371
372
373
374
375
@section USB RLINK based
Raisonance has an adapter called @b{RLink}.  It exists in a stripped-down form on the STM32 Primer, permanently attached to the JTAG lines.  It also exists on the STM32 Primer2, but that is wired for SWD and not JTAG, thus not supported.

@itemize @bullet
@item @b{Raisonance RLink}
@* Link: @url{http://www.raisonance.com/products/RLink.php}
@item @b{STM32 Primer}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
@item @b{STM32 Primer2}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
@end itemize

376
377
378
379
380
@section USB Other
@itemize @bullet
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604

381
@item @b{USB - Presto}
382
@* Link: @url{http://tools.asix.net/prg_presto.htm}
duane's avatar
duane committed
383
384
385

@item @b{Versaloon-Link}
@* Link: @url{http://www.simonqian.com/en/Versaloon}
386
387
388

@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
389
390
391
392
393
394
395
396
@end itemize

@section IBM PC Parallel Printer Port Based

The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
and the MacGraigor Wiggler. There are many clones and variations of
these on the market.

397
398
399
400
Note that parallel ports are becoming much less common, so if you
have the choice you should probably avoid these adapters in favor
of USB-based ones.

401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
@itemize @bullet

@item @b{Wiggler} - There are many clones of this.
@* Link: @url{http://www.macraigor.com/wiggler.htm}

@item @b{DLC5} - From XILINX - There are many clones of this
@* Link: Search the web for: ``XILINX DLC5'' - it is no longer
produced, PDF schematics are easily found and it is easy to make.

@item @b{Amontec - JTAG Accelerator}
@* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}

@item @b{GW16402}
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}

@item @b{Wiggler2}
zwelch's avatar
zwelch committed
417
418
@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
Improved parallel-port wiggler-style JTAG adapter}
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435

@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c

@item @b{old_amt_wiggler}
@* Unknown - probably not on the market today

@item @b{arm-jtag}
@* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]

@item @b{chameleon}
@* Link: @url{http://www.amontec.com/chameleon.shtml}

@item @b{Triton}
@* Unknown.

@item @b{Lattice}
zwelch's avatar
zwelch committed
436
437
@* ispDownload from Lattice Semiconductor
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
438
439

@item @b{flashlink}
zwelch's avatar
zwelch committed
440
441
442
@* From ST Microsystems;
@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
FlashLINK JTAG programing cable for PSD and uPSD}
443
444
445
446
447
448
449

@end itemize

@section Other...
@itemize @bullet

@item @b{ep93xx}
ntfreak's avatar
ntfreak committed
450
@* An EP93xx based Linux machine using the GPIO pins directly.
451
452
453
454
455
456

@item @b{at91rm9200}
@* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.

@end itemize

zwelch's avatar
zwelch committed
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
@node About JIM-Tcl
@chapter About JIM-Tcl
@cindex JIM Tcl
@cindex tcl

OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
This programming language provides a simple and extensible
command interpreter.

All commands presented in this Guide are extensions to JIM-Tcl.
You can use them as simple commands, without needing to learn
much of anything about Tcl.
Alternatively, can write Tcl programs with them.

You can learn more about JIM at its website,  @url{http://jim.berlios.de}.

@itemize @bullet
@item @b{JIM vs. Tcl}
@* JIM-TCL is a stripped down version of the well known Tcl language,
which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
fewer features. JIM-Tcl is a single .C file and a single .H file and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
4.2 MB .zip file containing 1540 files.

@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
needed. We welcome JIM Tcl improvements, not bloat.

@item @b{Scripts}
@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
command interpreter today is a mixture of (newer)
JIM-Tcl commands, and (older) the orginal command interpreter.

@item @b{Commands}
@* At the OpenOCD telnet command line (or via the GDB mon command) one
can type a Tcl for() loop, set variables, etc.
zwelch's avatar
zwelch committed
493
494
Some of the commands documented in this guide are implemented
as Tcl scripts, from a @file{startup.tcl} file internal to the server.
zwelch's avatar
zwelch committed
495
496
497
498
499
500
501
502

@item @b{Historical Note}
@* JIM-Tcl was introduced to OpenOCD in spring 2008.

@item @b{Need a crash course in Tcl?}
@*@xref{Tcl Crash Course}.
@end itemize

ntfreak's avatar
ntfreak committed
503
504
@node Running
@chapter Running
zwelch's avatar
zwelch committed
505
506
507
@cindex command line options
@cindex logfile
@cindex directory search
ntfreak's avatar
ntfreak committed
508

509
510
511
512
513
514
515
516
Properly installing OpenOCD sets up your operating system to grant it access
to the JTAG adapters.  On Linux, this usually involves installing a file
in @file{/etc/udev/rules.d,} so OpenOCD has permissions.  MS-Windows needs
complex and confusing driver configuration for every peripheral.  Such issues
are unique to each operating system, and are not detailed in this User's Guide.

Then later you will invoke the OpenOCD server, with various options to
tell it how each debug session should work.
517
518
519
520
521
522
523
524
525
526
527
The @option{--help} option shows:
@verbatim
bash$ openocd --help

--help       | -h       display this help
--version    | -v       display OpenOCD version
--file       | -f       use configuration file <name>
--search     | -s       dir to search for config files and scripts
--debug      | -d       set debug level <0-3>
--log_output | -l       redirect log output to file <name>
--command    | -c       run <command>
528
--pipe       | -p       use pipes when talking to gdb
529
530
@end verbatim

531
532
533
534
If you don't give any @option{-f} or @option{-c} options,
OpenOCD tries to read the configuration file @file{openocd.cfg}.
To specify one or more different
configuration files, use @option{-f} options. For example:
535
536

@example
537
openocd -f config1.cfg -f config2.cfg -f config3.cfg
538
539
@end example

540
541
542
543
544
545
546
547
548
549
Configuration files and scripts are searched for in
@enumerate
@item the current directory,
@item any search dir specified on the command line using the @option{-s} option,
@item @file{$HOME/.openocd} (not on Windows),
@item the site wide script library @file{$pkgdatadir/site} and
@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
@end enumerate
The first found file with a matching file name will be used.

550
551
552
553
554
@quotation Note
Don't try to use configuration script names or paths which
include the "#" character.  That character begins Tcl comments.  
@end quotation

555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
@section Simple setup, no customization

In the best case, you can use two scripts from one of the script
libraries, hook up your JTAG adapter, and start the server ... and
your JTAG setup will just work "out of the box".  Always try to
start by reusing those scripts, but assume you'll need more
customization even if this works.  @xref{OpenOCD Project Setup}.

If you find a script for your JTAG adapter, and for your board or
target, you may be able to hook up your JTAG adapter then start
the server like:

@example
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
@end example

You might also need to configure which reset signals are present,
using @option{-c 'reset_config trst_and_srst'} or something similar.
If all goes well you'll see output something like

@example
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
For bug reports, read
        http://openocd.berlios.de/doc/doxygen/bugs.html
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
       (mfg: 0x23b, part: 0xba00, ver: 0x3)
@end example

Seeing that "tap/device found" message, and no warnings, means
the JTAG communication is working.  That's a key milestone, but
you'll probably need more project-specific setup.

@section What OpenOCD does as it starts

589
OpenOCD starts by processing the configuration commands provided
590
591
on the command line or, if there were no @option{-c command} or
@option{-f file.cfg} options given, in @file{openocd.cfg}.
592
593
594
595
596
597
598
599
600
601
602
603
@xref{Configuration Stage}.
At the end of the configuration stage it verifies the JTAG scan
chain defined using those commands; your configuration should
ensure that this always succeeds.
Normally, OpenOCD then starts running as a daemon.
Alternatively, commands may be used to terminate the configuration
stage early, perform work (such as updating some flash memory),
and then shut down without acting as a daemon.

Once OpenOCD starts running as a daemon, it waits for connections from
clients (Telnet, GDB, Other) and processes the commands issued through
those channels.
604

605
If you are having problems, you can enable internal debug messages via
606
the @option{-d} option.
ntfreak's avatar
ntfreak committed
607

zwelch's avatar
zwelch committed
608
Also it is possible to interleave JIM-Tcl commands w/config scripts using the
609
@option{-c} command line switch.
ntfreak's avatar
ntfreak committed
610

611
612
613
614
615
To enable debug output (when reporting problems or working on OpenOCD
itself), use the @option{-d} command line switch. This sets the
@option{debug_level} to "3", outputting the most information,
including debug messages. The default setting is "2", outputting only
informational messages, warnings and errors. You can also change this
zwelch's avatar
zwelch committed
616
617
setting from within a telnet or gdb session using @command{debug_level
<n>} (@pxref{debug_level}).
618
619
620

You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
ntfreak's avatar
ntfreak committed
621

622
623
For details on the @option{-p} option. @xref{Connecting to GDB}.

624
625
626
627
Note! OpenOCD will launch the GDB & telnet server even if it can not
establish a connection with the target. In general, it is possible for
the JTAG controller to be unresponsive until the target is set up
correctly via e.g. GDB monitor commands in a GDB init script.
ntfreak's avatar
ntfreak committed
628

zwelch's avatar
zwelch committed
629
630
@node OpenOCD Project Setup
@chapter OpenOCD Project Setup
ntfreak's avatar
ntfreak committed
631

zwelch's avatar
zwelch committed
632
633
634
635
636
To use OpenOCD with your development projects, you need to do more than
just connecting the JTAG adapter hardware (dongle) to your development board
and then starting the OpenOCD server.
You also need to configure that server so that it knows
about that adapter and board, and helps your work.
637
638
You may also want to connect OpenOCD to GDB, possibly
using Eclipse or some other GUI.
zwelch's avatar
zwelch committed
639
640
641
642
643
644
645
646

@section Hooking up the JTAG Adapter

Today's most common case is a dongle with a JTAG cable on one side
(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
and a USB cable on the other.
Instead of USB, some cables use Ethernet;
older ones may use a PC parallel port, or even a serial port.
647
648

@enumerate
zwelch's avatar
zwelch committed
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
@item @emph{Start with power to your target board turned off},
and nothing connected to your JTAG adapter.
If you're particularly paranoid, unplug power to the board.
It's important to have the ground signal properly set up,
unless you are using a JTAG adapter which provides
galvanic isolation between the target board and the
debugging host.

@item @emph{Be sure it's the right kind of JTAG connector.}
If your dongle has a 20-pin ARM connector, you need some kind
of adapter (or octopus, see below) to hook it up to
boards using 14-pin or 10-pin connectors ... or to 20-pin
connectors which don't use ARM's pinout.

In the same vein, make sure the voltage levels are compatible.
Not all JTAG adapters have the level shifters needed to work
with 1.2 Volt boards.

@item @emph{Be certain the cable is properly oriented} or you might
damage your board.  In most cases there are only two possible
ways to connect the cable.
Connect the JTAG cable from your adapter to the board.
Be sure it's firmly connected.

In the best case, the connector is keyed to physically
prevent you from inserting it wrong.
This is most often done using a slot on the board's male connector
housing, which must match a key on the JTAG cable's female connector.
If there's no housing, then you must look carefully and
make sure pin 1 on the cable hooks up to pin 1 on the board.
Ribbon cables are frequently all grey except for a wire on one
edge, which is red.  The red wire is pin 1.

Sometimes dongles provide cables where one end is an ``octopus'' of
color coded single-wire connectors, instead of a connector block.
These are great when converting from one JTAG pinout to another,
but are tedious to set up.
Use these with connector pinout diagrams to help you match up the
adapter signals to the right board pins.

@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
A USB, parallel, or serial port connector will go to the host which
you are using to run OpenOCD.
For Ethernet, consult the documentation and your network administrator.

For USB based JTAG adapters you have an easy sanity check at this point:
695
696
does the host operating system see the JTAG adapter?  If that host is an
MS-Windows host, you'll need to install a driver before OpenOCD works.
zwelch's avatar
zwelch committed
697
698
699
700
701
702
703
704
705
706

@item @emph{Connect the adapter's power supply, if needed.}
This step is primarily for non-USB adapters,
but sometimes USB adapters need extra power.

@item @emph{Power up the target board.}
Unless you just let the magic smoke escape,
you're now ready to set up the OpenOCD server
so you can use JTAG to work with that board.

707
708
@end enumerate

zwelch's avatar
zwelch committed
709
710
711
712
713
Talk with the OpenOCD server using
telnet (@code{telnet localhost 4444} on many systems) or GDB.
@xref{GDB and OpenOCD}.

@section Project Directory
714

zwelch's avatar
zwelch committed
715
There are many ways you can configure OpenOCD and start it up.
716

zwelch's avatar
zwelch committed
717
718
719
A simple way to organize them all involves keeping a
single directory for your work with a given board.
When you start OpenOCD from that directory,
720
it searches there first for configuration files, scripts,
721
files accessed through semihosting,
zwelch's avatar
zwelch committed
722
and for code you upload to the target board.
zwelch's avatar
zwelch committed
723
It is also the natural place to write files,
zwelch's avatar
zwelch committed
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
such as log files and data you download from the board.

@section Configuration Basics

There are two basic ways of configuring OpenOCD, and
a variety of ways you can mix them.
Think of the difference as just being how you start the server:

@itemize
@item Many @option{-f file} or @option{-c command} options on the command line
@item No options, but a @dfn{user config file}
in the current directory named @file{openocd.cfg}
@end itemize

Here is an example @file{openocd.cfg} file for a setup
using a Signalyzer FT2232-based JTAG adapter to talk to
a board with an Atmel AT91SAM7X256 microcontroller:
741
742
743
744
745
746
747
748
749
750
751

@example
source [find interface/signalyzer.cfg]

# GDB can also flash my flash!
gdb_memory_map enable
gdb_flash_program enable

source [find target/sam7x256.cfg]
@end example

zwelch's avatar
zwelch committed
752
Here is the command line equivalent of that configuration:
753

zwelch's avatar
zwelch committed
754
755
756
757
758
759
760
761
762
@example
openocd -f interface/signalyzer.cfg \
        -c "gdb_memory_map enable" \
        -c "gdb_flash_program enable" \
        -f target/sam7x256.cfg
@end example

You could wrap such long command lines in shell scripts,
each supporting a different development task.
zwelch's avatar
zwelch committed
763
One might re-flash the board with a specific firmware version.
zwelch's avatar
zwelch committed
764
Another might set up a particular debugging or run-time environment.
765

766
767
768
769
770
771
772
773
@quotation Important
At this writing (October 2009) the command line method has
problems with how it treats variables.
For example, after @option{-c "set VAR value"}, or doing the
same in a script, the variable @var{VAR} will have no value
that can be tested in a later script.
@end quotation

zwelch's avatar
zwelch committed
774
775
776
Here we will focus on the simpler solution:  one user config
file, including basic configuration plus any TCL procedures
to simplify your work.
777

zwelch's avatar
zwelch committed
778
@section User Config Files
zwelch's avatar
zwelch committed
779
@cindex config file, user
zwelch's avatar
zwelch committed
780
@cindex user config file
zwelch's avatar
zwelch committed
781
@cindex config file, overview
782

zwelch's avatar
zwelch committed
783
784
785
786
787
788
789
790
A user configuration file ties together all the parts of a project
in one place.
One of the following will match your situation best:

@itemize
@item Ideally almost everything comes from configuration files
provided by someone else.
For example, OpenOCD distributes a @file{scripts} directory
zwelch's avatar
zwelch committed
791
792
793
794
(probably in @file{/usr/share/openocd/scripts} on Linux).
Board and tool vendors can provide these too, as can individual
user sites; the @option{-s} command line option lets you say
where to find these files.  (@xref{Running}.)
zwelch's avatar
zwelch committed
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
The AT91SAM7X256 example above works this way.

Three main types of non-user configuration file each have their
own subdirectory in the @file{scripts} directory:

@enumerate
@item @b{interface} -- one for each kind of JTAG adapter/dongle
@item @b{board} -- one for each different board
@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
@end enumerate

Best case:  include just two files, and they handle everything else.
The first is an interface config file.
The second is board-specific, and it sets up the JTAG TAPs and
their GDB targets (by deferring to some @file{target.cfg} file),
declares all flash memory, and leaves you nothing to do except
meet your deadline:
812
813

@example
zwelch's avatar
zwelch committed
814
815
source [find interface/olimex-jtag-tiny.cfg]
source [find board/csb337.cfg]
816
817
@end example

zwelch's avatar
zwelch committed
818
819
820
821
Boards with a single microcontroller often won't need more
than the target config file, as in the AT91SAM7X256 example.
That's because there is no external memory (flash, DDR RAM), and
the board differences are encapsulated by application code.
822

823
824
825
826
827
828
829
@item Maybe you don't know yet what your board looks like to JTAG.
Once you know the @file{interface.cfg} file to use, you may
need help from OpenOCD to discover what's on the board.
Once you find the TAPs, you can just search for appropriate
configuration files ... or write your own, from the bottom up.
@xref{Autoprobing}.

zwelch's avatar
zwelch committed
830
831
832
833
@item You can often reuse some standard config files but
need to write a few new ones, probably a @file{board.cfg} file.
You will be using commands described later in this User's Guide,
and working with the guidelines in the next chapter.
834

zwelch's avatar
zwelch committed
835
836
837
838
839
For example, there may be configuration files for your JTAG adapter
and target chip, but you need a new board-specific config file
giving access to your particular flash chips.
Or you might need to write another target chip configuration file
for a new chip built around the Cortex M3 core.
840

zwelch's avatar
zwelch committed
841
842
843
844
845
846
847
@quotation Note
When you write new configuration files, please submit
them for inclusion in the next OpenOCD release.
For example, a @file{board/newboard.cfg} file will help the
next users of that board, and a @file{target/newcpu.cfg}
will help support users of any board using that chip.
@end quotation
848

zwelch's avatar
zwelch committed
849
850
@item
You may may need to write some C code.
851
It may be as simple as a supporting a new ft2232 or parport
zwelch's avatar
zwelch committed
852
853
854
855
based dongle; a bit more involved, like a NAND or NOR flash
controller driver; or a big piece of work like supporting
a new chip architecture.
@end itemize
856

zwelch's avatar
zwelch committed
857
858
859
Reuse the existing config files when you can.
Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
You may find a board configuration that's a good example to follow.
860

zwelch's avatar
zwelch committed
861
862
863
When you write config files, separate the reusable parts
(things every user of that interface, chip, or board needs)
from ones specific to your environment and debugging approach.
864
@itemize
865

866
@item
zwelch's avatar
zwelch committed
867
868
869
870
For example, a @code{gdb-attach} event handler that invokes
the @command{reset init} command will interfere with debugging
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
871
872

@item
873
Likewise, the @command{arm9 vector_catch} command (or
874
875
876
@cindex vector_catch
its siblings @command{xscale vector_catch}
and @command{cortex_m3 vector_catch}) can be a timesaver
zwelch's avatar
zwelch committed
877
during some debug sessions, but don't make everyone use that either.
878
879
880
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
zwelch's avatar
zwelch committed
881

882
883
884
885
886
887
@item
You might need to override some defaults.
For example, you might need to move, shrink, or back up the target's
work area if your application needs much SRAM.

@item
zwelch's avatar
zwelch committed
888
889
890
TCP/IP port configuration is another example of something which
is environment-specific, and should only appear in
a user config file.  @xref{TCP/IP Ports}.
891
@end itemize
zwelch's avatar
zwelch committed
892

zwelch's avatar
zwelch committed
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
@section Project-Specific Utilities

A few project-specific utility
routines may well speed up your work.
Write them, and keep them in your project's user config file.

For example, if you are making a boot loader work on a
board, it's nice to be able to debug the ``after it's
loaded to RAM'' parts separately from the finicky early
code which sets up the DDR RAM controller and clocks.
A script like this one, or a more GDB-aware sibling,
may help:

@example
proc ramboot @{ @} @{
    # Reset, running the target's "reset-init" scripts
    # to initialize clocks and the DDR RAM controller.
    # Leave the CPU halted.
    reset init

    # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
    load_image u-boot.bin 0x20000000

    # Start running.
    resume 0x20000000
@}
@end example

Then once that code is working you will need to make it
boot from NOR flash; a different utility would help.
Alternatively, some developers write to flash using GDB.
(You might use a similar script if you're working with a flash
based microcontroller application instead of a boot loader.)

@example
proc newboot @{ @} @{
    # Reset, leaving the CPU halted.  The "reset-init" event
    # proc gives faster access to the CPU and to NOR flash;
    # "reset halt" would be slower.
    reset init

    # Write standard version of U-Boot into the first two
    # sectors of NOR flash ... the standard version should
    # do the same lowlevel init as "reset-init".
    flash protect 0 0 1 off
    flash erase_sector 0 0 1
    flash write_bank 0 u-boot.bin 0x0
    flash protect 0 0 1 on

    # Reboot from scratch using that new boot loader.
    reset run
@}
@end example
946

zwelch's avatar
zwelch committed
947
948
949
950
951
952
953
954
You may need more complicated utility procedures when booting
from NAND.
That often involves an extra bootloader stage,
running from on-chip SRAM to perform DDR RAM setup so it can load
the main bootloader code (which won't fit into that SRAM).

Other helper scripts might be used to write production system images,
involving considerably more than just a three stage bootloader.
955

956
957
958
959
960
961
962
963
964
965
@section Target Software Changes

Sometimes you may want to make some small changes to the software
you're developing, to help make JTAG debugging work better.
For example, in C or assembly language code you might
use @code{#ifdef JTAG_DEBUG} (or its converse) around code
handling issues like:

@itemize @bullet

David Brownell's avatar
David Brownell committed
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
@item @b{Watchdog Timers}...
Watchog timers are typically used to automatically reset systems if
some application task doesn't periodically reset the timer.  (The
assumption is that the system has locked up if the task can't run.)
When a JTAG debugger halts the system, that task won't be able to run
and reset the timer ... potentially causing resets in the middle of
your debug sessions.

It's rarely a good idea to disable such watchdogs, since their usage
needs to be debugged just like all other parts of your firmware.
That might however be your only option.

Look instead for chip-specific ways to stop the watchdog from counting
while the system is in a debug halt state.  It may be simplest to set
that non-counting mode in your debugger startup scripts.  You may however
need a different approach when, for example, a motor could be physically
damaged by firmware remaining inactive in a debug halt state.  That might
involve a type of firmware mode where that "non-counting" mode is disabled
at the beginning then re-enabled at the end; a watchdog reset might fire
and complicate the debug session, but hardware (or people) would be
protected.@footnote{Note that many systems support a "monitor mode" debug
that is a somewhat cleaner way to address such issues.  You can think of
it as only halting part of the system, maybe just one task,
instead of the whole thing.
At this writing, January 2010, OpenOCD based debugging does not support
monitor mode debug, only "halt mode" debug.}

993
994
995
996
997
998
999
1000
@item @b{ARM Semihosting}...
@cindex ARM semihosting
When linked with a special runtime library provided with many
toolchains@footnote{See chapter 8 "Semihosting" in
@uref{http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf,
ARM DUI 0203I}, the "RealView Compilation Tools Developer Guide".
The CodeSourcery EABI toolchain also includes a semihosting library.},
your target code can use I/O facilities on the debug host.  That library
For faster browsing, not all history is shown. View entire blame