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

@include version.texi

ntfreak's avatar
ntfreak committed
14
@copying
15
16
17

@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
18
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
19
20
21
22
@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
@end itemize

ntfreak's avatar
ntfreak committed
23
24
25
26
27
28
29
30
31
32
@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
33
@titlepage
34
35
@title Open On-Chip Debugger (OpenOCD)
@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
ntfreak's avatar
ntfreak committed
36
37
38
@subtitle @value{UPDATED}
@page
@vskip 0pt plus 1filll
ntfreak's avatar
ntfreak committed
39
@insertcopying
ntfreak's avatar
ntfreak committed
40
41
@end titlepage

42
@summarycontents
ntfreak's avatar
ntfreak committed
43
44
45
46
47
@contents

@node Top, About, , (dir)
@top OpenOCD

ntfreak's avatar
ntfreak committed
48
This manual documents edition @value{EDITION} of the Open On-Chip Debugger
49
(OpenOCD) version @value{VERSION}, @value{UPDATED}.
ntfreak's avatar
ntfreak committed
50
51

@insertcopying
ntfreak's avatar
ntfreak committed
52
53

@menu
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
* About::                            About OpenOCD.
* Developers::                       OpenOCD developers
* Building::                         Building OpenOCD
* JTAG Hardware Dongles::            JTAG Hardware Dongles
* Running::                          Running OpenOCD
* Simple Configuration Files::       Simple Configuration Files
* Config File Guidelines::           Config File Guidelines
* About JIM-Tcl::                    About JIM-Tcl
* Daemon Configuration::             Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration::              Reset Configuration
* Tap Creation::                     Tap Creation
* Target Configuration::             Target Configuration
* Flash Configuration::              Flash Configuration
* General Commands::                 General Commands
* JTAG Commands::                    JTAG Commands
* Sample Scripts::                   Sample Target Scripts
* TFTP::                             TFTP
* GDB and OpenOCD::                  Using GDB and OpenOCD
* TCL scripting API::                Tcl scripting API
* Upgrading::                        Deprecated/Removed Commands
* Target library::                   Target library
* FAQ::                              Frequently Asked Questions
* TCL Crash Course::                 TCL Crash Course
* License::                          GNU Free Documentation License
@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
* OpenOCD Index::                    Main index.
ntfreak's avatar
ntfreak committed
84
85
86
87
88
89
@end menu

@node About
@unnumbered About
@cindex about

90
91
92
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
93

94
95
@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
with the JTAG (IEEE 1149.1) complient taps on your target board.
ntfreak's avatar
ntfreak committed
96

97
98
@b{Dongles:} OpenOCD currently many types of hardware dongles: USB
Based, Parallel Port Based, and other standalone boxes that run
oharboe's avatar
oharboe committed
99
OpenOCD internally. See the section titled: @xref{JTAG Hardware Dongles}.
100
101
102
103
104
105
106
107
108
109
110

@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920t,
ARM922t, ARM926ej--s, ARM966e--s), XScale (PXA25x, IXP42x) and
Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be
debugged via the GDB Protocol.

@b{Flash Programing:} Flash writing is supported for external CFI
compatible flashes (Intel and AMD/Spansion command set) and several
internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3 and
STM32x). Preliminary support for using the LPC3180's NAND flash
controller is included.
ntfreak's avatar
ntfreak committed
111
112
113
114
115

@node Developers
@chapter Developers
@cindex developers

116
OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
ntfreak's avatar
ntfreak committed
117
118
119
120
121
122
123
University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
Others interested in improving the state of free and open debug and testing technology
are welcome to participate.

Other developers have contributed support for additional targets and flashes as well
as numerous bugfixes and enhancements. See the AUTHORS file for regular contributors. 

124
125
The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}

ntfreak's avatar
ntfreak committed
126
127
@node Building
@chapter Building
128
@cindex building OpenOCD
ntfreak's avatar
ntfreak committed
129

130
@section Pre-Built Tools
131
132
133
134
135
If you are interested in getting actual work done rather than building
OpenOCD, then check if your interface supplier provides binaries for
you. Chances are that that binary is from some SVN version that is more
stable than SVN trunk where bleeding edge development takes place.

136
@section Building From Source
137

ntfreak's avatar
ntfreak committed
138
139
140
141
142
143
144
145
146
You can download the current SVN version with SVN client of your choice from the
following repositories:

 (@uref{svn://svn.berlios.de/openocd/trunk})

or

 (@uref{http://svn.berlios.de/svnroot/repos/openocd/trunk})

147
Using the SVN command line client, you can use the following command to fetch the
ntfreak's avatar
ntfreak committed
148
149
150
latest version (make sure there is no (non-svn) directory called "openocd" in the
current directory):

151
@example
oharboe's avatar
oharboe committed
152
 svn checkout svn://svn.berlios.de/openocd/trunk openocd
153
@end example
ntfreak's avatar
ntfreak committed
154

155
Building OpenOCD requires a recent version of the GNU autotools.
ntfreak's avatar
ntfreak committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
On my build system, I'm using autoconf 2.13 and automake 1.9. For building on Windows,
you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
paths, resulting in obscure dependency errors (This is an observation I've gathered
from the logs of one user - correct me if I'm wrong).

You further need the appropriate driver files, if you want to build support for
a FTDI FT2232 based interface:
@itemize @bullet
@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID. 
@end itemize

171
libftdi is supported under windows. Do not use versions earlier then 0.14.
ntfreak's avatar
ntfreak committed
172
173

In general, the D2XX driver provides superior performance (several times as fast),
174
but has the draw-back of being binary-only - though that isn't that bad, as it isn't
ntfreak's avatar
ntfreak committed
175
176
177
a kernel module, only a user space library.

To build OpenOCD (on both Linux and Cygwin), use the following commands:
178
@example
ntfreak's avatar
ntfreak committed
179
 ./bootstrap 
180
@end example
ntfreak's avatar
ntfreak committed
181
Bootstrap generates the configure script, and prepares building on your system.
182
@example
183
 ./configure [options, see below]
184
@end example
oharboe's avatar
oharboe committed
185
Configure generates the Makefiles used to build OpenOCD.
186
@example
ntfreak's avatar
ntfreak committed
187
 make 
188
 make install
189
@end example
190
Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
ntfreak's avatar
ntfreak committed
191
192
193
194
195
196

The configure script takes several options, specifying which JTAG interfaces
should be included:

@itemize @bullet
@item
197
@option{--enable-parport} - Bit bang pc printer ports.
ntfreak's avatar
ntfreak committed
198
@item
199
@option{--enable-parport_ppdev} - Parallel Port [see below]
ntfreak's avatar
ntfreak committed
200
@item
201
@option{--enable-parport_giveio} - Parallel Port [see below]
202
@item
203
@option{--enable-amtjtagaccel} - Parallel Port [Amontec, see below]
ntfreak's avatar
ntfreak committed
204
@item
205
@option{--enable-ft2232_ftd2xx} - Numerous USB Type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
ntfreak's avatar
ntfreak committed
206
@item
207
@option{--enable-ft2232_libftdi} - An open source (free) alternate to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin)
ntfreak's avatar
ntfreak committed
208
@item
209
210
211
212
213
@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@item
@option{--with-ftd2xx-linux-tardir=PATH} - Linux only equal of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
@item
@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static, specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. Shared is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
214
215
216
217
218
219
220
221
@item
@option{--enable-gw16012}
@item
@option{--enable-usbprog}
@item
@option{--enable-presto_libftdi}
@item
@option{--enable-presto_ftd2xx}
222
@item
223
@option{--enable-jlink} - From SEGGER
224
@item
225
@option{--enable-rlink} - Raisonance.com dongle.
ntfreak's avatar
ntfreak committed
226
227
@end itemize

228
229
@section Parallel Port Dongles

ntfreak's avatar
ntfreak committed
230
231
232
233
234
If you want to access the parallel port using the PPDEV interface you have to specify
both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
the @option{--enable-parport_ppdev} option actually is an option to the parport driver
(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).

235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
@section FT2232C Based USB Dongles 

There are 2 methods of using the FTD2232, either (1) using the
FTDICHIP.COM closed source driver, or (2) the open (and free) driver
libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.

The FTDICHIP drivers come as either a (win32) ZIP file, or a (linux)
TAR.GZ file. You must unpack them ``some where'' convient. As of this
writing (12/26/2008) FTDICHIP does not supply means to install these
files ``in an appropriate place'' As a result, there are two
``./configure'' options that help. 

Below is an example build process:

1) Check out the latest version of ``openocd'' from SVN.

2) Download & Unpack either the Windows or Linux FTD2xx Drivers
    (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})

@example
   /home/duane/ftd2xx.win32    => the Cygwin/Win32 ZIP file contents.
   /home/duane/libftd2xx0.4.16 => the Linux TAR file contents.
@end example

3) Configure with these options:

@example
Cygwin FTCICHIP solution
   ./configure --prefix=/home/duane/mytools \ 
                  --enable-ft2232_ftd2xx \
                  --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32

Linux FTDICHIP solution
   ./configure --prefix=/home/duane/mytools \
                  --enable-ft2232_ftd2xx \
                  --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16

Cygwin/Linux LIBFTDI solution
    Assumes: 
    1a) For Windows: The windows port of LIBUSB is in place.
    1b) For Linux: libusb has been built and is inplace.

    2) And libftdi has been built and installed
    Note: libftdi - relies upon libusb.

    ./configure --prefix=/home/duane/mytools \
                   --enable-ft2232_libftdi
       
@end example

4) Then just type ``make'', and perhaps ``make install''.
ntfreak's avatar
ntfreak committed
286
287


288
@section Miscellaneous configure options
ntfreak's avatar
ntfreak committed
289
290
291
292
293
294

@itemize @bullet
@item
@option{--enable-gccwarnings} - enable extra gcc warnings during build
@end itemize

295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@cindex dongles
@cindex ftdi
@cindex wiggler
@cindex zy1000
@cindex printer port
@cindex usb adapter
@cindex rtck

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
an ethernet cable.


@section Choosing a Dongle

There are three things you should keep in mind when choosing a dongle. 

@enumerate 
@item @b{Voltage} What voltage is your target? 1.8, 2.8, 3.3, or 5V? Does your dongle support it?
@item @b{Connection} Printer Ports - Does your computer have one?
@item @b{Connection} Is that long printer bit-bang cable practical? 
@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking'' 
@end enumerate

@section Stand alone Systems

@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
dongle, but a standalone box.

@section USB FT2232 Based

There are many USB jtag dongles on the market, many of them are based
on a chip from ``Future Technology Devices International'' (FTDI)
known as the FTDI FT2232.

See: @url{http://www.ftdichip.com} or @url{http://www.ftdichip.com/Products/FT2232H.htm}

As of 28/Nov/2008, the following are supported:

@itemize @bullet
@item @b{usbjtag}
342
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
343
344
345
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{oocdlink}
duane's avatar
duane committed
346
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
347
348
349
350
351
352
353
354
355
356
357
358
359
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
@* See: @url{http://www.luminarymicro.com} - The Luminary Micro Stellaris LM3S811 eval board has an FTD2232C chip built in.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See: @url{http://www.ethernut.de}, or @url{http://www.ethernut.de/en/hardware/turtelizer/index.html}
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
ntfreak's avatar
ntfreak committed
360
361
362
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
@* Axiom AXM-0432 Link @url{http://www.axman.com}
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
@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

379
380
381
382
383
384
385
386
387
388
389
390
@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

391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
@section USB Other
@itemize @bullet
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604

@item @b{USB - Presto} 
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@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.

@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}
@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}

@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}
ntfreak's avatar
ntfreak committed
440
@* ispDownload from Lattice Semiconductor @url{http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf}
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459

@item @b{flashlink}
@* From ST Microsystems, link:
@url{http://www.st.com/stonline/products/literature/um/7889.pdf}
Title: FlashLINK JTAG programing cable for PSD and uPSD

@end itemize

@section Other...
@itemize @bullet

@item @b{ep93xx}
@* An EP93xx based linux machine using the GPIO pins directly.

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

@end itemize

ntfreak's avatar
ntfreak committed
460
461
@node Running
@chapter Running
462
@cindex running OpenOCD
ntfreak's avatar
ntfreak committed
463
464
465
466
467
@cindex --configfile
@cindex --debug_level
@cindex --logfile
@cindex --search

468
469
470
471
472
473
474
475
476
477
478
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>
479
--pipe       | -p       use pipes when talking to gdb
480
481
@end verbatim

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

@example
  openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example

Once started, OpenOCD runs as a daemon, waiting for connections from
clients (Telnet, GDB, Other).
492

493
494
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
ntfreak's avatar
ntfreak committed
495

496
497
Also it is possible to interleave commands w/config scripts using the
@option{-c} command line switch.
ntfreak's avatar
ntfreak committed
498

499
500
501
502
503
504
505
506
507
508
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
setting from within a telnet or gdb session using @option{debug_level
<n>} @xref{debug_level}.

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

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

514
515
516
For details on the @option{-p} option. @xref{Connecting to GDB}.
Option @option{-p} is not currently supported under native win32.

517
518
519
520
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
521

522
523
@node Simple Configuration Files
@chapter Simple Configuration Files
ntfreak's avatar
ntfreak committed
524
525
@cindex configuration

526
@section Outline
527
There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
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
612

@enumerate
@item A small openocd.cfg file which ``sources'' other configuration files
@item A monolithic openocd.cfg file
@item Many -f filename options on the command line
@item Your Mixed Solution
@end enumerate

@section Small configuration file method

This is the prefered method, it is simple and is works well for many
people.  The developers of OpenOCD would encourage you to use this
method. If you create a new configuration please email new
configurations to the development list.

Here is an example of an openocd.cfg file for an ATMEL at91sam7x256

@example
source [find interface/signalyzer.cfg]

# Change the default telnet port...
telnet_port 4444
# GDB connects here
gdb_port 3333
# GDB can also flash my flash!
gdb_memory_map enable
gdb_flash_program enable

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

There are many example configuration scripts you can work with. You
should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
should find:

@enumerate
@item @b{board} - eval board level configurations
@item @b{interface} - specific dongle configurations
@item @b{target} - the target chips
@item @b{tcl} - helper scripts 
@item @b{xscale} - things specific to the xscale.
@end enumerate

Look first in the ``boards'' area, then the ``targets'' area. Often a board
configuration is a good example to work from.

@section Many -f filename options
Some believe this is a wonderful solution, others find it painful.

You can use a series of ``-f filename'' options on the command line,
OpenOCD will read each filename in sequence, for example:

@example
        openocd -f file1.cfg -f file2.cfg -f file2.cfg
@end example

You can also intermix various commands with the ``-c'' command line
option.

@section Monolithic file
The ``Monolithic File'' dispenses with all ``source'' statements and
puts everything in one self contained (monolithic) file. This is not
encouraged. 

Please try to ``source'' various files or use the multiple -f
technique.

@section Advice for you
Often, one uses a ``mixed approach''. Where possible, please try to
``source'' common things, and if needed cut/paste parts of the
standard distribution configuration files as needed.

@b{REMEMBER:} The ``important parts'' of your configuration file are:

@enumerate
@item @b{Interface} - Defines the dongle
@item @b{Taps} - Defines the JTAG Taps
@item @b{GDB Targets} - What GDB talks to
@item @b{Flash Programing} - Very Helpful
@end enumerate

Some key things you should look at and understand are:

@enumerate
@item The RESET configuration of your debug environment as a hole
613
@item Is there a ``work area'' that OpenOCD can use?
614
615
616
617
618
619
@* For ARM - work areas mean up to 10x faster downloads.
@item For MMU/MPU based ARM chips (ie: ARM9 and later) will that work area still be available?
@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
@end enumerate


ntfreak's avatar
ntfreak committed
620

621
622
623
624
625
626
627
628
629
630
631
632
633
@node Config File Guidelines
@chapter Config File Guidelines

This section/chapter is aimed at developers and integrators of
OpenOCD. These are guidelines for creating new boards and new target
configurations as of 28/Nov/2008.

However, you the user of OpenOCD should be some what familiar with
this section as it should help explain some of the internals of what
you might be looking at.

The user should find under @t{$(INSTALLDIR)/lib/openocd} the
following directories:
ntfreak's avatar
ntfreak committed
634
635

@itemize @bullet
636
637
638
639
640
641
642
643
644
645
646
647
648
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
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
@item @b{interface}
@*Think JTAG Dongle. Files that configure the jtag dongle go here.
@item @b{board}
@* Thing Circuit Board, PWA, PCB, they go by many names.  Board files
contain initialization items that are specific to a board - for
example: The SDRAM initialization sequence for the board, or the type
of external flash and what address it is found at. Any initialization
sequence to enable that external flash or sdram should be found in the
board file. Boards may also contain multiple targets, ie: Two cpus, or
a CPU and an FPGA or CPLD.
@item @b{target}
@* Think CHIP. The ``target'' directory represents a jtag tap (or
chip) OpenOCD should control, not a board. Two common types of targets
are ARM chips and FPGA or CPLD chips.
@end itemize

@b{If needed...} The user in their ``openocd.cfg'' file or the board
file might override a specific feature in any of the above files by
setting a variable or two before sourcing the target file. Or adding
various commands specific to their situation.

@section Interface Config Files

The user should be able to source one of these files via a command like this:

@example
  source [find interface/FOOBAR.cfg]
Or:
  openocd -f interface/FOOBAR.cfg
@end example

A preconfigured interface file should exist for every interface in use
today, that said, perhaps some interfaces have only been used by the
sole developer who created it.

@b{FIXME/NOTE:} We need to add support for a variable like TCL variable
tcl_platform(platform), it should be called jim_platform (because it
is jim, not real tcl) and it should contain 1 of 3 words: ``linux'',
``cygwin'' or ``mingw''

Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}

@section Board Config Files

@b{Note: BOARD directory NEW as of 28/nov/2008} 

The user should be able to source one of these files via a command like this:

@example
  source [find board/FOOBAR.cfg]
Or:
  openocd -f board/FOOBAR.cfg
@end example


The board file should contain one or more @t{source [find
target/FOO.cfg]} statements along with any board specific things.

In summery the board files should contain (if present)

@enumerate
@item External flash configuration (ie: the flash on CS0)
@item SDRAM configuration (size, speed, etc)
@item Board specific IO configuration (ie: GPIO pins might disable a 2nd flash)
@item Multiple TARGET source statements
@item All things that are not ``inside a chip''
@item Things inside a chip go in a 'target' file
@end enumerate

@section Target Config Files

The user should be able to source one of these files via a command like this:

@example
  source [find target/FOOBAR.cfg]
Or:
  openocd -f target/FOOBAR.cfg
@end example

In summery the target files should contain

@enumerate 
@item Set Defaults
@item Create Taps
@item Reset Configuration
@item Work Areas
@item CPU/Chip/CPU-Core Specific features
@item OnChip Flash
@end enumerate

@subsection Important variable names

By default, the end user should never need to set these
variables. However, if the user needs to override a setting they only
need to set the variable in a simple way.

@itemize @bullet
@item @b{CHIPNAME}
@* This gives a name to the overall chip, and is used as part of the
tap identifier dotted name.
@item @b{ENDIAN}
@* By default little - unless the chip or board is not normally used that way.
@item @b{CPUTAPID}
@* When OpenOCD examines the JTAG chain, it will attempt to identify
every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
to verify the tap id number verses configuration file and may issue an
error or warning like this. The hope is this will help pin point
743
problem OpenOCD configurations.
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
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
850
851
852
853
854
855
856
857
858
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
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
946
947
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

@example
Info:   JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
Error:  ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
Error:  ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
Error:  ERROR:      got: mfg: 0x787, part: 0xf0f0, ver: 0x3
@end example

@item @b{_TARGETNAME}
@* By convention, this variable is created by the target configuration
script. The board configuration file may make use of this variable to
configure things like a ``reset init'' script, or other things
specific to that board and that target.

If the chip has 2 targets, use the names @b{_TARGETNAME0},
@b{_TARGETNAME1}, ... etc.

@b{Remember:} The ``board file'' may include multiple targets.

At no time should the name ``target0'' (the default target name if
none was specified) be used. The name ``target0'' is a hard coded name
- the next target on the board will be some other number.

The user (or board file) should reasonably be able to:

@example
   source [find target/FOO.cfg]
   $_TARGETNAME configure ... FOO specific parameters

   source [find target/BAR.cfg]
   $_TARGETNAME configure ... BAR specific parameters
@end example

@end itemize

@subsection TCL Variables Guide Line
The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.

Thus the rule we follow in OpenOCD is this: Variables that begin with
a leading underscore are temporal in nature, and can be modified and
used at will within a ?TARGET? configuration file

@b{EXAMPLE:} The user should be able to do this:

@example
   # Board has 3 chips,
   #    PXA270 #1 network side, big endian
   #    PXA270 #2 video side, little endian
   #    Xilinx    Glue logic
   set CHIPNAME network
   set ENDIAN big
   source [find target/pxa270.cfg]
   # variable: _TARGETNAME = network.cpu
   # other commands can refer to the "network.cpu" tap.
   $_TARGETNAME configure .... params for this cpu..
   
   set ENDIAN little
   set CHIPNAME video
   source [find target/pxa270.cfg]
   # variable: _TARGETNAME = video.cpu
   # other commands can refer to the "video.cpu" tap.
   $_TARGETNAME configure .... params for this cpu..
   
   unset ENDIAN
   set CHIPNAME xilinx
   source [find target/spartan3.cfg]

   # Since $_TARGETNAME is temporal..
   #  these names still work!
   network.cpu configure ... params
   video.cpu   configure ... params

@end example

@subsection Default Value Boiler Plate Code

All target configuration files should start with this (or a modified form)

@example
# SIMPLE example
if @{ [info exists CHIPNAME] @} @{	
   set  _CHIPNAME $CHIPNAME    
@} else @{	 
   set  _CHIPNAME sam7x256
@}

if @{ [info exists ENDIAN] @} @{	
   set  _ENDIAN $ENDIAN    
@} else @{	 
   set  _ENDIAN little
@}

if @{ [info exists CPUTAPID ] @} @{
   set _CPUTAPID $CPUTAPID
@} else @{
   set _CPUTAPID 0x3f0f0f0f
@}

@end example

@subsection Creating Taps
After the ``defaults'' are choosen, [see above], the taps are created.

@b{SIMPLE example:} such as an Atmel AT91SAM7X256

@example
# for an ARM7TDMI.
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
@end example

@b{COMPLEX example:}

This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:

@enumerate
@item @b{Unform tap names} - See: Tap Naming Convention
@item @b{_TARGETNAME} is created at the end where used.
@end enumerate

@example
if @{ [info exists FLASHTAPID ] @} @{
   set _FLASHTAPID $FLASHTAPID
@} else @{
   set _FLASHTAPID 0x25966041
@}
jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 -expected-id $_FLASHTAPID

if @{ [info exists CPUTAPID ] @} @{
   set _CPUTAPID $CPUTAPID
@} else @{
   set _CPUTAPID 0x25966041
@}
jtag newtap $_CHIPNAME cpu   -irlen 4 -ircapture 0xf -irmask 0xe -expected-id $_CPUTAPID


if @{ [info exists BSTAPID ] @} @{
   set _BSTAPID $BSTAPID
@} else @{
   set _BSTAPID 0x1457f041
@}
jtag newtap $_CHIPNAME bs    -irlen 5 -ircapture 0x1 -irmask 0x1 -expected-id $_BSTAPID

set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
@end example

@b{Tap Naming Convention}

See the command ``jtag newtap'' for detail, but in breif the names you should use are:

@itemize @bullet
@item @b{tap}
@item @b{cpu}
@item @b{flash}
@item @b{bs}
@item @b{jrc}
@item @b{unknownN} - it happens :-(
@end itemize

@subsection Reset Configuration

Some chips have specific ways the TRST and SRST signals are
managed. If these are @b{CHIP SPECIFIC} they go here, if they are
@b{BOARD SPECIFIC} they go in the board file.

@subsection Work Areas

Work areas are small RAM areas used by OpenOCD to speed up downloads,
and to download small snippits of code to program flash chips.  

If the chip includes an form of ``on-chip-ram'' - and many do - define
a reasonable work area and use the ``backup'' option.

@b{PROBLEMS:} On more complex chips, this ``work area'' may become
inaccessable if/when the application code enables or disables the MMU.

@subsection ARM Core Specific Hacks

If the chip has a DCC, enable it. If the chip is an arm9 with some
special high speed download - enable it.

If the chip has an ARM ``vector catch'' feature - by defeault enable
it for Undefined Instructions, Data Abort, and Prefetch Abort, if the
user is really writing a handler for those situations - they can
easily disable it.  Experiance has shown the ``vector catch'' is
helpful - for common programing errors.

If present, the MMU, the MPU and the CACHE should be disabled.

@subsection Internal Flash Configuration

This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.

@b{Never ever} in the ``target configuration file'' define any type of
flash that is external to the chip. (For example the BOOT flash on
Chip Select 0). The BOOT flash information goes in a board file - not
the TARGET (chip) file.

Examples:
@itemize @bullet
@item at91sam7x256 - has 256K flash YES enable it.
@item str912 - has flash internal YES enable it.
@item imx27 - uses boot flash on CS0 - it goes in the board file.
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize

@node About JIM-Tcl
@chapter About JIM-Tcl
@cindex JIM Tcl
@cindex tcl

OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can
learn more about JIM here: @url{http://jim.berlios.de}

@itemize @bullet
@item @b{JIM vrs 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
impliments the basic TCL command set along. In contrast: Tcl 8.6 is a
4.2MEG 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 interpretor today (28/nov/2008) is a mixture of (newer)
JIM-Tcl commands, and (older) the orginal command interpretor.

@item @b{Commands}
976
@* At the OpenOCD telnet command line (or via the GDB mon command) one
977
978
979
980
981
982
983
984
985
986
987
988
can type a Tcl for() loop, set variables, etc.

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

@item @b{Need a Crash Course In TCL?}
@* See: @xref{TCL Crash Course}.
@end itemize


@node Daemon Configuration
@chapter Daemon Configuration
989
The commands here are commonly found in the openocd.cfg file and are
990
991
992
used to specify what TCP/IP ports are used, and how GDB should be
supported.
@section init
993
@cindex init
994
995
996
997
998
999
1000
This command terminates the configuration stage and
enters the normal command mode. This can be useful to add commands to
the startup scripts and commands such as resetting the target,
programming flash, etc. To reset the CPU upon startup, add "init" and
"reset" at the end of the config script or at the end of the OpenOCD
command line using the @option{-c} command line switch.

For faster browsing, not all history is shown. View entire blame