openocd.texi 260 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}
zwelch's avatar
zwelch committed
26
@item Copyright @copyright{} 2009 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
ntfreak's avatar
ntfreak committed
63
* Developers::                       OpenOCD Developers
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
155
156
157
158

@section OpenOCD User's Forum

There is an OpenOCD forum (phpBB) hosted by SparkFun:

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

zwelch's avatar
zwelch committed
159

ntfreak's avatar
ntfreak committed
160
@node Developers
zwelch's avatar
zwelch committed
161
@chapter OpenOCD Developer Resources
ntfreak's avatar
ntfreak committed
162
163
@cindex developers

zwelch's avatar
zwelch committed
164
165
166
167
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
168

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

172
@section OpenOCD GIT Repository
173

174
175
During the 0.3.x release cycle, OpenOCD switched from Subversion to
a GIT repository hosted at SourceForge.  The repository URL is:
176

177
@uref{git://openocd.git.sourceforge.net/gitroot/openocd/openocd}
178

David Brownell's avatar
David Brownell committed
179
180
181
182
You may prefer to use a mirror and the HTTP protocol:

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

183
184
185
186
187
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:
188

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

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

193
194
The @file{README} file contains the instructions for building the project
from the repository or a snapshot.
ntfreak's avatar
ntfreak committed
195

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

zwelch's avatar
zwelch committed
201
@section Doxygen Developer Manual
ntfreak's avatar
ntfreak committed
202

203
During the 0.2.x release cycle, the OpenOCD project began
zwelch's avatar
zwelch committed
204
205
206
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
207

zwelch's avatar
zwelch committed
208
209
210
211
@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,
212
listed in the Doxyfile configuration in the top of the source tree.
zwelch's avatar
zwelch committed
213
214
215
216
217
218

@section OpenOCD Developer Mailing List

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

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

221
222
223
Discuss and submit patches to this list.
The @file{PATCHES} file contains basic information about how
to prepare patches.
zwelch's avatar
zwelch committed
224

ntfreak's avatar
ntfreak committed
225

226
227
228
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@cindex dongles
ntfreak's avatar
ntfreak committed
229
@cindex FTDI
230
231
232
@cindex wiggler
@cindex zy1000
@cindex printer port
ntfreak's avatar
ntfreak committed
233
@cindex USB Adapter
zwelch's avatar
zwelch committed
234
@cindex RTCK
235
236
237
238
239
240
241

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
242
243
244
245
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.
246
247
248
249


@section Choosing a Dongle

250
There are several things you should keep in mind when choosing a dongle.
251

252
@enumerate
253
254
255
256
257
258
259
@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?
260
@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
261
262
263
264
265
@end enumerate

@section Stand alone Systems

@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
266
267
268
269
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.
270
271
272

@section USB FT2232 Based

ntfreak's avatar
ntfreak committed
273
There are many USB JTAG dongles on the market, many of them are based
274
on a chip from ``Future Technology Devices International'' (FTDI)
zwelch's avatar
zwelch committed
275
276
277
278
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.
279
280
281

@itemize @bullet
@item @b{usbjtag}
282
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
283
284
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
285
286
@item @b{jtagkey2}
@* See: @url{http://www.amontec.com/jtagkey2.shtml}
287
@item @b{oocdlink}
duane's avatar
duane committed
288
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
289
290
291
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
zwelch's avatar
zwelch committed
292
@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
zwelch's avatar
zwelch committed
293
294
@item @b{luminary_icdi}
@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
295
296
297
298
299
@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
300
301
302
@* See:
@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
@url{http://www.ethernut.de}
303
304
305
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
ntfreak's avatar
ntfreak committed
306
307
308
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
@* Axiom AXM-0432 Link @url{http://www.axman.com}
309
310
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
@end itemize

@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

327
328
329
330
331
332
333
334
335
336
337
338
@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

339
340
341
342
343
@section USB Other
@itemize @bullet
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604

344
@item @b{USB - Presto}
345
@* Link: @url{http://tools.asix.net/prg_presto.htm}
duane's avatar
duane committed
346
347
348

@item @b{Versaloon-Link}
@* Link: @url{http://www.simonqian.com/en/Versaloon}
349
350
351

@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
352
353
354
355
356
357
358
359
@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.

360
361
362
363
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.

364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
@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
380
381
@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
Improved parallel-port wiggler-style JTAG adapter}
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398

@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
399
400
@* ispDownload from Lattice Semiconductor
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
401
402

@item @b{flashlink}
zwelch's avatar
zwelch committed
403
404
405
@* From ST Microsystems;
@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
FlashLINK JTAG programing cable for PSD and uPSD}
406
407
408
409
410
411
412

@end itemize

@section Other...
@itemize @bullet

@item @b{ep93xx}
ntfreak's avatar
ntfreak committed
413
@* An EP93xx based Linux machine using the GPIO pins directly.
414
415
416
417
418
419

@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
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
@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
456
457
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
458
459
460
461
462
463
464
465

@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
466
467
@node Running
@chapter Running
zwelch's avatar
zwelch committed
468
469
470
@cindex command line options
@cindex logfile
@cindex directory search
ntfreak's avatar
ntfreak committed
471

472
473
474
475
476
477
478
479
480
481
482
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>
483
--pipe       | -p       use pipes when talking to gdb
484
485
@end verbatim

486
By default OpenOCD reads the file configuration file @file{openocd.cfg}
487
488
489
490
in the current directory.  To specify a different (or multiple)
configuration file, you can use the ``-f'' option. For example:

@example
491
openocd -f config1.cfg -f config2.cfg -f config3.cfg
492
493
@end example

494
495
496
497
498
499
500
501
502
503
504
505
506
507
OpenOCD starts by processing the configuration commands provided
on the command line or in @file{openocd.cfg}.
@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.
508

509
510
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
ntfreak's avatar
ntfreak committed
511

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

515
516
517
518
519
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
520
521
setting from within a telnet or gdb session using @command{debug_level
<n>} (@pxref{debug_level}).
522
523
524

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

526
Search paths for config/script files can be added to OpenOCD by using
527
528
the @option{-s <search>} switch. The current directory and the OpenOCD
target library is in the search path by default.
529

530
531
For details on the @option{-p} option. @xref{Connecting to GDB}.

532
533
534
535
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
536

zwelch's avatar
zwelch committed
537
538
@node OpenOCD Project Setup
@chapter OpenOCD Project Setup
ntfreak's avatar
ntfreak committed
539

zwelch's avatar
zwelch committed
540
541
542
543
544
545
546
547
548
549
550
551
552
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.

@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.
553
554

@enumerate
zwelch's avatar
zwelch committed
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
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
@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:
does the host operating system see the JTAG adapter?

@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.

612
613
@end enumerate

zwelch's avatar
zwelch committed
614
615
616
617
618
Talk with the OpenOCD server using
telnet (@code{telnet localhost 4444} on many systems) or GDB.
@xref{GDB and OpenOCD}.

@section Project Directory
619

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

zwelch's avatar
zwelch committed
622
623
624
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,
625
it searches there first for configuration files, scripts,
zwelch's avatar
zwelch committed
626
and for code you upload to the target board.
zwelch's avatar
zwelch committed
627
It is also the natural place to write files,
zwelch's avatar
zwelch committed
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
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:
645
646
647
648
649
650
651
652
653
654
655

@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
656
Here is the command line equivalent of that configuration:
657

zwelch's avatar
zwelch committed
658
659
660
661
662
663
664
665
666
@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
667
One might re-flash the board with a specific firmware version.
zwelch's avatar
zwelch committed
668
Another might set up a particular debugging or run-time environment.
669

670
671
672
673
674
675
676
677
@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
678
679
680
Here we will focus on the simpler solution:  one user config
file, including basic configuration plus any TCL procedures
to simplify your work.
681

zwelch's avatar
zwelch committed
682
@section User Config Files
zwelch's avatar
zwelch committed
683
@cindex config file, user
zwelch's avatar
zwelch committed
684
@cindex user config file
zwelch's avatar
zwelch committed
685
@cindex config file, overview
686

zwelch's avatar
zwelch committed
687
688
689
690
691
692
693
694
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
695
696
697
698
(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
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
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:
716
717

@example
zwelch's avatar
zwelch committed
718
719
source [find interface/olimex-jtag-tiny.cfg]
source [find board/csb337.cfg]
720
721
@end example

zwelch's avatar
zwelch committed
722
723
724
725
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.
726

727
728
729
730
731
732
733
@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
734
735
736
737
@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.
738

zwelch's avatar
zwelch committed
739
740
741
742
743
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.
744

zwelch's avatar
zwelch committed
745
746
747
748
749
750
751
@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
752

zwelch's avatar
zwelch committed
753
754
@item
You may may need to write some C code.
755
It may be as simple as a supporting a new ft2232 or parport
zwelch's avatar
zwelch committed
756
757
758
759
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
760

zwelch's avatar
zwelch committed
761
762
763
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.
764

zwelch's avatar
zwelch committed
765
766
767
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.
768
@itemize
769

770
@item
zwelch's avatar
zwelch committed
771
772
773
774
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.
775
776

@item
777
Likewise, the @command{arm9 vector_catch} command (or
778
779
780
@cindex vector_catch
its siblings @command{xscale vector_catch}
and @command{cortex_m3 vector_catch}) can be a timesaver
zwelch's avatar
zwelch committed
781
during some debug sessions, but don't make everyone use that either.
782
783
784
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
785

786
787
788
789
790
791
@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
792
793
794
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}.
795
@end itemize
zwelch's avatar
zwelch committed
796

zwelch's avatar
zwelch committed
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
@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
850

zwelch's avatar
zwelch committed
851
852
853
854
855
856
857
858
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.
859

860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
@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

@item @b{ARM Wait-For-Interrupt}...
Many ARM chips synchronize the JTAG clock using the core clock.
Low power states which stop that core clock thus prevent JTAG access.
Idle loops in tasking environments often enter those low power states
via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).

You may want to @emph{disable that instruction} in source code,
or otherwise prevent using that state,
to ensure you can get JTAG access at any time.
For example, the OpenOCD @command{halt} command may not
work for an idle processor otherwise.

@item @b{Delay after reset}...
Not all chips have good support for debugger access
right after reset; many LPC2xxx chips have issues here.
Similarly, applications that reconfigure pins used for
JTAG access as they start will also block debugger access.

To work with boards like this, @emph{enable a short delay loop}
the first thing after reset, before "real" startup activities.
For example, one second's delay is usually more than enough
time for a JTAG debugger to attach, so that
early code execution can be debugged
or firmware can be replaced.

@item @b{Debug Communications Channel (DCC)}...
Some processors include mechanisms to send messages over JTAG.
Many ARM cores support these, as do some cores from other vendors.
(OpenOCD may be able to use this DCC internally, speeding up some
operations like writing to memory.)

Your application may want to deliver various debugging messages
over JTAG, by @emph{linking with a small library of code}
provided with OpenOCD and using the utilities there to send
various kinds of message.
@xref{Software Debug Messages and Tracing}.

@end itemize
ntfreak's avatar
ntfreak committed
908

909
910
911
@node Config File Guidelines
@chapter Config File Guidelines

zwelch's avatar
zwelch committed
912
913
914
915
This chapter is aimed at any user who needs to write a config file,
including developers and integrators of OpenOCD and any user who
needs to get a new board working smoothly.
It provides guidelines for creating those files.
916

917
918
919
You should find the following directories under @t{$(INSTALLDIR)/scripts},
with files including the ones listed here.
Use them as-is where you can; or as models for new files.
ntfreak's avatar
ntfreak committed
920
@itemize @bullet
zwelch's avatar
zwelch committed
921
922
@item @file{interface} ...
think JTAG Dongle. Files that configure JTAG adapters go here.
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
@example
$ ls interface
arm-jtag-ew.cfg          hitex_str9-comstick.cfg  oocdlink.cfg
arm-usb-ocd.cfg          icebear.cfg              openocd-usb.cfg
at91rm9200.cfg           jlink.cfg                parport.cfg
axm0432.cfg              jtagkey2.cfg             parport_dlc5.cfg
calao-usb-a9260-c01.cfg  jtagkey.cfg              rlink.cfg
calao-usb-a9260-c02.cfg  jtagkey-tiny.cfg         sheevaplug.cfg
calao-usb-a9260.cfg      luminary.cfg             signalyzer.cfg
chameleon.cfg            luminary-icdi.cfg        stm32-stick.cfg
cortino.cfg              luminary-lm3s811.cfg     turtelizer2.cfg
dummy.cfg                olimex-arm-usb-ocd.cfg   usbprog.cfg
flyswatter.cfg           olimex-jtag-tiny.cfg     vsllink.cfg
$
@end example
zwelch's avatar
zwelch committed
938
939
@item @file{board} ...
think Circuit Board, PWA, PCB, they go by many names.  Board files
940
941
942
943
contain initialization items that are specific to a board.
They reuse target configuration files, since the same
microprocessor chips are used on many boards,
but support for external parts varies widely.  For
zwelch's avatar
zwelch committed
944
945
example, the SDRAM initialization sequence for the board, or the type
of external flash and what address it uses.  Any initialization
ntfreak's avatar
ntfreak committed
946
sequence to enable that external flash or SDRAM should be found in the
zwelch's avatar
zwelch committed
947
board file. Boards may also contain multiple targets:  two CPUs; or
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
a CPU and an FPGA.
@example
$ ls board
arm_evaluator7t.cfg               keil_mcb1700.cfg
at91rm9200-dk.cfg                 keil_mcb2140.cfg
at91sam9g20-ek.cfg                linksys_nslu2.cfg
atmel_at91sam7s-ek.cfg            logicpd_imx27.cfg
atmel_at91sam9260-ek.cfg          mini2440.cfg
atmel_sam3u_ek.cfg                olimex_LPC2378STK.cfg
crossbow_tech_imote2.cfg          olimex_lpc_h2148.cfg
csb337.cfg                        olimex_sam7_ex256.cfg
csb732.cfg                        olimex_sam9_l9260.cfg
digi_connectcore_wi-9c.cfg        olimex_stm32_h103.cfg
dm355evm.cfg                      omap2420_h4.cfg
dm365evm.cfg                      osk5912.cfg
dm6446evm.cfg                     pic-p32mx.cfg
eir.cfg                           propox_mmnet1001.cfg
ek-lm3s1968.cfg                   pxa255_sst.cfg
ek-lm3s3748.cfg                   sheevaplug.cfg
ek-lm3s811.cfg                    stm3210e_eval.cfg
ek-lm3s9b9x.cfg                   stm32f10x_128k_eval.cfg
hammer.cfg                        str910-eval.cfg
hitex_lpc2929.cfg                 telo.cfg
hitex_stm32-performancestick.cfg  ti_beagleboard.cfg
hitex_str9-comstick.cfg           topas910.cfg
iar_str912_sk.cfg                 topasa900.cfg
imx27ads.cfg                      unknown_at91sam9260.cfg
imx27lnst.cfg                     x300t.cfg
imx31pdk.cfg                      zy1000.cfg
$
@end example
zwelch's avatar
zwelch committed
979
980
@item @file{target} ...
think chip. The ``target'' directory represents the JTAG TAPs
zwelch's avatar
zwelch committed
981
982
on a chip
which OpenOCD should control, not a board. Two common types of targets
983
are ARM chips and FPGA or CPLD chips.
zwelch's avatar
zwelch committed
984
985
When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
the target config file defines all of them.
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@example
$ ls target
aduc702x.cfg     imx27.cfg     pxa255.cfg
ar71xx.cfg       imx31.cfg     pxa270.cfg
at91eb40a.cfg    imx35.cfg     readme.txt
at91r40008.cfg   is5114.cfg    sam7se512.cfg
at91rm9200.cfg   ixp42x.cfg    sam7x256.cfg
at91sam3u1c.cfg  lm3s1968.cfg  samsung_s3c2410.cfg
at91sam3u1e.cfg  lm3s3748.cfg  samsung_s3c2440.cfg
at91sam3u2c.cfg  lm3s6965.cfg  samsung_s3c2450.cfg
at91sam3u2e.cfg  lm3s811.cfg   samsung_s3c4510.cfg
at91sam3u4c.cfg  lm3s9b9x.cfg  samsung_s3c6410.cfg
at91sam3u4e.cfg  lpc1768.cfg   sharp_lh79532.cfg
at91sam3uXX.cfg  lpc2103.cfg   smdk6410.cfg
at91sam7sx.cfg   lpc2124.cfg   smp8634.cfg