openocd.texi 419 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
@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
25
@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
@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
34
Texts. A copy of the license is included in the section entitled ``GNU
ntfreak's avatar
ntfreak committed
35
36
37
38
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
* Debug Adapter Hardware::           Debug Adapter Hardware
65
* About Jim-Tcl::                    About Jim-Tcl
66
* Running::                          Running OpenOCD
zwelch's avatar
zwelch committed
67
* OpenOCD Project Setup::            OpenOCD Project Setup
68
* Config File Guidelines::           Config File Guidelines
69
* Server Configuration::             Server Configuration
70
* Debug Adapter Configuration::      Debug Adapter Configuration
71
* 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
* Flash Programming::                Flash Programming
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
* Utility Commands::                 Utility Commands
82
83
* TFTP::                             TFTP
* GDB and OpenOCD::                  Using GDB and OpenOCD
ntfreak's avatar
ntfreak committed
84
* Tcl Scripting API::                Tcl Scripting API
85
* FAQ::                              Frequently Asked Questions
ntfreak's avatar
ntfreak committed
86
* Tcl Crash Course::                 Tcl Crash Course
87
* License::                          GNU Free Documentation License
zwelch's avatar
zwelch committed
88

89
90
91
92
@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
93
* OpenOCD Concept Index::            Concept Index
zwelch's avatar
zwelch committed
94
* Command and Driver Index::         Command and Driver Index
ntfreak's avatar
ntfreak committed
95
96
97
98
99
100
@end menu

@node About
@unnumbered About
@cindex about

101
102
OpenOCD was created by Dominic Rath as part of a 2005 diploma thesis written
at the University of Applied Sciences Augsburg (@uref{http://www.hs-augsburg.de}).
zwelch's avatar
zwelch committed
103
104
105
106
107
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
108
109
@cindex TAP
@cindex JTAG
zwelch's avatar
zwelch committed
110

111
112
113
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
114

115
116
It does so with the assistance of a @dfn{debug adapter}, which is
a small hardware module which helps provide the right kind of
117
electrical signaling to the target being debugged. These are
118
119
120
121
122
123
required since the debug host (on which OpenOCD runs) won't
usually have native support for such signaling, or the connector
needed to hook up to the target.

Such debug adapters support one or more @dfn{transport} protocols,
each of which involves different electrical signaling (and uses
124
different messaging protocols on top of that signaling). There
125
are many types of debug adapter, and little uniformity in what
126
they are called. (There are also product naming differences.)
127

Antonio Borneo's avatar
Antonio Borneo committed
128
These adapters are sometimes packaged as discrete dongles, which
129
130
may generically be called @dfn{hardware interface dongles}.
Some development boards also integrate them directly, which may
131
let the development board connect directly to the debug
132
133
134
135
136
host over USB (and sometimes also to power it over USB).

For example, a @dfn{JTAG Adapter} supports JTAG
signaling, and is used to communicate
with JTAG (IEEE 1149.1) compliant TAPs on your target board.
zwelch's avatar
zwelch committed
137
A @dfn{TAP} is a ``Test Access Port'', a module which processes
138
139
special instructions and data. TAPs are daisy-chained within and
between chips and boards. JTAG supports debugging and boundary
140
141
142
143
scan operations.

There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD)
signaling to communicate with some newer ARM cores, as well as debug
144
adapters which support both JTAG and SWD transports. SWD supports only
145
146
147
148
149
150
151
debugging, whereas JTAG also supports boundary scan operations.

For some chips, there are also @dfn{Programming Adapters} supporting
special transports used only to write code to flash memory, without
support for on-chip debugging or boundary scan.
(At this writing, OpenOCD does not support such non-debug adapters.)

ntfreak's avatar
ntfreak committed
152

153
154
@b{Dongles:} OpenOCD currently supports many types of hardware dongles:
USB-based, parallel port-based, and other standalone boxes that run
155
OpenOCD internally. @xref{Debug Adapter Hardware}.
156

ntfreak's avatar
ntfreak committed
157
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
158
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3
159
160
(Stellaris LM3, STMicroelectronics STM32 and Energy Micro EFM32) and
Intel Quark (x10xx) based cores to be debugged via the GDB protocol.
161

162
163
@b{Flash Programming:} Flash writing is supported for external
CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several
164
165
internal flashes (LPC1700, LPC1800, LPC2000, LPC4300, AT91SAM7, AT91SAM3U,
STR7x, STR9x, LM3, STM32x and EFM32). Preliminary support for various NAND flash
166
controllers (LPC3180, Orion, S3C24xx, more) is included.
ntfreak's avatar
ntfreak committed
167

zwelch's avatar
zwelch committed
168
169
170
171
@section OpenOCD Web Site

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

172
@uref{http://openocd.org/}
zwelch's avatar
zwelch committed
173

zwelch's avatar
zwelch committed
174
175
176
@section Latest User's Guide:

The user's guide you are now reading may not be the latest one
177
available. A version for more recent code may be available.
178
Its HTML form is published regularly at:
zwelch's avatar
zwelch committed
179

180
@uref{http://openocd.org/doc/html/index.html}
zwelch's avatar
zwelch committed
181
182
183

PDF form is likewise published at:

184
@uref{http://openocd.org/doc/pdf/openocd.pdf}
zwelch's avatar
zwelch committed
185
186
187

@section OpenOCD User's Forum

188
There is an OpenOCD forum (phpBB) hosted by SparkFun,
189
which might be helpful to you. Note that if you want
190
191
192
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
193
194
195

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

196
197
198
199
200
201
202
203
204
205
206
@section OpenOCD User's Mailing List

The OpenOCD User Mailing List provides the primary means of
communication between users:

@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-user}

@section OpenOCD IRC

Support can also be found on irc:
@uref{irc://irc.freenode.net/openocd}
zwelch's avatar
zwelch committed
207

ntfreak's avatar
ntfreak committed
208
@node Developers
zwelch's avatar
zwelch committed
209
@chapter OpenOCD Developer Resources
ntfreak's avatar
ntfreak committed
210
211
@cindex developers

zwelch's avatar
zwelch committed
212
If you are interested in improving the state of OpenOCD's debugging and
213
testing support, new contributions will be welcome. Motivated developers
zwelch's avatar
zwelch committed
214
215
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
216

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

220
@section OpenOCD Git Repository
221

222
During the 0.3.x release cycle, OpenOCD switched from Subversion to
223
a Git repository hosted at SourceForge. The repository URL is:
224

Spencer Oliver's avatar
Spencer Oliver committed
225
226
227
228
229
@uref{git://git.code.sf.net/p/openocd/code}

or via http

@uref{http://git.code.sf.net/p/openocd/code}
230

David Brownell's avatar
David Brownell committed
231
232
233
234
You may prefer to use a mirror and the HTTP protocol:

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

235
With standard Git tools, use @command{git clone} to initialize
236
237
238
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
239
needing a Git client:
240

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

243
244
The @file{README} file contains the instructions for building the project
from the repository or a snapshot.
ntfreak's avatar
ntfreak committed
245

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

zwelch's avatar
zwelch committed
251
@section Doxygen Developer Manual
ntfreak's avatar
ntfreak committed
252

253
During the 0.2.x release cycle, the OpenOCD project began
254
providing a Doxygen reference manual. This document contains more
zwelch's avatar
zwelch committed
255
256
technical information about the software internals, development
processes, and similar documentation:
ntfreak's avatar
ntfreak committed
257

258
@uref{http://openocd.org/doc/doxygen/html/index.html}
zwelch's avatar
zwelch committed
259
260

This document is a work-in-progress, but contributions would be welcome
261
to fill in the gaps. All of the source files are provided in-tree,
262
listed in the Doxyfile configuration at the top of the source tree.
zwelch's avatar
zwelch committed
263

264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
@section Gerrit Review System

All changes in the OpenOCD Git repository go through the web-based Gerrit
Code Review System:

@uref{http://openocd.zylin.com/}

After a one-time registration and repository setup, anyone can push commits
from their local Git repository directly into Gerrit.
All users and developers are encouraged to review, test, discuss and vote
for changes in Gerrit. The feedback provides the basis for a maintainer to
eventually submit the change to the main Git repository.

The @file{HACKING} file, also available as the Patch Guide in the Doxygen
Developer Manual, contains basic information about how to connect a
repository to Gerrit, prepare and push patches. Patch authors are expected to
maintain their changes while they're in Gerrit, respond to feedback and if
necessary rework and push improved versions of the change.

zwelch's avatar
zwelch committed
283
284
285
286
287
@section OpenOCD Developer Mailing List

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

288
@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
zwelch's avatar
zwelch committed
289

Spencer Oliver's avatar
Spencer Oliver committed
290
@section OpenOCD Bug Tracker
291

Spencer Oliver's avatar
Spencer Oliver committed
292
The OpenOCD Bug Tracker is hosted on SourceForge:
293

294
@uref{http://bugs.openocd.org/}
295

ntfreak's avatar
ntfreak committed
296

297
298
@node Debug Adapter Hardware
@chapter Debug Adapter Hardware
299
@cindex dongles
ntfreak's avatar
ntfreak committed
300
@cindex FTDI
301
302
303
@cindex wiggler
@cindex zy1000
@cindex printer port
ntfreak's avatar
ntfreak committed
304
@cindex USB Adapter
zwelch's avatar
zwelch committed
305
@cindex RTCK
306

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

310
In the OpenOCD case, this generally refers to @b{a small adapter} that
311
312
313
attaches to your computer via USB or the parallel port. One
exception is the Ultimate Solutions ZY1000, packaged as a small box you
attach via an ethernet cable. The ZY1000 has the advantage that it does not
314
315
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
316
and has a built-in relay to power cycle targets remotely.
317
318
319
320


@section Choosing a Dongle

321
There are several things you should keep in mind when choosing a dongle.
322

323
@enumerate
324
@item @b{Transport} Does it support the kind of communication that you need?
325
OpenOCD focusses mostly on JTAG. Your version may also support
326
other ways to communicate with target devices.
327
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
328
Does your dongle support it? You might need a level converter.
329
@item @b{Pinout} What pinout does your target board use?
330
Does your dongle support it? You may be able to use jumper
331
wires, or an "octopus" connector, to convert pinouts.
332
@item @b{Connection} Does your computer have the USB, parallel, or
333
Ethernet port needed?
334
@item @b{RTCK} Do you expect to use it with ARM chips and boards with
335
RTCK support (also known as ``adaptive clocking'')?
336
337
@end enumerate

338
339
340
@section Stand-alone JTAG Probe

The ZY1000 from Ultimate Solutions is technically not a dongle but a
341
342
stand-alone JTAG probe that, unlike most dongles, doesn't require any drivers
running on the developer's host computer.
343
344
345
346
347
348
349
350
351
352
353
354
Once installed on a network using DHCP or a static IP assignment, users can
access the ZY1000 probe locally or remotely from any host with access to the
IP address assigned to the probe.
The ZY1000 provides an intuitive web interface with direct access to the
OpenOCD debugger.
Users may also run a GDBSERVER directly on the ZY1000 to take full advantage
of GCC & GDB to debug any distribution of embedded Linux or NetBSD running on
the target.
The ZY1000 supports RTCK & RCLK or adaptive clocking and has a built-in relay
to power cycle the target remotely.

For more information, visit:
355

356
@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/210-zylin-zy1000-main}
357
358
359

@section USB FT2232 Based

360
There are many USB JTAG dongles on the market, many of them based
361
on a chip from ``Future Technology Devices International'' (FTDI)
zwelch's avatar
zwelch committed
362
363
364
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
365
chips started to become available in JTAG adapters. Around 2012, a new
366
367
368
variant appeared - FT232H - this is a single-channel version of FT2232H.
(Adapters using those high speed FT2232H or FT232H chips may support adaptive
clocking.)
369
370
371
372
373
374
375
376

The FT2232 chips are flexible enough to support some other
transport options, such as SWD or the SPI variants used to
program some chips. They have two communications channels,
and one can be used for a UART adapter at the same time the
other one is used to provide a debug adapter.

Also, some development boards integrate an FT2232 chip to serve as
377
a built-in low-cost debug adapter and USB-to-serial solution.
378
379
380

@itemize @bullet
@item @b{usbjtag}
381
@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html}
382
383
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
384
385
@item @b{jtagkey2}
@* See: @url{http://www.amontec.com/jtagkey2.shtml}
386
@item @b{oocdlink}
duane's avatar
duane committed
387
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
388
389
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
390
@item @b{Stellaris Eval Boards}
391
@* See: @url{http://www.ti.com} - The Stellaris eval boards
392
bundle FT2232-based JTAG and SWD support, which can be used to debug
393
the Stellaris chips. Using separate JTAG adapters is optional.
394
395
These boards can also be used in a "pass through" mode as JTAG adapters
to other target boards, disabling the Stellaris chip.
396
397
@item @b{TI/Luminary ICDI}
@* See: @url{http://www.ti.com} - TI/Luminary In-Circuit Debug
398
Interface (ICDI) Boards are included in Stellaris LM3S9B9x
399
Evaluation Kits. Like the non-detachable FT2232 support on the other
400
Stellaris eval boards, they can be used to debug other target boards.
401
402
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
403
@item @b{Flyswatter/Flyswatter2}
404
405
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
zwelch's avatar
zwelch committed
406
407
408
@* See:
@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
@url{http://www.ethernut.de}
409
410
411
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
ntfreak's avatar
ntfreak committed
412
413
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
414
@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear
415
to be available anymore as of April 2012.
416
417
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
418
419
@item @b{dlp-usb1232h}
@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
420
421
@item @b{digilent-hs1}
@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
422
423
424
@item @b{opendous}
@* Link @url{http://code.google.com/p/opendous/wiki/JTAG} FT2232H-based
(OpenHardware).
425
426
@item @b{JTAG-lock-pick Tiny 2}
@* Link @url{http://www.distortec.com/jtag-lock-pick-tiny-2} FT232H-based
427

428
429
430
431
432
@item @b{GW16042}
@* Link: @url{http://shop.gateworks.com/index.php?route=product/product&path=70_80&product_id=64}
FT2232H-based

@end itemize
433
434
435
436
@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,
437
protocol-compatible among themselves. USB-JTAG devices typically consist
438
of a FT245 followed by a CPLD that understands a particular protocol,
439
or emulates this protocol using some other hardware.
440
441

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

@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
447
@* Link: @url{http://ixo-jtag.sourceforge.net/}
448
449
450
451
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize

452
453
454
@section USB J-Link based
There are several OEM versions of the SEGGER @b{J-Link} adapter. It is
an example of a microcontroller based JTAG adapter, it uses an
455
456
457
AT91SAM764 internally.

@itemize @bullet
458
@item @b{SEGGER J-Link}
459
@* Link: @url{http://www.segger.com/jlink.html}
460
461
@item @b{Atmel SAM-ICE} (Only works with Atmel chips!)
@* Link: @url{http://www.atmel.com/tools/atmelsam-ice.aspx}
462
463
464
@item @b{IAR J-Link}
@end itemize

465
@section USB RLINK based
466
467
468
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.
469
470
471

@itemize @bullet
@item @b{Raisonance RLink}
472
@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__@/microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html}
473
474
475
476
477
478
@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

479
@section USB ST-LINK based
480
481
STMicroelectronics has an adapter called @b{ST-LINK}.
They only work with STMicroelectronics chips, notably STM32 and STM8.
482
483
484
485
486
487
488
489

@itemize @bullet
@item @b{ST-LINK}
@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
@item @b{ST-LINK/V2}
@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
490
491
492
@item @b{STLINK-V3}
@* This is available standalone and as part of some kits.
@* Link: @url{http://www.st.com/stlink-v3}
493
494
@end itemize

495
496
497
For info the original ST-LINK enumerates using the mass storage usb class; however,
its implementation is completely broken. The result is this causes issues under Linux.
The simplest solution is to get Linux to ignore the ST-LINK using one of the following methods:
498
499
500
501
502
@itemize @bullet
@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
@end itemize

503
504
505
506
507
@section USB TI/Stellaris ICDI based
Texas Instruments has an adapter called @b{ICDI}.
It is not to be confused with the FTDI based adapters that were originally fitted to their
evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.

508
509
510
511
@section USB CMSIS-DAP based
ARM has released a interface standard called CMSIS-DAP that simplifies connecting
debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}.

512
513
514
@section USB Other
@itemize @bullet
@item @b{USBprog}
515
@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604
516

517
@item @b{USB - Presto}
518
@* Link: @url{http://tools.asix.net/prg_presto.htm}
duane's avatar
duane committed
519
520

@item @b{Versaloon-Link}
521
@* Link: @url{http://www.versaloon.com}
522
523
524

@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
525
526
527

@item @b{Buspirate}
@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
528
529

@item @b{opendous}
530
@* Link: @url{http://code.google.com/p/opendous-jtag/} - which uses an AT90USB162
531
532
533

@item @b{estick}
@* Link: @url{http://code.google.com/p/estick-jtag/}
534
535
536

@item @b{Keil ULINK v1}
@* Link: @url{http://www.keil.com/ulink1/}
537
538
539
540

@item @b{TI XDS110 Debug Probe}
@* The XDS110 is included as the embedded debug probe on many Texas Instruments
LaunchPad evaluation boards.
541
542
543
544
545
546
@* The XDS110 is also available as a stand-alone USB debug probe. The XDS110
stand-alone probe has the additional ability to supply voltage to the target
board via its AUX FUNCTIONS port. Use the
@command{xds110_supply_voltage <millivolts>} command to set the voltage. 0 turns
off the supply. Otherwise, the supply can be set to any value in the range 1800
to 3600 millivolts.
547
548
@* Link: @url{http://processors.wiki.ti.com/index.php/XDS110}
@* Link: @url{http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Support_Utilities}
549
550
551
552
@end itemize

@section IBM PC Parallel Printer Port Based

553
The two well-known ``JTAG Parallel Ports'' cables are the Xilinx DLC5
554
and the Macraigor Wiggler. There are many clones and variations of
555
556
these on the market.

557
558
559
560
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.

561
562
563
564
565
566
567
568
569
570
571
572
573
@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{Wiggler2}
574
@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591

@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
592
593
@* ispDownload from Lattice Semiconductor
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
594
595

@item @b{flashlink}
596
@* From STMicroelectronics;
597
@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
598
599
600
601
602
603
604

@end itemize

@section Other...
@itemize @bullet

@item @b{ep93xx}
ntfreak's avatar
ntfreak committed
605
@* An EP93xx based Linux machine using the GPIO pins directly.
606
607
608
609

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

610
611
612
@item @b{bcm2835gpio}
@* A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of the expansion header.

613
614
615
@item @b{imx_gpio}
@* A NXP i.MX-based board (e.g. Wandboard) using the GPIO pins (should work on any i.MX processor).

616
617
618
619
@item @b{jtag_vpi}
@* A JTAG driver acting as a client for the JTAG VPI server interface.
@* Link: @url{http://github.com/fjullien/jtag_vpi}

620
621
@end itemize

622
623
624
@node About Jim-Tcl
@chapter About Jim-Tcl
@cindex Jim-Tcl
zwelch's avatar
zwelch committed
625
626
@cindex tcl

627
OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl.
zwelch's avatar
zwelch committed
628
629
630
This programming language provides a simple and extensible
command interpreter.

631
All commands presented in this Guide are extensions to Jim-Tcl.
zwelch's avatar
zwelch committed
632
633
You can use them as simple commands, without needing to learn
much of anything about Tcl.
634
Alternatively, you can write Tcl programs with them.
zwelch's avatar
zwelch committed
635

636
You can learn more about Jim at its website, @url{http://jim.tcl.tk}.
637
638
639
There is an active and responsive community, get on the mailing list
if you have any questions. Jim-Tcl maintainers also lurk on the
OpenOCD mailing list.
zwelch's avatar
zwelch committed
640
641

@itemize @bullet
642
643
644
@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
645
fewer features. Jim-Tcl is several dozens of .C files and .H files and
zwelch's avatar
zwelch committed
646
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
Spencer Oliver's avatar
Spencer Oliver committed
647
4.2 MB .zip file containing 1540 files.
zwelch's avatar
zwelch committed
648
649
650

@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
651
needed. We welcome Jim-Tcl improvements, not bloat. Also there
Spencer Oliver's avatar
Spencer Oliver committed
652
are a large number of optional Jim-Tcl features that are not
653
enabled in OpenOCD.
zwelch's avatar
zwelch committed
654
655

@item @b{Scripts}
656
@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
zwelch's avatar
zwelch committed
657
command interpreter today is a mixture of (newer)
658
Jim-Tcl commands, and the (older) original command interpreter.
zwelch's avatar
zwelch committed
659
660

@item @b{Commands}
661
@* At the OpenOCD telnet command line (or via the GDB monitor command) one
zwelch's avatar
zwelch committed
662
can type a Tcl for() loop, set variables, etc.
zwelch's avatar
zwelch committed
663
664
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
665
666

@item @b{Historical Note}
667
@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
668
669
670
before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl
as a Git submodule, which greatly simplified upgrading Jim-Tcl
to benefit from new features and bugfixes in Jim-Tcl.
zwelch's avatar
zwelch committed
671
672
673
674
675

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

ntfreak's avatar
ntfreak committed
676
677
@node Running
@chapter Running
zwelch's avatar
zwelch committed
678
679
680
@cindex command line options
@cindex logfile
@cindex directory search
ntfreak's avatar
ntfreak committed
681

682
Properly installing OpenOCD sets up your operating system to grant it access
683
to the debug adapters. On Linux, this usually involves installing a file
684
685
686
in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file
that works for many common adapters is shipped with OpenOCD in the
@file{contrib} directory. MS-Windows needs
687
complex and confusing driver configuration for every peripheral. Such issues
688
689
690
691
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.
692
693
694
695
696
697
698
699
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
700
701
--debug      | -d       set debug level to 3
             | -d<n>    set debug level to <level>
702
703
704
705
--log_output | -l       redirect log output to file <name>
--command    | -c       run <command>
@end verbatim

706
707
708
709
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:
710
711

@example
712
openocd -f config1.cfg -f config2.cfg -f config3.cfg
713
714
@end example

715
716
717
718
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,
719
@item any search dir specified using the @command{add_script_search_dir} command,
720
@item @file{$HOME/.openocd} (not on Windows),
721
@item a directory in the @env{OPENOCD_SCRIPTS} environment variable (if set),
722
723
724
725
726
@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.

727
728
@quotation Note
Don't try to use configuration script names or paths which
729
include the "#" character. That character begins Tcl comments.
730
731
@end quotation

732
733
734
735
@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
736
your JTAG setup will just work "out of the box". Always try to
737
start by reusing those scripts, but assume you'll need more
738
customization even if this works. @xref{OpenOCD Project Setup}.
739
740
741

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
742
the server with some variation of one of the following:
743
744
745

@example
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
746
openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg
747
748
749
750
751
752
753
754
755
@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
756
        http://openocd.org/doc/doxygen/bugs.html
757
758
759
760
761
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
762
the JTAG communication is working. That's a key milestone, but
763
764
765
766
you'll probably need more project-specific setup.

@section What OpenOCD does as it starts

767
OpenOCD starts by processing the configuration commands provided
768
769
on the command line or, if there were no @option{-c command} or
@option{-f file.cfg} options given, in @file{openocd.cfg}.
770
@xref{configurationstage,,Configuration Stage}.
771
772
773
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.
774
Normally, OpenOCD then starts running as a server.
775
776
Alternatively, commands may be used to terminate the configuration
stage early, perform work (such as updating some flash memory),
777
and then shut down without acting as a server.
778

779
780
Once OpenOCD starts running as a server, it waits for connections from
clients (Telnet, GDB, RPC) and processes the commands issued through
781
those channels.
782

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

786
Also it is possible to interleave Jim-Tcl commands w/config scripts using the
787
@option{-c} command line switch.
ntfreak's avatar
ntfreak committed
788

789
790
791
792
793
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
794
795
setting from within a telnet or gdb session using @command{debug_level<n>}
(@pxref{debuglevel,,debug_level}).
796

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

800
801
802
803
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
804

zwelch's avatar
zwelch committed
805
806
@node OpenOCD Project Setup
@chapter OpenOCD Project Setup
ntfreak's avatar
ntfreak committed
807

zwelch's avatar
zwelch committed
808
To use OpenOCD with your development projects, you need to do more than
809
810
811
812
just connect the JTAG adapter hardware (dongle) to your development board
and start the OpenOCD server.
You also need to configure your OpenOCD server so that it knows
about your adapter and board, and helps your work.
813
814
You may also want to connect OpenOCD to GDB, possibly
using Eclipse or some other GUI.
zwelch's avatar
zwelch committed
815
816
817
818
819
820
821
822

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

@enumerate
zwelch's avatar
zwelch committed
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
@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
844
damage your board. In most cases there are only two possible
zwelch's avatar
zwelch committed
845
846
847
848
849
850
851
852
853
854
855
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
856
edge, which is red. The red wire is pin 1.
zwelch's avatar
zwelch committed
857
858
859
860
861
862
863
864
865
866
867
868
869

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.

870
871
872
For USB-based JTAG adapters you have an easy sanity check at this point:
does the host operating system see the JTAG adapter? If you're running
Linux, try the @command{lsusb} command. If that host is an
873
MS-Windows host, you'll need to install a driver before OpenOCD works.
zwelch's avatar
zwelch committed
874
875
876
877
878
879
880
881
882
883

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

884
885
@end enumerate

zwelch's avatar
zwelch committed
886
887
888
889
890
Talk with the OpenOCD server using
telnet (@code{telnet localhost 4444} on many systems) or GDB.
@xref{GDB and OpenOCD}.

@section Project Directory
891

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

zwelch's avatar
zwelch committed
894
895
896
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,
897
it searches there first for configuration files, scripts,
898
files accessed through semihosting,
zwelch's avatar
zwelch committed
899
and for code you upload to the target board.
zwelch's avatar
zwelch committed
900
It is also the natural place to write files,
zwelch's avatar
zwelch committed
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
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:
918
919

@example
920
source [find interface/ftdi/signalyzer.cfg]
921
922
923
924
925
926
927
928

# 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
929
Here is the command line equivalent of that configuration:
930

zwelch's avatar
zwelch committed
931
@example
932
openocd -f interface/ftdi/signalyzer.cfg \
zwelch's avatar
zwelch committed
933
934
935
936
937
938
939
        -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
940
One might re-flash the board with a specific firmware version.
zwelch's avatar
zwelch committed
941
Another might set up a particular debugging or run-time environment.
942

dbrownell's avatar