1 \input texinfo @c -*-texinfo-*-
3 @setfilename openocd.info
4 @settitle Open On-Chip Debugger (OpenOCD)
5 @dircategory Development
8 * OpenOCD: (openocd). Open On-Chip Debugger.
17 @item Copyright @copyright{} 2008 The OpenOCD Project
18 @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
19 @item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
20 @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
24 Permission is granted to copy, distribute and/or modify this document
25 under the terms of the GNU Free Documentation License, Version 1.2 or
26 any later version published by the Free Software Foundation; with no
27 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
28 Texts. A copy of the license is included in the section entitled ``GNU
29 Free Documentation License''.
34 @title Open On-Chip Debugger (OpenOCD)
35 @subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
36 @subtitle @value{UPDATED}
38 @vskip 0pt plus 1filll
45 @node Top, About, , (dir)
48 This manual documents edition @value{EDITION} of the Open On-Chip Debugger
49 (OpenOCD) version @value{VERSION}, @value{UPDATED}.
54 * About:: About OpenOCD
55 * Developers:: OpenOCD Developers
56 * Building OpenOCD:: Building OpenOCD From SVN
57 * JTAG Hardware Dongles:: JTAG Hardware Dongles
58 * Running:: Running OpenOCD
59 * Simple Configuration Files:: Simple Configuration Files
60 * Config File Guidelines:: Config File Guidelines
61 * About JIM-Tcl:: About JIM-Tcl
62 * Daemon Configuration:: Daemon Configuration
63 * Interface - Dongle Configuration:: Interface - Dongle Configuration
64 * Reset Configuration:: Reset Configuration
65 * Tap Creation:: Tap Creation
66 * Target Configuration:: Target Configuration
67 * Flash Commands:: Flash Commands
68 * NAND Flash Commands:: NAND Flash Commands
69 * General Commands:: General Commands
70 * JTAG Commands:: JTAG Commands
71 * Sample Scripts:: Sample Target Scripts
73 * GDB and OpenOCD:: Using GDB and OpenOCD
74 * Tcl Scripting API:: Tcl Scripting API
75 * Upgrading:: Deprecated/Removed Commands
76 * Target Library:: Target Library
77 * FAQ:: Frequently Asked Questions
78 * Tcl Crash Course:: Tcl Crash Course
79 * License:: GNU Free Documentation License
80 @comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
81 @comment case issue with ``Index.html'' and ``index.html''
82 @comment Occurs when creating ``--html --no-split'' output
83 @comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
84 * OpenOCD Concept Index:: Concept Index
85 * Command and Driver Index:: Command and Driver Index
92 OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
93 University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
94 Since that time, the project has grown into an active open-source project,
95 supported by a diverse community of software and hardware developers from
98 @section What is OpenOCD?
100 The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
101 in-system programming and boundary-scan testing for embedded target
104 @b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
105 with the JTAG (IEEE 1149.1) compliant taps on your target board.
107 @b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
108 based, parallel port based, and other standalone boxes that run
109 OpenOCD internally. @xref{JTAG Hardware Dongles}.
111 @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
112 ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
113 Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
114 debugged via the GDB protocol.
116 @b{Flash Programing:} Flash writing is supported for external CFI
117 compatible NOR flashes (Intel and AMD/Spansion command set) and several
118 internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
119 STM32x). Preliminary support for various NAND flash controllers
120 (LPC3180, Orion, S3C24xx, more) controller is included.
122 @section OpenOCD Web Site
124 The OpenOCD web site provides the latest public news from the community:
126 @uref{http://openocd.berlios.de/web/}
130 @chapter OpenOCD Developer Resources
133 If you are interested in improving the state of OpenOCD's debugging and
134 testing support, new contributions will be welcome. Motivated developers
135 can produce new target, flash or interface drivers, improve the
136 documentation, as well as more conventional bug fixes and enhancements.
138 The resources in this chapter are available for developers wishing to explore
139 or expand the OpenOCD source code.
141 @section OpenOCD Subversion Repository
143 The ``Building From Source'' section provides instructions to retrieve
144 and and build the latest version of the OpenOCD source code.
145 @xref{Building OpenOCD}.
147 Developers that want to contribute patches to the OpenOCD system are
148 @b{strongly} encouraged to base their work off of the most recent trunk
149 revision. Patches created against older versions may require additional
150 work from their submitter in order to be updated for newer releases.
152 @section Doxygen Developer Manual
154 During the development of the 0.2.0 release, the OpenOCD project began
155 providing a Doxygen reference manual. This document contains more
156 technical information about the software internals, development
157 processes, and similar documentation:
159 @uref{http://openocd.berlios.de/doc/doxygen/index.html}
161 This document is a work-in-progress, but contributions would be welcome
162 to fill in the gaps. All of the source files are provided in-tree,
163 listed in the Doxyfile configuration in the top of the repository trunk.
165 @section OpenOCD Developer Mailing List
167 The OpenOCD Developer Mailing List provides the primary means of
168 communication between developers:
170 @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
172 All drivers developers are enouraged to also subscribe to the list of
173 SVN commits to keep pace with the ongoing changes:
175 @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
177 @node Building OpenOCD
178 @chapter Building OpenOCD
181 @section Pre-Built Tools
182 If you are interested in getting actual work done rather than building
183 OpenOCD, then check if your interface supplier provides binaries for
184 you. Chances are that that binary is from some SVN version that is more
185 stable than SVN trunk where bleeding edge development takes place.
187 @section Packagers Please Read!
189 You are a @b{PACKAGER} of OpenOCD if you
192 @item @b{Sell dongles} and include pre-built binaries
193 @item @b{Supply tools} i.e.: A complete development solution
194 @item @b{Supply IDEs} like Eclipse, or RHIDE, etc.
195 @item @b{Build packages} i.e.: RPM files, or DEB files for a Linux Distro
198 As a @b{PACKAGER}, you will experience first reports of most issues.
199 When you fix those problems for your users, your solution may help
200 prevent hundreds (if not thousands) of other questions from other users.
202 If something does not work for you, please work to inform the OpenOCD
203 developers know how to improve the system or documentation to avoid
204 future problems, and follow-up to help us ensure the issue will be fully
205 resolved in our future releases.
207 That said, the OpenOCD developers would also like you to follow a few
211 @item @b{Always build with printer ports enabled.}
212 @item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
216 @item @b{Why YES to LIBFTDI + LIBUSB?}
218 @item @b{LESS} work - libusb perhaps already there
219 @item @b{LESS} work - identical code, multiple platforms
220 @item @b{MORE} dongles are supported
221 @item @b{MORE} platforms are supported
222 @item @b{MORE} complete solution
224 @item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
226 @item @b{LESS} speed - some say it is slower
227 @item @b{LESS} complex to distribute (external dependencies)
231 @section Building From Source
233 You can download the current SVN version with an SVN client of your choice from the
234 following repositories:
236 @uref{svn://svn.berlios.de/openocd/trunk}
240 @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
242 Using the SVN command line client, you can use the following command to fetch the
243 latest version (make sure there is no (non-svn) directory called "openocd" in the
247 svn checkout svn://svn.berlios.de/openocd/trunk openocd
250 Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
251 For building on Windows,
252 you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
253 other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
254 paths, resulting in obscure dependency errors (This is an observation I've gathered
255 from the logs of one user - correct me if I'm wrong).
257 You further need the appropriate driver files, if you want to build support for
258 a FTDI FT2232 based interface:
261 @item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
262 @item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
263 @item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
264 homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
267 libftdi is supported under Windows. Do not use versions earlier than 0.14.
269 In general, the D2XX driver provides superior performance (several times as fast),
270 but has the draw-back of being binary-only - though that isn't that bad, as it isn't
271 a kernel module, only a user space library.
273 To build OpenOCD (on both Linux and Cygwin), use the following commands:
279 Bootstrap generates the configure script, and prepares building on your system.
282 ./configure [options, see below]
285 Configure generates the Makefiles used to build OpenOCD.
292 Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
294 The configure script takes several options, specifying which JTAG interfaces
295 should be included (among other things):
299 @option{--enable-parport} - Enable building the PC parallel port driver.
301 @option{--enable-parport_ppdev} - Enable use of ppdev (/dev/parportN) for parport.
303 @option{--enable-parport_giveio} - Enable use of giveio for parport instead of ioperm.
305 @option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver.
307 @option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger.
309 @option{--enable-ioutil} - Enable ioutil functions - useful for standalone OpenOCD implementations.
311 @option{--enable-httpd} - Enable builtin httpd server - useful for standalone OpenOCD implementations.
313 @option{--enable-ep93xx} - Enable building support for EP93xx based SBCs.
315 @option{--enable-at91rm9200} - Enable building support for AT91RM9200 based SBCs.
317 @option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
319 @option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
321 @option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
323 @option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
324 give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
326 @option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver
327 on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked.
329 @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}. The 'shared' value 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.
331 @option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
333 @option{--enable-presto_ftd2xx} - Enable building support for ASIX Presto programmer using the FTD2XX driver.
335 @option{--enable-usbprog} - Enable building support for the USBprog JTAG programmer.
337 @option{--enable-oocd_trace} - Enable building support for the OpenOCD+trace ETM capture device.
339 @option{--enable-jlink} - Enable building support for the Segger J-Link JTAG programmer.
341 @option{--enable-vsllink} - Enable building support for the Versaloon-Link JTAG programmer.
343 @option{--enable-rlink} - Enable building support for the Raisonance RLink JTAG programmer.
345 @option{--enable-arm-jtag-ew} - Enable building support for the Olimex ARM-JTAG-EW programmer.
347 @option{--enable-dummy} - Enable building the dummy port driver.
350 @section Parallel Port Dongles
352 If you want to access the parallel port using the PPDEV interface you have to specify
353 both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
354 the @option{--enable-parport_ppdev} option actually is an option to the parport driver
355 (see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
357 The same is true for the @option{--enable-parport_giveio} option, you have to
358 use both the @option{--enable-parport} AND the @option{--enable-parport_giveio} option if you want to use giveio instead of ioperm parallel port access method.
360 @section FT2232C Based USB Dongles
362 There are 2 methods of using the FTD2232, either (1) using the
363 FTDICHIP.COM closed source driver, or (2) the open (and free) driver
364 libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
366 The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
367 TAR.GZ file. You must unpack them ``some where'' convient. As of this
368 writing (12/26/2008) FTDICHIP does not supply means to install these
369 files ``in an appropriate place'' As a result, there are two
370 ``./configure'' options that help.
372 Below is an example build process:
375 @item Check out the latest version of ``openocd'' from SVN.
377 @item If you are using the FTDICHIP.COM driver, download
378 and unpack the Windows or Linux FTD2xx drivers
379 (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
380 If you are using the libftdi driver, install that package
381 (e.g. @command{apt-get install libftdi} on systems with APT).
384 /home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents
385 /home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents
388 @item Configure with options resembling the following.
391 @item Cygwin FTDICHIP solution:
393 ./configure --prefix=/home/duane/mytools \
394 --enable-ft2232_ftd2xx \
395 --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
398 @item Linux FTDICHIP solution:
400 ./configure --prefix=/home/duane/mytools \
401 --enable-ft2232_ftd2xx \
402 --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
405 @item Cygwin/Linux LIBFTDI solution ... assuming that
407 @item For Windows -- that the Windows port of LIBUSB is in place.
408 @item For Linux -- that libusb has been built/installed and is in place.
409 @item That libftdi has been built and installed (relies on libusb).
412 Then configure the libftdi solution like this:
415 ./configure --prefix=/home/duane/mytools \
416 --enable-ft2232_libftdi
420 @item Then just type ``make'', and perhaps ``make install''.
424 @section Miscellaneous Configure Options
428 @option{--disable-option-checking} - Ignore unrecognized @option{--enable} and @option{--with} options.
430 @option{--enable-gccwarnings} - Enable extra gcc warnings during build.
433 @option{--enable-release} - Enable building of an OpenOCD release, generally
434 this is for developers. It simply omits the svn version string when the
435 openocd @option{-v} is executed.
438 @node JTAG Hardware Dongles
439 @chapter JTAG Hardware Dongles
448 Defined: @b{dongle}: A small device that plugins into a computer and serves as
449 an adapter .... [snip]
451 In the OpenOCD case, this generally refers to @b{a small adapater} one
452 attaches to your computer via USB or the Parallel Printer Port. The
453 execption being the Zylin ZY1000 which is a small box you attach via
454 an ethernet cable. The Zylin ZY1000 has the advantage that it does not
455 require any drivers to be installed on the developer PC. It also has
456 a built in web interface. It supports RTCK/RCLK or adaptive clocking
457 and has a built in relay to power cycle targets remotely.
460 @section Choosing a Dongle
462 There are three things you should keep in mind when choosing a dongle.
465 @item @b{Voltage} What voltage is your target? 1.8, 2.8, 3.3, or 5V? Does your dongle support it?
466 @item @b{Connection} Printer Ports - Does your computer have one?
467 @item @b{Connection} Is that long printer bit-bang cable practical?
468 @item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
471 @section Stand alone Systems
473 @b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
474 dongle, but a standalone box. The ZY1000 has the advantage that it does
475 not require any drivers installed on the developer PC. It also has
476 a built in web interface. It supports RTCK/RCLK or adaptive clocking
477 and has a built in relay to power cycle targets remotely.
479 @section USB FT2232 Based
481 There are many USB JTAG dongles on the market, many of them are based
482 on a chip from ``Future Technology Devices International'' (FTDI)
483 known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
484 See: @url{http://www.ftdichip.com} for more information.
485 In summer 2009, USB high speed (480 Mbps) versions of these FTDI
486 chips are starting to become available in JTAG adapters.
488 As of 28/Nov/2008, the following are supported:
492 @* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
494 @* See: @url{http://www.amontec.com/jtagkey.shtml}
496 @* See: @url{http://www.oocdlink.com} By Joern Kaipf
498 @* See: @url{http://www.signalyzer.com}
499 @item @b{evb_lm3s811}
500 @* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
501 @item @b{olimex-jtag}
502 @* See: @url{http://www.olimex.com}
504 @* See: @url{http://www.tincantools.com}
505 @item @b{turtelizer2}
507 @uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
508 @url{http://www.ethernut.de}
510 @* Link: @url{http://www.hitex.com/index.php?id=383}
512 @* Link @url{http://www.hitex.com/stm32-stick}
513 @item @b{axm0432_jtag}
514 @* Axiom AXM-0432 Link @url{http://www.axman.com}
516 @* Link @url{http://www.hitex.com/index.php?id=cortino}
519 @section USB JLINK based
520 There are several OEM versions of the Segger @b{JLINK} adapter. It is
521 an example of a micro controller based JTAG adapter, it uses an
522 AT91SAM764 internally.
525 @item @b{ATMEL SAMICE} Only works with ATMEL chips!
526 @* Link: @url{http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3892}
527 @item @b{SEGGER JLINK}
528 @* Link: @url{http://www.segger.com/jlink.html}
530 @* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
533 @section USB RLINK based
534 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.
537 @item @b{Raisonance RLink}
538 @* Link: @url{http://www.raisonance.com/products/RLink.php}
539 @item @b{STM32 Primer}
540 @* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
541 @item @b{STM32 Primer2}
542 @* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
548 @* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
550 @item @b{USB - Presto}
551 @* Link: @url{http://tools.asix.net/prg_presto.htm}
553 @item @b{Versaloon-Link}
554 @* Link: @url{http://www.simonqian.com/en/Versaloon}
556 @item @b{ARM-JTAG-EW}
557 @* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
560 @section IBM PC Parallel Printer Port Based
562 The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
563 and the MacGraigor Wiggler. There are many clones and variations of
568 @item @b{Wiggler} - There are many clones of this.
569 @* Link: @url{http://www.macraigor.com/wiggler.htm}
571 @item @b{DLC5} - From XILINX - There are many clones of this
572 @* Link: Search the web for: ``XILINX DLC5'' - it is no longer
573 produced, PDF schematics are easily found and it is easy to make.
575 @item @b{Amontec - JTAG Accelerator}
576 @* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
579 @* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
582 @*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
583 Improved parallel-port wiggler-style JTAG adapter}
585 @item @b{Wiggler_ntrst_inverted}
586 @* Yet another variation - See the source code, src/jtag/parport.c
588 @item @b{old_amt_wiggler}
589 @* Unknown - probably not on the market today
592 @* Link: Most likely @url{http://www.olimex.com/dev/arm-jtag.html} [another wiggler clone]
595 @* Link: @url{http://www.amontec.com/chameleon.shtml}
601 @* ispDownload from Lattice Semiconductor
602 @url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
605 @* From ST Microsystems;
606 @uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
607 FlashLINK JTAG programing cable for PSD and uPSD}
615 @* An EP93xx based Linux machine using the GPIO pins directly.
618 @* Like the EP93xx - but an ATMEL AT91RM9200 based solution using the GPIO pins on the chip.
624 @cindex running OpenOCD
626 @cindex --debug_level
630 The @option{--help} option shows:
634 --help | -h display this help
635 --version | -v display OpenOCD version
636 --file | -f use configuration file <name>
637 --search | -s dir to search for config files and scripts
638 --debug | -d set debug level <0-3>
639 --log_output | -l redirect log output to file <name>
640 --command | -c run <command>
641 --pipe | -p use pipes when talking to gdb
644 By default OpenOCD reads the file configuration file ``openocd.cfg''
645 in the current directory. To specify a different (or multiple)
646 configuration file, you can use the ``-f'' option. For example:
649 openocd -f config1.cfg -f config2.cfg -f config3.cfg
652 Once started, OpenOCD runs as a daemon, waiting for connections from
653 clients (Telnet, GDB, Other).
655 If you are having problems, you can enable internal debug messages via
658 Also it is possible to interleave commands w/config scripts using the
659 @option{-c} command line switch.
661 To enable debug output (when reporting problems or working on OpenOCD
662 itself), use the @option{-d} command line switch. This sets the
663 @option{debug_level} to "3", outputting the most information,
664 including debug messages. The default setting is "2", outputting only
665 informational messages, warnings and errors. You can also change this
666 setting from within a telnet or gdb session using @option{debug_level
667 <n>} @xref{debug_level}.
669 You can redirect all output from the daemon to a file using the
670 @option{-l <logfile>} switch.
672 Search paths for config/script files can be added to OpenOCD by using
673 the @option{-s <search>} switch. The current directory and the OpenOCD
674 target library is in the search path by default.
676 For details on the @option{-p} option. @xref{Connecting to GDB}.
678 Note! OpenOCD will launch the GDB & telnet server even if it can not
679 establish a connection with the target. In general, it is possible for
680 the JTAG controller to be unresponsive until the target is set up
681 correctly via e.g. GDB monitor commands in a GDB init script.
683 @node Simple Configuration Files
684 @chapter Simple Configuration Files
685 @cindex configuration
688 There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
691 @item A small openocd.cfg file which ``sources'' other configuration files
692 @item A monolithic openocd.cfg file
693 @item Many -f filename options on the command line
694 @item Your Mixed Solution
697 @section Small configuration file method
699 This is the preferred method. It is simple and works well for many
700 people. The developers of OpenOCD would encourage you to use this
701 method. If you create a new configuration please email new
702 configurations to the development list.
704 Here is an example of an openocd.cfg file for an ATMEL at91sam7x256
707 source [find interface/signalyzer.cfg]
709 # GDB can also flash my flash!
710 gdb_memory_map enable
711 gdb_flash_program enable
713 source [find target/sam7x256.cfg]
716 There are many example configuration scripts you can work with. You
717 should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
721 @item @b{board} - eval board level configurations
722 @item @b{interface} - specific dongle configurations
723 @item @b{target} - the target chips
724 @item @b{tcl} - helper scripts
725 @item @b{xscale} - things specific to the xscale.
728 Look first in the ``boards'' area, then the ``targets'' area. Often a board
729 configuration is a good example to work from.
731 @section Many -f filename options
732 Some believe this is a wonderful solution, others find it painful.
734 You can use a series of ``-f filename'' options on the command line,
735 OpenOCD will read each filename in sequence, for example:
738 openocd -f file1.cfg -f file2.cfg -f file2.cfg
741 You can also intermix various commands with the ``-c'' command line
744 @section Monolithic file
745 The ``Monolithic File'' dispenses with all ``source'' statements and
746 puts everything in one self contained (monolithic) file. This is not
749 Please try to ``source'' various files or use the multiple -f
752 @section Advice for you
753 Often, one uses a ``mixed approach''. Where possible, please try to
754 ``source'' common things, and if needed cut/paste parts of the
755 standard distribution configuration files as needed.
757 @b{REMEMBER:} The ``important parts'' of your configuration file are:
760 @item @b{Interface} - Defines the dongle
761 @item @b{Taps} - Defines the JTAG Taps
762 @item @b{GDB Targets} - What GDB talks to
763 @item @b{Flash Programing} - Very Helpful
766 Some key things you should look at and understand are:
769 @item The reset configuration of your debug environment as a whole
770 @item Is there a ``work area'' that OpenOCD can use?
771 @* For ARM - work areas mean up to 10x faster downloads.
772 @item For MMU/MPU based ARM chips (i.e.: ARM9 and later) will that work area still be available?
773 @item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
778 @node Config File Guidelines
779 @chapter Config File Guidelines
781 This section/chapter is aimed at developers and integrators of
782 OpenOCD. These are guidelines for creating new boards and new target
783 configurations as of 28/Nov/2008.
785 However, you, the user of OpenOCD, should be somewhat familiar with
786 this section as it should help explain some of the internals of what
787 you might be looking at.
789 The user should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
793 @*Think JTAG Dongle. Files that configure the JTAG dongle go here.
795 @* Think Circuit Board, PWA, PCB, they go by many names. Board files
796 contain initialization items that are specific to a board - for
797 example: The SDRAM initialization sequence for the board, or the type
798 of external flash and what address it is found at. Any initialization
799 sequence to enable that external flash or SDRAM should be found in the
800 board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
801 a CPU and an FPGA or CPLD.
803 @* Think chip. The ``target'' directory represents a JTAG tap (or
804 chip) OpenOCD should control, not a board. Two common types of targets
805 are ARM chips and FPGA or CPLD chips.
808 @b{If needed...} The user in their ``openocd.cfg'' file or the board
809 file might override a specific feature in any of the above files by
810 setting a variable or two before sourcing the target file. Or adding
811 various commands specific to their situation.
813 @section Interface Config Files
815 The user should be able to source one of these files via a command like this:
818 source [find interface/FOOBAR.cfg]
820 openocd -f interface/FOOBAR.cfg
823 A preconfigured interface file should exist for every interface in use
824 today, that said, perhaps some interfaces have only been used by the
825 sole developer who created it.
827 Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
829 @section Board Config Files
831 @b{Note: BOARD directory NEW as of 28/nov/2008}
833 The user should be able to source one of these files via a command like this:
836 source [find board/FOOBAR.cfg]
838 openocd -f board/FOOBAR.cfg
842 The board file should contain one or more @t{source [find
843 target/FOO.cfg]} statements along with any board specific things.
845 In summary the board files should contain (if present)
848 @item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
849 @item SDRAM configuration (size, speed, etc.
850 @item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
851 @item Multiple TARGET source statements
852 @item All things that are not ``inside a chip''
853 @item Things inside a chip go in a 'target' file
856 @section Target Config Files
858 The user should be able to source one of these files via a command like this:
861 source [find target/FOOBAR.cfg]
863 openocd -f target/FOOBAR.cfg
866 In summary the target files should contain
871 @item Reset configuration
873 @item CPU/Chip/CPU-Core specific features
877 @subsection Important variable names
879 By default, the end user should never need to set these
880 variables. However, if the user needs to override a setting they only
881 need to set the variable in a simple way.
885 @* This gives a name to the overall chip, and is used as part of the
886 tap identifier dotted name.
888 @* By default little - unless the chip or board is not normally used that way.
890 @* When OpenOCD examines the JTAG chain, it will attempt to identify
891 every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
892 to verify the tap id number verses configuration file and may issue an
893 error or warning like this. The hope is that this will help to pinpoint
894 problems in OpenOCD configurations.
897 Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
898 (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
899 Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678,
901 Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
902 Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
905 @item @b{_TARGETNAME}
906 @* By convention, this variable is created by the target configuration
907 script. The board configuration file may make use of this variable to
908 configure things like a ``reset init'' script, or other things
909 specific to that board and that target.
911 If the chip has 2 targets, use the names @b{_TARGETNAME0},
912 @b{_TARGETNAME1}, ... etc.
914 @b{Remember:} The ``board file'' may include multiple targets.
916 At no time should the name ``target0'' (the default target name if
917 none was specified) be used. The name ``target0'' is a hard coded name
918 - the next target on the board will be some other number.
919 In the same way, avoid using target numbers even when they are
920 permitted; use the right target name(s) for your board.
922 The user (or board file) should reasonably be able to:
925 source [find target/FOO.cfg]
926 $_TARGETNAME configure ... FOO specific parameters
928 source [find target/BAR.cfg]
929 $_TARGETNAME configure ... BAR specific parameters
934 @subsection Tcl Variables Guide Line
935 The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
937 Thus the rule we follow in OpenOCD is this: Variables that begin with
938 a leading underscore are temporary in nature, and can be modified and
939 used at will within a ?TARGET? configuration file.
941 @b{EXAMPLE:} The user should be able to do this:
945 # PXA270 #1 network side, big endian
946 # PXA270 #2 video side, little endian
950 source [find target/pxa270.cfg]
951 # variable: _TARGETNAME = network.cpu
952 # other commands can refer to the "network.cpu" tap.
953 $_TARGETNAME configure .... params for this CPU..
957 source [find target/pxa270.cfg]
958 # variable: _TARGETNAME = video.cpu
959 # other commands can refer to the "video.cpu" tap.
960 $_TARGETNAME configure .... params for this CPU..
964 source [find target/spartan3.cfg]
966 # Since $_TARGETNAME is temporal..
967 # these names still work!
968 network.cpu configure ... params
969 video.cpu configure ... params
973 @subsection Default Value Boiler Plate Code
975 All target configuration files should start with this (or a modified form)
979 if @{ [info exists CHIPNAME] @} @{
980 set _CHIPNAME $CHIPNAME
982 set _CHIPNAME sam7x256
985 if @{ [info exists ENDIAN] @} @{
991 if @{ [info exists CPUTAPID ] @} @{
992 set _CPUTAPID $CPUTAPID
994 set _CPUTAPID 0x3f0f0f0f
999 @subsection Creating Taps
1000 After the ``defaults'' are choosen [see above] the taps are created.
1002 @b{SIMPLE example:} such as an Atmel AT91SAM7X256
1006 set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
1007 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
1008 -expected-id $_CPUTAPID
1011 @b{COMPLEX example:}
1013 This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
1016 @item @b{Unform tap names} - See: Tap Naming Convention
1017 @item @b{_TARGETNAME} is created at the end where used.
1021 if @{ [info exists FLASHTAPID ] @} @{
1022 set _FLASHTAPID $FLASHTAPID
1024 set _FLASHTAPID 0x25966041
1026 jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 \
1027 -expected-id $_FLASHTAPID
1029 if @{ [info exists CPUTAPID ] @} @{
1030 set _CPUTAPID $CPUTAPID
1032 set _CPUTAPID 0x25966041
1034 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe \
1035 -expected-id $_CPUTAPID
1038 if @{ [info exists BSTAPID ] @} @{
1039 set _BSTAPID $BSTAPID
1041 set _BSTAPID 0x1457f041
1043 jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 \
1044 -expected-id $_BSTAPID
1046 set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
1049 @b{Tap Naming Convention}
1051 See the command ``jtag newtap'' for detail, but in brief the names you should use are:
1060 @item @b{unknownN} - it happens :-(
1063 @subsection Reset Configuration
1065 Some chips have specific ways the TRST and SRST signals are
1066 managed. If these are @b{CHIP SPECIFIC} they go here, if they are
1067 @b{BOARD SPECIFIC} they go in the board file.
1069 @subsection Work Areas
1071 Work areas are small RAM areas used by OpenOCD to speed up downloads,
1072 and to download small snippets of code to program flash chips.
1074 If the chip includes a form of ``on-chip-ram'' - and many do - define
1075 a reasonable work area and use the ``backup'' option.
1077 @b{PROBLEMS:} On more complex chips, this ``work area'' may become
1078 inaccessible if/when the application code enables or disables the MMU.
1080 @subsection ARM Core Specific Hacks
1082 If the chip has a DCC, enable it. If the chip is an ARM9 with some
1083 special high speed download features - enable it.
1085 If the chip has an ARM ``vector catch'' feature - by default enable
1086 it for Undefined Instructions, Data Abort, and Prefetch Abort, if the
1087 user is really writing a handler for those situations - they can
1088 easily disable it. Experiance has shown the ``vector catch'' is
1089 helpful - for common programing errors.
1091 If present, the MMU, the MPU and the CACHE should be disabled.
1093 Some ARM cores are equipped with trace support, which permits
1094 examination of the instruction and data bus activity. Trace
1095 activity is controlled through an ``Embedded Trace Module'' (ETM)
1096 on one of the core's scan chains. The ETM emits voluminous data
1097 through a ``trace port''. (@xref{ARM Tracing}.)
1098 If you are using an external trace port,
1099 configure it in your board config file.
1100 If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
1101 configure it in your target config file.
1104 etm config $_TARGETNAME 16 normal full etb
1105 etb config $_TARGETNAME $_CHIPNAME.etb
1108 @subsection Internal Flash Configuration
1110 This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
1112 @b{Never ever} in the ``target configuration file'' define any type of
1113 flash that is external to the chip. (For example a BOOT flash on
1114 Chip Select 0.) Such flash information goes in a board file - not
1115 the TARGET (chip) file.
1119 @item at91sam7x256 - has 256K flash YES enable it.
1120 @item str912 - has flash internal YES enable it.
1121 @item imx27 - uses boot flash on CS0 - it goes in the board file.
1122 @item pxa270 - again - CS0 flash - it goes in the board file.
1126 @chapter About JIM-Tcl
1130 OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can
1131 learn more about JIM here: @url{http://jim.berlios.de}
1134 @item @b{JIM vs. Tcl}
1135 @* JIM-TCL is a stripped down version of the well known Tcl language,
1136 which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
1137 fewer features. JIM-Tcl is a single .C file and a single .H file and
1138 impliments the basic Tcl command set along. In contrast: Tcl 8.6 is a
1139 4.2 MB .zip file containing 1540 files.
1141 @item @b{Missing Features}
1142 @* Our practice has been: Add/clone the real Tcl feature if/when
1143 needed. We welcome JIM Tcl improvements, not bloat.
1146 @* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
1147 command interpreter today (28/nov/2008) is a mixture of (newer)
1148 JIM-Tcl commands, and (older) the orginal command interpreter.
1151 @* At the OpenOCD telnet command line (or via the GDB mon command) one
1152 can type a Tcl for() loop, set variables, etc.
1154 @item @b{Historical Note}
1155 @* JIM-Tcl was introduced to OpenOCD in spring 2008.
1157 @item @b{Need a crash course in Tcl?}
1158 @* See: @xref{Tcl Crash Course}.
1161 @node Daemon Configuration
1162 @chapter Daemon Configuration
1163 @cindex initialization
1164 The commands here are commonly found in the openocd.cfg file and are
1165 used to specify what TCP/IP ports are used, and how GDB should be
1168 @section Configuration Stage
1169 @cindex configuration stage
1170 @cindex configuration command
1172 When the OpenOCD server process starts up, it enters a
1173 @emph{configuration stage} which is the only time that
1174 certain commands, @emph{configuration commands}, may be issued.
1175 Those configuration commands include declaration of TAPs
1176 and other basic setup.
1177 The server must leave the configuration stage before it
1178 may access or activate TAPs.
1179 After it leaves this stage, configuration commands may no
1182 @deffn {Config Command} init
1183 This command terminates the configuration stage and
1184 enters the normal command mode. This can be useful to add commands to
1185 the startup scripts and commands such as resetting the target,
1186 programming flash, etc. To reset the CPU upon startup, add "init" and
1187 "reset" at the end of the config script or at the end of the OpenOCD
1188 command line using the @option{-c} command line switch.
1190 If this command does not appear in any startup/configuration file
1191 OpenOCD executes the command for you after processing all
1192 configuration files and/or command line options.
1194 @b{NOTE:} This command normally occurs at or near the end of your
1195 openocd.cfg file to force OpenOCD to ``initialize'' and make the
1196 targets ready. For example: If your openocd.cfg file needs to
1197 read/write memory on your target, @command{init} must occur before
1198 the memory read/write commands. This includes @command{nand probe}.
1201 @section TCP/IP Ports
1205 The OpenOCD server accepts remote commands in several syntaxes.
1206 Each syntax uses a different TCP/IP port, which you may specify
1207 only during configuration (before those ports are opened).
1209 @deffn {Command} gdb_port (number)
1211 Specify or query the first port used for incoming GDB connections.
1212 The GDB port for the
1213 first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
1214 When not specified during the configuration stage,
1215 the port @var{number} defaults to 3333.
1218 @deffn {Command} tcl_port (number)
1219 Specify or query the port used for a simplified RPC
1220 connection that can be used by clients to issue TCL commands and get the
1221 output from the Tcl engine.
1222 Intended as a machine interface.
1223 When not specified during the configuration stage,
1224 the port @var{number} defaults to 6666.
1227 @deffn {Command} telnet_port (number)
1228 Specify or query the
1229 port on which to listen for incoming telnet connections.
1230 This port is intended for interaction with one human through TCL commands.
1231 When not specified during the configuration stage,
1232 the port @var{number} defaults to 4444.
1235 @section GDB Configuration
1236 @anchor{GDB Configuration}
1238 @cindex GDB configuration
1239 You can reconfigure some GDB behaviors if needed.
1240 The ones listed here are static and global.
1241 @xref{Target Create}, about declaring individual targets.
1242 @xref{Target Events}, about configuring target-specific event handling.
1244 @deffn {Command} gdb_breakpoint_override <hard|soft|disable>
1245 @anchor{gdb_breakpoint_override}
1246 Force breakpoint type for gdb @command{break} commands.
1247 The raison d'etre for this option is to support GDB GUI's which don't
1248 distinguish hard versus soft breakpoints, if the default OpenOCD and
1249 GDB behaviour is not sufficient. GDB normally uses hardware
1250 breakpoints if the memory map has been set up for flash regions.
1252 This option replaces older arm7_9 target commands that addressed
1256 @deffn {Config command} gdb_detach <resume|reset|halt|nothing>
1257 Configures what OpenOCD will do when GDB detaches from the daemon.
1258 Default behaviour is @var{resume}.
1261 @deffn {Config command} gdb_flash_program <enable|disable>
1262 @anchor{gdb_flash_program}
1263 Set to @var{enable} to cause OpenOCD to program the flash memory when a
1264 vFlash packet is received.
1265 The default behaviour is @var{enable}.
1268 @deffn {Config command} gdb_memory_map <enable|disable>
1269 Set to @var{enable} to cause OpenOCD to send the memory configuration to GDB when
1270 requested. GDB will then know when to set hardware breakpoints, and program flash
1271 using the GDB load command. @command{gdb_flash_program enable} must also be enabled
1272 for flash programming to work.
1273 Default behaviour is @var{enable}.
1274 @xref{gdb_flash_program}.
1277 @deffn {Config command} gdb_report_data_abort <enable|disable>
1278 Specifies whether data aborts cause an error to be reported
1279 by GDB memory read packets.
1280 The default behaviour is @var{disable};
1281 use @var{enable} see these errors reported.
1284 @node Interface - Dongle Configuration
1285 @chapter Interface - Dongle Configuration
1286 Interface commands are normally found in an interface configuration
1287 file which is sourced by your openocd.cfg file. These commands tell
1288 OpenOCD what type of JTAG dongle you have and how to talk to it.
1289 @section Simple Complete Interface Examples
1290 @b{A Turtelizer FT2232 Based JTAG Dongle}
1294 ft2232_device_desc "Turtelizer JTAG/RS232 Adapter A"
1295 ft2232_layout turtelizer2
1296 ft2232_vid_pid 0x0403 0xbdc8
1303 @b{A Raisonance RLink}
1312 parport_cable wiggler
1317 interface arm-jtag-ew
1319 @section Interface Command
1321 The interface command tells OpenOCD what type of JTAG dongle you are
1322 using. Depending on the type of dongle, you may need to have one or
1323 more additional commands.
1327 @item @b{interface} <@var{name}>
1329 @*Use the interface driver <@var{name}> to connect to the
1330 target. Currently supported interfaces are
1335 @* PC parallel port bit-banging (Wigglers, PLD download cable, ...)
1337 @item @b{amt_jtagaccel}
1338 @* Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
1342 @* FTDI FT2232 (USB) based devices using either the open-source libftdi or the binary only
1343 FTD2XX driver. The FTD2XX is superior in performance, but not available on every
1344 platform. The libftdi uses libusb, and should be portable to all systems that provide
1348 @*Cirrus Logic EP93xx based single-board computer bit-banging (in development)
1351 @* ASIX PRESTO USB JTAG programmer.
1354 @* usbprog is a freely programmable USB adapter.
1357 @* Gateworks GW16012 JTAG programmer.
1360 @* Segger jlink USB adapter
1363 @* Raisonance RLink USB adapter
1366 @* vsllink is part of Versaloon which is a versatile USB programmer.
1368 @item @b{arm-jtag-ew}
1369 @* Olimex ARM-JTAG-EW USB adapter
1370 @comment - End parameters
1372 @comment - End Interface
1374 @subsection parport options
1377 @item @b{parport_port} <@var{number}>
1378 @cindex parport_port
1379 @*Either the address of the I/O port (default: 0x378 for LPT1) or the number of
1380 the @file{/dev/parport} device
1382 When using PPDEV to access the parallel port, use the number of the parallel port:
1383 @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
1384 you may encounter a problem.
1385 @item @b{parport_cable} <@var{name}>
1386 @cindex parport_cable
1387 @*The layout of the parallel port cable used to connect to the target.
1388 Currently supported cables are
1392 The original Wiggler layout, also supported by several clones, such
1393 as the Olimex ARM-JTAG
1396 Same as original wiggler except an led is fitted on D5.
1397 @item @b{wiggler_ntrst_inverted}
1398 @cindex wiggler_ntrst_inverted
1399 Same as original wiggler except TRST is inverted.
1400 @item @b{old_amt_wiggler}
1401 @cindex old_amt_wiggler
1402 The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
1403 version available from the website uses the original Wiggler layout ('@var{wiggler}')
1406 The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to
1407 program the Chameleon itself, not a connected target.
1410 The Xilinx Parallel cable III.
1413 The parallel port adapter found on the 'Karo Triton 1 Development Board'.
1414 This is also the layout used by the HollyGates design
1415 (see @uref{http://www.lartmaker.nl/projects/jtag/}).
1418 The ST Parallel cable.
1421 Same as original wiggler except SRST and TRST connections reversed and
1422 TRST is also inverted.
1425 Altium Universal JTAG cable.
1427 @item @b{parport_write_on_exit} <@var{on}|@var{off}>
1428 @cindex parport_write_on_exit
1429 @*This will configure the parallel driver to write a known value to the parallel
1430 interface on exiting OpenOCD
1433 @subsection amt_jtagaccel options
1435 @item @b{parport_port} <@var{number}>
1436 @cindex parport_port
1437 @*Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
1438 @file{/dev/parport} device
1440 @subsection ft2232 options
1443 @item @b{ft2232_device_desc} <@var{description}>
1444 @cindex ft2232_device_desc
1445 @*The USB device description of the FTDI FT2232 device. If not
1446 specified, the FTDI default value is used. This setting is only valid
1447 if compiled with FTD2XX support.
1449 @b{TODO:} Confirm the following: On Windows the name needs to end with
1450 a ``space A''? Or not? It has to do with the FTD2xx driver. When must
1451 this be added and when must it not be added? Why can't the code in the
1452 interface or in OpenOCD automatically add this if needed? -- Duane.
1454 @item @b{ft2232_serial} <@var{serial-number}>
1455 @cindex ft2232_serial
1456 @*The serial number of the FTDI FT2232 device. If not specified, the FTDI default
1458 @item @b{ft2232_layout} <@var{name}>
1459 @cindex ft2232_layout
1460 @*The layout of the FT2232 GPIO signals used to control output-enables and reset
1461 signals. Valid layouts are
1464 "USBJTAG-1" layout described in the original OpenOCD diploma thesis
1466 Amontec JTAGkey and JTAGkey-Tiny
1467 @item @b{signalyzer}
1469 @item @b{olimex-jtag}
1472 American Microsystems M5960
1473 @item @b{evb_lm3s811}
1474 Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
1475 SRST signals on external connector
1478 @item @b{stm32stick}
1479 Hitex STM32 Performance Stick
1480 @item @b{flyswatter}
1481 Tin Can Tools Flyswatter
1482 @item @b{turtelizer2}
1483 egnite Software turtelizer2
1486 @item @b{axm0432_jtag}
1489 Hitex Cortino JTAG interface
1492 @item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
1493 @*The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
1494 default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, e.g.
1496 ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
1498 @item @b{ft2232_latency} <@var{ms}>
1499 @*On some systems using FT2232 based JTAG interfaces the FT_Read function call in
1500 ft2232_read() fails to return the expected number of bytes. This can be caused by
1501 USB communication delays and has proved hard to reproduce and debug. Setting the
1502 FT2232 latency timer to a larger value increases delays for short USB packets but it
1503 also reduces the risk of timeouts before receiving the expected number of bytes.
1504 The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
1507 @subsection ep93xx options
1508 @cindex ep93xx options
1509 Currently, there are no options available for the ep93xx interface.
1513 JTAG clock setup is part of system setup.
1514 It @emph{does not belong with interface setup} since any interface
1515 only knows a few of the constraints for the JTAG clock speed.
1516 Sometimes the JTAG speed is
1517 changed during the target initialization process: (1) slow at
1518 reset, (2) program the CPU clocks, (3) run fast.
1519 Both the "slow" and "fast" clock rates are functions of the
1520 oscillators used, the chip, the board design, and sometimes
1521 power management software that may be active.
1523 The speed used during reset can be adjusted using pre_reset
1524 and post_reset event handlers.
1525 @xref{Target Events}.
1527 If your system supports adaptive clocking (RTCK), configuring
1528 JTAG to use that is probably the most robust approach.
1529 However, it introduces delays to synchronize clocks; so it
1530 may not be the fastest solution.
1532 @b{NOTE:} Script writers should consider using @command{jtag_rclk}
1533 instead of @command{jtag_khz}.
1535 @deffn {Command} jtag_khz max_speed_kHz
1536 A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
1537 JTAG interfaces usually support a limited number of
1538 speeds. The speed actually used won't be faster
1539 than the speed specified.
1541 As a rule of thumb, if you specify a clock rate make
1542 sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
1543 This is especially true for synthesized cores (ARMxxx-S).
1545 Speed 0 (khz) selects RTCK method.
1547 If your system uses RTCK, you won't need to change the
1548 JTAG clocking after setup.
1549 Not all interfaces, boards, or targets support ``rtck''.
1550 If the interface device can not
1551 support it, an error is returned when you try to use RTCK.
1554 @defun jtag_rclk fallback_speed_kHz
1556 This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK.
1557 If that fails (maybe the interface, board, or target doesn't
1558 support it), falls back to the specified frequency.
1560 # Fall back to 3mhz if RTCK is not supported
1565 @node Reset Configuration
1566 @chapter Reset Configuration
1567 @cindex Reset Configuration
1569 Every system configuration may require a different reset
1570 configuration. This can also be quite confusing.
1571 Resets also interact with @var{reset-init} event handlers,
1572 which do things like setting up clocks and DRAM, and
1573 JTAG clock rates. (@xref{JTAG Speed}.)
1574 Please see the various board files for examples.
1577 To maintainers and integrators:
1578 Reset configuration touches several things at once.
1579 Normally the board configuration file
1580 should define it and assume that the JTAG adapter supports
1581 everything that's wired up to the board's JTAG connector.
1582 However, the target configuration file could also make note
1583 of something the silicon vendor has done inside the chip,
1584 which will be true for most (or all) boards using that chip.
1585 And when the JTAG adapter doesn't support everything, the
1586 system configuration file will need to override parts of
1587 the reset configuration provided by other files.
1590 @section Types of Reset
1592 There are many kinds of reset possible through JTAG, but
1593 they may not all work with a given board and adapter.
1594 That's part of why reset configuration can be error prone.
1598 @emph{System Reset} ... the @emph{SRST} hardware signal
1599 resets all chips connected to the JTAG adapter, such as processors,
1600 power management chips, and I/O controllers. Normally resets triggered
1601 with this signal behave exactly like pressing a RESET button.
1603 @emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
1604 just the TAP controllers connected to the JTAG adapter.
1605 Such resets should not be visible to the rest of the system; resetting a
1606 device's the TAP controller just puts that controller into a known state.
1608 @emph{Emulation Reset} ... many devices can be reset through JTAG
1609 commands. These resets are often distinguishable from system
1610 resets, either explicitly (a "reset reason" register says so)
1611 or implicitly (not all parts of the chip get reset).
1613 @emph{Other Resets} ... system-on-chip devices often support
1614 several other types of reset.
1615 You may need to arrange that a watchdog timer stops
1616 while debugging, preventing a watchdog reset.
1617 There may be individual module resets.
1620 In the best case, OpenOCD can hold SRST, then reset
1621 the TAPs via TRST and send commands through JTAG to halt the
1622 CPU at the reset vector before the 1st instruction is executed.
1623 Then when it finally releases the SRST signal, the system is
1624 halted under debugger control before any code has executed.
1625 This is the behavior required to support the @command{reset halt}
1626 and @command{reset init} commands; after @command{reset init} a
1627 board-specific script might do things like setting up DRAM.
1628 (@xref{Reset Command}.)
1630 @section SRST and TRST Signal Issues
1632 Because SRST and TRST are hardware signals, they can have a
1633 variety of system-specific constraints. Some of the most
1638 @item @emph{Signal not available} ... Some boards don't wire
1639 SRST or TRST to the JTAG connector. Some JTAG adapters don't
1640 support such signals even if they are wired up.
1641 Use the @command{reset_config} @var{signals} options to say
1642 when one of those signals is not connected.
1643 When SRST is not available, your code might not be able to rely
1644 on controllers having been fully reset during code startup.
1646 @item @emph{Signals shorted} ... Sometimes a chip, board, or
1647 adapter will connect SRST to TRST, instead of keeping them separate.
1648 Use the @command{reset_config} @var{combination} options to say
1649 when those signals aren't properly independent.
1651 @item @emph{Timing} ... Reset circuitry like a resistor/capacitor
1652 delay circuit, reset supervisor, or on-chip features can extend
1653 the effect of a JTAG adapter's reset for some time after the adapter
1654 stops issuing the reset. For example, there may be chip or board
1655 requirements that all reset pulses last for at least a
1656 certain amount of time; and reset buttons commonly have
1657 hardware debouncing.
1658 Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
1659 commands to say when extra delays are needed.
1661 @item @emph{Drive type} ... Reset lines often have a pullup
1662 resistor, letting the JTAG interface treat them as open-drain
1663 signals. But that's not a requirement, so the adapter may need
1664 to use push/pull output drivers.
1665 Also, with weak pullups it may be advisable to drive
1666 signals to both levels (push/pull) to minimize rise times.
1667 Use the @command{reset_config} @var{trst_type} and
1668 @var{srst_type} parameters to say how to drive reset signals.
1671 There can also be other issues.
1672 Some devices don't fully conform to the JTAG specifications.
1673 Trivial system-specific differences are common, such as
1674 SRST and TRST using slightly different names.
1675 There are also vendors who distribute key JTAG documentation for
1676 their chips only to developers who have signed a Non-Disclosure
1679 Sometimes there are chip-specific extensions like a requirement to use
1680 the normally-optional TRST signal (precluding use of JTAG adapters which
1681 don't pass TRST through), or needing extra steps to complete a TAP reset.
1683 In short, SRST and especially TRST handling may be very finicky,
1684 needing to cope with both architecture and board specific constraints.
1686 @section Commands for Handling Resets
1688 @deffn {Command} jtag_nsrst_delay milliseconds
1689 How long (in milliseconds) OpenOCD should wait after deasserting
1690 nSRST (active-low system reset) before starting new JTAG operations.
1691 When a board has a reset button connected to SRST line it will
1692 probably have hardware debouncing, implying you should use this.
1695 @deffn {Command} jtag_ntrst_delay milliseconds
1696 How long (in milliseconds) OpenOCD should wait after deasserting
1697 nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
1700 @deffn {Command} reset_config mode_flag ...
1701 This command tells OpenOCD the reset configuration
1702 of your combination of JTAG board and target in target
1703 configuration scripts.
1705 If you have an interface that does not support SRST and
1706 TRST(unlikely), then you may be able to work around that
1707 problem by using a reset_config command to override any
1708 settings in the target configuration script.
1710 SRST and TRST has a fairly well understood definition and
1711 behaviour in the JTAG specification, but vendors take
1712 liberties to achieve various more or less clearly understood
1713 goals. Sometimes documentation is available, other times it
1714 is not. OpenOCD has the reset_config command to allow OpenOCD
1715 to deal with the various common cases.
1717 The @var{mode_flag} options can be specified in any order, but only one
1718 of each type -- @var{signals}, @var{combination}, @var{trst_type},
1719 and @var{srst_type} -- may be specified at a time.
1720 If you don't provide a new value for a given type, its previous
1721 value (perhaps the default) is unchanged.
1722 For example, this means that you don't need to say anything at all about
1723 TRST just to declare that if the JTAG adapter should want to drive SRST,
1724 it must explicitly be driven high (@option{srst_push_pull}).
1726 @var{signals} can specify which of the reset signals are connected.
1727 For example, If the JTAG interface provides SRST, but the board doesn't
1728 connect that signal properly, then OpenOCD can't use it.
1729 Possible values are @option{none} (the default), @option{trst_only},
1730 @option{srst_only} and @option{trst_and_srst}.
1733 If your board provides SRST or TRST through the JTAG connector,
1734 you must declare that or else those signals will not be used.
1737 The @var{combination} is an optional value specifying broken reset
1738 signal implementations.
1739 The default behaviour if no option given is @option{separate},
1740 indicating everything behaves normally.
1741 @option{srst_pulls_trst} states that the
1742 test logic is reset together with the reset of the system (e.g. Philips
1743 LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
1744 the system is reset together with the test logic (only hypothetical, I
1745 haven't seen hardware with such a bug, and can be worked around).
1746 @option{combined} implies both @option{srst_pulls_trst} and
1747 @option{trst_pulls_srst}.
1749 The optional @var{trst_type} and @var{srst_type} parameters allow the
1750 driver mode of each reset line to be specified. These values only affect
1751 JTAG interfaces with support for different driver modes, like the Amontec
1752 JTAGkey and JTAGAccelerator. Also, they are necessarily ignored if the
1753 relevant signal (TRST or SRST) is not connected.
1755 Possible @var{trst_type} driver modes for the test reset signal (TRST)
1756 are @option{trst_push_pull} (default) and @option{trst_open_drain}.
1757 Most boards connect this signal to a pulldown, so the JTAG TAPs
1758 never leave reset unless they are hooked up to a JTAG adapter.
1760 Possible @var{srst_type} driver modes for the system reset signal (SRST)
1761 are the default @option{srst_open_drain}, and @option{srst_push_pull}.
1762 Most boards connect this signal to a pullup, and allow the
1763 signal to be pulled low by various events including system
1764 powerup and pressing a reset button.
1769 @chapter Tap Creation
1770 @cindex tap creation
1771 @cindex tap configuration
1773 In order for OpenOCD to control a target, a JTAG tap must be
1776 Commands to create taps are normally found in a configuration file and
1777 are not normally typed by a human.
1779 When a tap is created a @b{dotted.name} is created for the tap. Other
1780 commands use that dotted.name to manipulate or refer to the tap.
1784 @item @b{Debug Target} A tap can be used by a GDB debug target
1785 @item @b{Flash Programing} Some chips program the flash directly via JTAG,
1786 instead of indirectly by making a CPU do it.
1787 @item @b{Boundry Scan} Some chips support boundary scan.
1791 @section jtag newtap
1792 @b{@t{jtag newtap CHIPNAME TAPNAME configparams ....}}
1797 @cindex tap geometry
1799 @comment START options
1802 @* is a symbolic name of the chip.
1804 @* is a symbol name of a tap present on the chip.
1805 @item @b{Required configparams}
1806 @* Every tap has 3 required configparams, and several ``optional
1807 parameters'', the required parameters are:
1808 @comment START REQUIRED
1810 @item @b{-irlen NUMBER} - the length in bits of the instruction register, mostly 4 or 5 bits.
1811 @item @b{-ircapture NUMBER} - the IDCODE capture command, usually 0x01.
1812 @item @b{-irmask NUMBER} - the corresponding mask for the IR register. For
1813 some devices, there are bits in the IR that aren't used. This lets you mask
1814 them off when doing comparisons. In general, this should just be all ones for
1816 @comment END REQUIRED
1818 An example of a FOOBAR Tap
1820 jtag newtap foobar tap -irlen 7 -ircapture 0x42 -irmask 0x55
1822 Creates the tap ``foobar.tap'' with the instruction register (IR) is 7
1823 bits long, during Capture-IR 0x42 is loaded into the IR, and bits
1824 [6,4,2,0] are checked.
1826 @item @b{Optional configparams}
1827 @comment START Optional
1829 @item @b{-expected-id NUMBER}
1830 @* By default it is zero. If non-zero represents the
1831 expected tap ID used when the JTAG chain is examined. Repeat
1832 the option as many times as required if multiple id's can be
1833 expected. See below.
1836 @* By default not specified the tap is enabled. Some chips have a
1837 JTAG route controller (JRC) that is used to enable and/or disable
1838 specific JTAG taps. You can later enable or disable any JTAG tap via
1839 the command @b{jtag tapenable DOTTED.NAME} or @b{jtag tapdisable
1841 @comment END Optional
1844 @comment END OPTIONS
1847 @comment START NOTES
1849 @item @b{Technically}
1850 @* newtap is a sub command of the ``jtag'' command
1851 @item @b{Big Picture Background}
1852 @*GDB Talks to OpenOCD using the GDB protocol via
1853 TCP/IP. OpenOCD then uses the JTAG interface (the dongle) to
1854 control the JTAG chain on your board. Your board has one or more chips
1855 in a @i{daisy chain configuration}. Each chip may have one or more
1856 JTAG taps. GDB ends up talking via OpenOCD to one of the taps.
1857 @item @b{NAME Rules}
1858 @*Names follow ``C'' symbol name rules (start with alpha ...)
1859 @item @b{TAPNAME - Conventions}
1861 @item @b{tap} - should be used only FPGA or CPLD like devices with a single tap.
1862 @item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp}
1863 @item @b{flash} - if the chip has a flash tap, example: str912.flash
1864 @item @b{bs} - for boundary scan if this is a seperate tap.
1865 @item @b{etb} - for an embedded trace buffer (example: an ARM ETB11)
1866 @item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards)
1867 @item @b{unknownN} - where N is a number if you have no idea what the tap is for
1868 @item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap.
1869 @item @b{When in doubt} - use the chip maker's name in their data sheet.
1871 @item @b{DOTTED.NAME}
1872 @* @b{CHIPNAME}.@b{TAPNAME} creates the tap name, aka: the
1873 @b{Dotted.Name} is the @b{CHIPNAME} and @b{TAPNAME} combined with a
1874 dot (period); for example: @b{xilinx.tap}, @b{str912.flash},
1875 @b{omap3530.jrc}, or @b{stm32.cpu} The @b{dotted.name} is used in
1876 numerous other places to refer to various taps.
1878 @* The order this command appears via the config files is
1880 @item @b{Multi Tap Example}
1881 @* This example is based on the ST Microsystems STR912. See the ST
1882 document titled: @b{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
1883 28/102, Figure 3: JTAG chaining inside the STR91xFA}.
1885 @url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}
1886 @*@b{checked: 28/nov/2008}
1888 The diagram shows that the TDO pin connects to the flash tap, flash TDI
1889 connects to the CPU debug tap, CPU TDI connects to the boundary scan
1890 tap which then connects to the TDI pin.
1894 # create tap: 'str912.flash'
1895 jtag newtap str912 flash ... params ...
1896 # create tap: 'str912.cpu'
1897 jtag newtap str912 cpu ... params ...
1898 # create tap: 'str912.bs'
1899 jtag newtap str912 bs ... params ...
1902 @item @b{Note: Deprecated} - Index Numbers
1903 @* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this
1904 feature is still present, however its use is highly discouraged and
1905 should not be counted upon. Update all of your scripts to use
1906 TAP names rather than numbers.
1907 @item @b{Multiple chips}
1908 @* If your board has multiple chips, you should be
1909 able to @b{source} two configuration files, in the proper order, and
1910 have the taps created in the proper order.
1913 @comment at command level
1914 @comment DOCUMENT old command
1915 @section jtag_device - REMOVED
1917 @b{jtag_device} <@var{IR length}> <@var{IR capture}> <@var{IR mask}> <@var{IDCODE instruction}>
1921 @* @b{Removed: 28/nov/2008} This command has been removed and replaced
1922 by the ``jtag newtap'' command. The documentation remains here so that
1923 one can easily convert the old syntax to the new syntax. About the old
1924 syntax: The old syntax is positional, i.e.: The 3rd parameter is the
1925 ``irmask''. The new syntax requires named prefixes, and supports
1926 additional options, for example ``-expected-id 0x3f0f0f0f''. Please refer to the
1927 @b{jtag newtap} command for details.
1929 OLD: jtag_device 8 0x01 0xe3 0xfe
1930 NEW: jtag newtap CHIPNAME TAPNAME -irlen 8 -ircapture 0x01 -irmask 0xe3
1933 @section Enable/Disable Taps
1934 @b{Note:} These commands are intended to be used as a machine/script
1935 interface. Humans might find the ``scan_chain'' command more helpful
1936 when querying the state of the JTAG taps.
1938 @b{By default, all taps are enabled}
1941 @item @b{jtag tapenable} @var{DOTTED.NAME}
1942 @item @b{jtag tapdisable} @var{DOTTED.NAME}
1943 @item @b{jtag tapisenabled} @var{DOTTED.NAME}
1948 @cindex route controller
1950 These commands are used when your target has a JTAG route controller
1951 that effectively adds or removes a tap from the JTAG chain in a
1954 The ``standard way'' to remove a tap would be to place the tap in
1955 bypass mode. But with the advent of modern chips, this is not always a
1956 good solution. Some taps operate slowly, others operate fast, and
1957 there are other JTAG clock synchronisation problems one must face. To
1958 solve that problem, the JTAG route controller was introduced. Rather
1959 than ``bypass'' the tap, the tap is completely removed from the
1960 circuit and skipped.
1963 From OpenOCD's point of view, a JTAG tap is in one of 3 states:
1966 @item @b{Enabled - Not In ByPass} and has a variable bit length
1967 @item @b{Enabled - In ByPass} and has a length of exactly 1 bit.
1968 @item @b{Disabled} and has a length of ZERO and is removed from the circuit.
1971 The IEEE JTAG definition has no concept of a ``disabled'' tap.
1972 @b{Historical note:} this feature was added 28/nov/2008
1974 @b{jtag tapisenabled DOTTED.NAME}
1976 This command returns 1 if the named tap is currently enabled, 0 if not.
1977 This command exists so that scripts that manipulate a JRC (like the
1978 OMAP3530 has) can determine if OpenOCD thinks a tap is presently
1979 enabled or disabled.
1982 @node Target Configuration
1983 @chapter Target Configuration
1986 This chapter discusses how to create a GDB debug target. Before
1987 creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
1989 @section targets [NAME]
1990 @b{Note:} This command name is PLURAL - not singular.
1992 With NO parameter, this plural @b{targets} command lists all known
1993 targets in a human friendly form.
1995 With a parameter, this plural @b{targets} command sets the current
1996 target to the given name. (i.e.: If there are multiple debug targets)
2001 CmdName Type Endian ChainPos State
2002 -- ---------- ---------- ---------- -------- ----------
2003 0: target0 arm7tdmi little 0 halted
2006 @section target COMMANDS
2007 @b{Note:} This command name is SINGULAR - not plural. It is used to
2008 manipulate specific targets, to create targets and other things.
2010 Once a target is created, a TARGETNAME (object) command is created;
2011 see below for details.
2013 The TARGET command accepts these sub-commands:
2015 @item @b{create} .. parameters ..
2016 @* creates a new target, see below for details.
2018 @* Lists all supported target types (perhaps some are not yet in this document).
2020 @* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
2022 foreach t [target names] {
2023 puts [format "Target: %s\n" $t]
2027 @* Returns the current target. OpenOCD always has, or refers to the ``current target'' in some way.
2028 By default, commands like: ``mww'' (used to write memory) operate on the current target.
2029 @item @b{number} @b{NUMBER}
2030 @* Internally OpenOCD maintains a list of targets - in numerical index
2031 (0..N-1) this command returns the name of the target at index N.
2034 set thename [target number $x]
2035 puts [format "Target %d is: %s\n" $x $thename]
2038 @* Returns the number of targets known to OpenOCD (see number above)
2041 set c [target count]
2042 for { set x 0 } { $x < $c } { incr x } {
2043 # Assuming you have created this function
2044 print_target_details $x
2050 @section TARGETNAME (object) commands
2051 @b{Use:} Once a target is created, an ``object name'' that represents the
2052 target is created. By convention, the target name is identical to the
2053 tap name. In a multiple target system, one can preceed many common
2054 commands with a specific target name and effect only that target.
2056 str912.cpu mww 0x1234 0x42
2057 omap3530.cpu mww 0x5555 123
2060 @b{Model:} The Tcl/Tk language has the concept of object commands. A
2061 good example is a on screen button, once a button is created a button
2062 has a name (a path in Tk terms) and that name is useable as a 1st
2063 class command. For example in Tk, one can create a button and later
2064 configure it like this:
2068 button .foobar -background red -command @{ foo @}
2070 .foobar configure -foreground blue
2072 set x [.foobar cget -background]
2074 puts [format "The button is %s" $x]
2077 In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
2078 button. Commands available as a ``target object'' are:
2080 @comment START targetobj commands.
2082 @item @b{configure} - configure the target; see Target Config/Cget Options below
2083 @item @b{cget} - query the target configuration; see Target Config/Cget Options below
2084 @item @b{curstate} - current target state (running, halt, etc.
2086 @* Intended for a human to see/read the currently configure target events.
2087 @item @b{Various Memory Commands} See the ``mww'' command elsewhere.
2088 @comment start memory
2098 @item @b{Memory To Array, Array To Memory}
2099 @* These are aimed at a machine interface to memory
2101 @item @b{mem2array ARRAYNAME WIDTH ADDRESS COUNT}
2102 @item @b{array2mem ARRAYNAME WIDTH ADDRESS COUNT}
2104 @* @b{ARRAYNAME} is the name of an array variable
2105 @* @b{WIDTH} is 8/16/32 - indicating the memory access size
2106 @* @b{ADDRESS} is the target memory address
2107 @* @b{COUNT} is the number of elements to process
2109 @item @b{Used during ``reset''}
2110 @* These commands are used internally by the OpenOCD scripts to deal
2111 with odd reset situations and are not documented here.
2113 @item @b{arp_examine}
2117 @item @b{arp_waitstate}
2119 @item @b{invoke-event} @b{EVENT-NAME}
2120 @* Invokes the specific event manually for the target
2123 @section Target Events
2125 @anchor{Target Events}
2126 At various times, certain things can happen, or you want them to happen.
2130 @item What should happen when GDB connects? Should your target reset?
2131 @item When GDB tries to flash the target, do you need to enable the flash via a special command?
2132 @item During reset, do you need to write to certain memory location to reconfigure the SDRAM?
2135 All of the above items are handled by target events.
2137 To specify an event action, either during target creation, or later
2138 via ``$_TARGETNAME configure'' see this example.
2140 Syntactially, the option is: ``-event NAME BODY'' where NAME is a
2141 target event name, and BODY is a Tcl procedure or string of commands
2144 The programmers model is the ``-command'' option used in Tcl/Tk
2145 buttons and events. Below are two identical examples, the first
2146 creates and invokes small procedure. The second inlines the procedure.
2149 proc my_attach_proc @{ @} @{
2153 mychip.cpu configure -event gdb-attach my_attach_proc
2154 mychip.cpu configure -event gdb-attach @{
2160 @section Current Events
2161 The following events are available:
2163 @item @b{debug-halted}
2164 @* The target has halted for debug reasons (i.e.: breakpoint)
2165 @item @b{debug-resumed}
2166 @* The target has resumed (i.e.: gdb said run)
2167 @item @b{early-halted}
2168 @* Occurs early in the halt process
2169 @item @b{examine-end}
2170 @* Currently not used (goal: when JTAG examine completes)
2171 @item @b{examine-start}
2172 @* Currently not used (goal: when JTAG examine starts)
2173 @item @b{gdb-attach}
2174 @* When GDB connects
2175 @item @b{gdb-detach}
2176 @* When GDB disconnects
2178 @* When the taret has halted and GDB is not doing anything (see early halt)
2179 @item @b{gdb-flash-erase-start}
2180 @* Before the GDB flash process tries to erase the flash
2181 @item @b{gdb-flash-erase-end}
2182 @* After the GDB flash process has finished erasing the flash
2183 @item @b{gdb-flash-write-start}
2184 @* Before GDB writes to the flash
2185 @item @b{gdb-flash-write-end}
2186 @* After GDB writes to the flash
2188 @* Before the taret steps, gdb is trying to start/resume the target
2190 @* The target has halted
2191 @item @b{old-gdb_program_config}
2192 @* DO NOT USE THIS: Used internally
2193 @item @b{old-pre_resume}
2194 @* DO NOT USE THIS: Used internally
2195 @item @b{reset-assert-pre}
2196 @* Before reset is asserted on the tap.
2197 @item @b{reset-assert-post}
2198 @* Reset is now asserted on the tap.
2199 @item @b{reset-deassert-pre}
2200 @* Reset is about to be released on the tap
2201 @item @b{reset-deassert-post}
2202 @* Reset has been released on the tap
2204 @* Currently not used.
2205 @item @b{reset-halt-post}
2206 @* Currently not usd
2207 @item @b{reset-halt-pre}
2208 @* Currently not used
2209 @item @b{reset-init}
2210 @* Used by @b{reset init} command for board-specific initialization.
2211 This is where you would configure PLLs and clocking, set up DRAM so
2212 you can download programs that don't fit in on-chip SRAM, set up pin
2213 multiplexing, and so on.
2214 @item @b{reset-start}
2215 @* Currently not used
2216 @item @b{reset-wait-pos}
2217 @* Currently not used
2218 @item @b{reset-wait-pre}
2219 @* Currently not used
2220 @item @b{resume-start}
2221 @* Before any target is resumed
2222 @item @b{resume-end}
2223 @* After all targets have resumed
2227 @* Target has resumed
2228 @item @b{tap-enable}
2229 @* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
2231 jtag configure DOTTED.NAME -event tap-enable @{
2236 @item @b{tap-disable}
2237 @*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
2239 jtag configure DOTTED.NAME -event tap-disable @{
2240 puts "Disabling CPU"
2246 @section Target Create
2247 @anchor{Target Create}
2249 @cindex target creation
2252 @b{target} @b{create} <@var{NAME}> <@var{TYPE}> <@var{PARAMS ...}>
2254 @*This command creates a GDB debug target that refers to a specific JTAG tap.
2255 @comment START params
2258 @* Is the name of the debug target. By convention it should be the tap
2259 DOTTED.NAME. This name is also used to create the target object
2260 command, and in other places the target needs to be identified.
2262 @* Specifies the target type, i.e.: ARM7TDMI, or Cortex-M3. Currently supported targets are:
2263 @comment START types
2280 @*PARAMs are various target configuration parameters. The following ones are mandatory:
2281 @comment START mandatory
2283 @item @b{-endian big|little}
2284 @item @b{-chain-position DOTTED.NAME}
2285 @comment end MANDATORY
2290 @section Target Config/Cget Options
2291 These options can be specified when the target is created, or later
2292 via the configure option or to query the target via cget.
2294 You should specify a working area if you can; typically it uses some
2295 on-chip SRAM. Such a working area can speed up many things, including bulk
2296 writes to target memory; flash operations like checking to see if memory needs
2297 to be erased; GDB memory checksumming; and may help perform otherwise
2298 unavailable operations (like some coprocessor operations on ARM7/9 systems).
2300 @item @b{-type} - returns the target type
2301 @item @b{-event NAME BODY} see Target events
2302 @item @b{-work-area-virt [ADDRESS]} specify/set the work area base address
2303 which will be used when an MMU is active.
2304 @item @b{-work-area-phys [ADDRESS]} specify/set the work area base address
2305 which will be used when an MMU is inactive.
2306 @item @b{-work-area-size [ADDRESS]} specify/set the work area
2307 @item @b{-work-area-backup [0|1]} does the work area get backed up;
2308 by default, it doesn't. When possible, use a working_area that doesn't
2309 need to be backed up, since performing a backup slows down operations.
2310 @item @b{-endian [big|little]}
2311 @item @b{-variant [NAME]} some chips have variants OpenOCD needs to know about
2312 @item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
2316 for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
2317 set name [target number $x]
2318 set y [$name cget -endian]
2319 set z [$name cget -type]
2320 puts [format "Chip %d is %s, Endian: %s, type: %s" $x $y $z]
2324 @section Target Variants
2327 @* Use variant @option{lm3s} when debugging older Stellaris LM3S targets.
2328 This will cause OpenOCD to use a software reset rather than asserting
2329 SRST, to avoid a issue with clearing the debug registers.
2330 This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
2331 be detected and the normal reset behaviour used.
2333 @*Supported variants are
2334 @option{ixp42x}, @option{ixp45x}, @option{ixp46x},
2335 @option{pxa250}, @option{pxa255}, @option{pxa26x}.
2337 @* Use variant @option{ejtag_srst} when debugging targets that do not
2338 provide a functional SRST line on the EJTAG connector. This causes
2339 OpenOCD to instead use an EJTAG software reset command to reset the
2340 processor. You still need to enable @option{srst} on the reset
2341 configuration command to enable OpenOCD hardware reset functionality.
2342 @comment END variants
2344 @section working_area - Command Removed
2345 @cindex working_area
2346 @*@b{Please use the ``$_TARGETNAME configure -work-area-... parameters instead}
2347 @* This documentation remains because there are existing scripts that
2348 still use this that need to be converted.
2350 working_area target# address size backup| [virtualaddress]
2352 @* The target# is a the 0 based target numerical index.
2354 @node Flash Commands
2355 @chapter Flash Commands
2357 OpenOCD has different commands for NOR and NAND flash;
2358 the ``flash'' command works with NOR flash, while
2359 the ``nand'' command works with NAND flash.
2360 This partially reflects different hardware technologies:
2361 NOR flash usually supports direct CPU instruction and data bus access,
2362 while data from a NAND flash must be copied to memory before it can be
2363 used. (SPI flash must also be copied to memory before use.)
2364 However, the documentation also uses ``flash'' as a generic term;
2365 for example, ``Put flash configuration in board-specific files''.
2368 As of 28-nov-2008 OpenOCD does not know how to program a SPI
2369 flash that a micro may boot from. Perhaps you, the reader, would like to
2370 contribute support for this.
2375 @item Configure via the command @command{flash bank}
2376 @* Do this in a board-specific configuration file,
2377 passing parameters as needed by the driver.
2378 @item Operate on the flash via @command{flash subcommand}
2379 @* Often commands to manipulate the flash are typed by a human, or run
2380 via a script in some automated way. Common tasks include writing a
2381 boot loader, operating system, or other data.
2383 @* Flashing via GDB requires the flash be configured via ``flash
2384 bank'', and the GDB flash features be enabled.
2385 @xref{GDB Configuration}.
2388 Many CPUs have the ablity to ``boot'' from the first flash bank.
2389 This means that misprograming that bank can ``brick'' a system,
2390 so that it can't boot.
2391 JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
2392 board by (re)installing working boot firmware.
2394 @section Flash Configuration Commands
2395 @cindex flash configuration
2397 @deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
2398 Configures a flash bank which provides persistent storage
2399 for addresses from @math{base} to @math{base + size - 1}.
2400 These banks will often be visible to GDB through the target's memory map.
2401 In some cases, configuring a flash bank will activate extra commands;
2402 see the driver-specific documentation.
2405 @item @var{driver} ... identifies the controller driver
2406 associated with the flash bank being declared.
2407 This is usually @code{cfi} for external flash, or else
2408 the name of a microcontroller with embedded flash memory.
2409 @xref{Flash Driver List}.
2410 @item @var{base} ... Base address of the flash chip.
2411 @item @var{size} ... Size of the chip, in bytes.
2412 For some drivers, this value is detected from the hardware.
2413 @item @var{chip_width} ... Width of the flash chip, in bytes;
2414 ignored for most microcontroller drivers.
2415 @item @var{bus_width} ... Width of the data bus used to access the
2416 chip, in bytes; ignored for most microcontroller drivers.
2417 @item @var{target} ... Names the target used to issue
2418 commands to the flash controller.
2419 @comment Actually, it's currently a controller-specific parameter...
2420 @item @var{driver_options} ... drivers may support, or require,
2421 additional parameters. See the driver-specific documentation
2422 for more information.
2425 This command is not available after OpenOCD initialization has completed.
2426 Use it in board specific configuration files, not interactively.
2430 @comment the REAL name for this command is "ocd_flash_banks"
2431 @comment less confusing would be: "flash list" (like "nand list")
2432 @deffn Command {flash banks}
2433 Prints a one-line summary of each device declared
2434 using @command{flash bank}, numbered from zero.
2435 Note that this is the @emph{plural} form;
2436 the @emph{singular} form is a very different command.
2439 @deffn Command {flash probe} num
2440 Identify the flash, or validate the parameters of the configured flash. Operation
2441 depends on the flash type.
2442 The @var{num} parameter is a value shown by @command{flash banks}.
2443 Most flash commands will implicitly @emph{autoprobe} the bank;
2444 flash drivers can distinguish between probing and autoprobing,
2445 but most don't bother.
2448 @section Erasing, Reading, Writing to Flash
2449 @cindex flash erasing
2450 @cindex flash reading
2451 @cindex flash writing
2452 @cindex flash programming
2454 One feature distinguishing NOR flash from NAND or serial flash technologies
2455 is that for read access, it acts exactly like any other addressible memory.
2456 This means you can use normal memory read commands like @command{mdw} or
2457 @command{dump_image} with it, with no special @command{flash} subcommands.
2458 @xref{Memory access}.
2459 @xref{Image access}.
2461 Write access works differently. Flash memory normally needs to be erased
2462 before it's written. Erasing a sector turns all of its bits to ones, and
2463 writing can turn ones into zeroes. This is why there are special commands
2464 for interactive erasing and writing, and why GDB needs to know which parts
2465 of the address space hold NOR flash memory.
2468 Most of these erase and write commands leverage the fact that NOR flash
2469 chips consume target address space. They implicitly refer to the current
2470 JTAG target, and map from an address in that target's address space
2471 back to a flash bank.
2472 @comment In May 2009, those mappings may fail if any bank associated
2473 @comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
2474 A few commands use abstract addressing based on bank and sector numbers,
2475 and don't depend on searching the current target and its address space.
2476 Avoid confusing the two command models.
2479 Some flash chips implement software protection against accidental writes,
2480 since such buggy writes could in some cases ``brick'' a system.
2481 For such systems, erasing and writing may require sector protection to be
2483 Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
2484 and AT91SAM7 on-chip flash.
2485 @xref{flash protect}.
2487 @anchor{flash erase_sector}
2488 @deffn Command {flash erase_sector} num first last
2489 Erase sectors in bank @var{num}, starting at sector @var{first} up to and including
2490 @var{last}. Sector numbering starts at 0.
2491 The @var{num} parameter is a value shown by @command{flash banks}.
2494 @deffn Command {flash erase_address} address length
2495 Erase sectors starting at @var{address} for @var{length} bytes.
2496 The flash bank to use is inferred from the @var{address}, and
2497 the specified length must stay within that bank.
2498 As a special case, when @var{length} is zero and @var{address} is
2499 the start of the bank, the whole flash is erased.
2502 @deffn Command {flash fillw} address word length
2503 @deffnx Command {flash fillh} address halfword length
2504 @deffnx Command {flash fillb} address byte length
2505 Fills flash memory with the specified @var{word} (32 bits),
2506 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
2507 starting at @var{address} and continuing
2508 for @var{length} units (word/halfword/byte).
2509 No erasure is done before writing; when needed, that must be done
2510 before issuing this command.
2511 Writes are done in blocks of up to 1024 bytes, and each write is
2512 verified by reading back the data and comparing it to what was written.
2513 The flash bank to use is inferred from the @var{address} of
2514 each block, and the specified length must stay within that bank.
2516 @comment no current checks for errors if fill blocks touch multiple banks!
2518 @anchor{flash write_bank}
2519 @deffn Command {flash write_bank} num filename offset
2520 Write the binary @file{filename} to flash bank @var{num},
2521 starting at @var{offset} bytes from the beginning of the bank.
2522 The @var{num} parameter is a value shown by @command{flash banks}.
2525 @anchor{flash write_image}
2526 @deffn Command {flash write_image} [erase] filename [offset] [type]
2527 Write the image @file{filename} to the current target's flash bank(s).
2528 A relocation @var{offset} may be specified, in which case it is added
2529 to the base address for each section in the image.
2530 The file [@var{type}] can be specified
2531 explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
2532 @option{elf} (ELF file), @option{s19} (Motorola s19).
2533 @option{mem}, or @option{builder}.
2534 The relevant flash sectors will be erased prior to programming
2535 if the @option{erase} parameter is given.
2536 The flash bank to use is inferred from the @var{address} of
2540 @section Other Flash commands
2541 @cindex flash protection
2543 @deffn Command {flash erase_check} num
2544 Check erase state of sectors in flash bank @var{num},
2545 and display that status.
2546 The @var{num} parameter is a value shown by @command{flash banks}.
2547 This is the only operation that
2548 updates the erase state information displayed by @option{flash info}. That means you have
2549 to issue an @command{flash erase_check} command after erasing or programming the device
2550 to get updated information.
2551 (Code execution may have invalidated any state records kept by OpenOCD.)
2554 @deffn Command {flash info} num
2555 Print info about flash bank @var{num}
2556 The @var{num} parameter is a value shown by @command{flash banks}.
2557 The information includes per-sector protect status.
2560 @anchor{flash protect}
2561 @deffn Command {flash protect} num first last (on|off)
2562 Enable (@var{on}) or disable (@var{off}) protection of flash sectors
2563 @var{first} to @var{last} of flash bank @var{num}.
2564 The @var{num} parameter is a value shown by @command{flash banks}.
2567 @deffn Command {flash protect_check} num
2568 Check protection state of sectors in flash bank @var{num}.
2569 The @var{num} parameter is a value shown by @command{flash banks}.
2570 @comment @option{flash erase_sector} using the same syntax.
2573 @section Flash Drivers, Options, and Commands
2574 @anchor{Flash Driver List}
2575 As noted above, the @command{flash bank} command requires a driver name,
2576 and allows driver-specific options and behaviors.
2577 Some drivers also activate driver-specific commands.
2579 @subsection External Flash
2581 @deffn {Flash Driver} cfi
2582 @cindex Common Flash Interface
2584 The ``Common Flash Interface'' (CFI) is the main standard for
2585 external NOR flash chips, each of which connects to a
2586 specific external chip select on the CPU.
2587 Frequently the first such chip is used to boot the system.
2588 Your board's @code{reset-init} handler might need to
2589 configure additional chip selects using other commands (like: @command{mww} to
2590 configure a bus and its timings) , or
2591 perhaps configure a GPIO pin that controls the ``write protect'' pin
2593 The CFI driver can use a target-specific working area to significantly
2596 The CFI driver can accept the following optional parameters, in any order:
2599 @item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
2600 like AM29LV010 and similar types.
2601 @item @var{x16_as_x8} ...
2604 To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
2605 wide on a sixteen bit bus:
2608 flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
2609 flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
2613 @subsection Internal Flash (Microcontrollers)
2615 @deffn {Flash Driver} aduc702x
2616 The ADUC702x analog microcontrollers from ST Micro
2617 include internal flash and use ARM7TDMI cores.
2618 The aduc702x flash driver works with models ADUC7019 through ADUC7028.
2619 The setup command only requires the @var{target} argument
2620 since all devices in this family have the same memory layout.
2623 flash bank aduc702x 0 0 0 0 $_TARGETNAME
2627 @deffn {Flash Driver} at91sam7
2628 All members of the AT91SAM7 microcontroller family from Atmel
2629 include internal flash and use ARM7TDMI cores.
2630 The driver automatically recognizes a number of these chips using
2631 the chip identification register, and autoconfigures itself.
2634 flash bank at91sam7 0 0 0 0 $_TARGETNAME
2637 For chips which are not recognized by the controller driver, you must
2638 provide additional parameters in the following order:
2641 @item @var{chip_model} ... label used with @command{flash info}
2643 @item @var{sectors_per_bank}
2644 @item @var{pages_per_sector}
2645 @item @var{pages_size}
2646 @item @var{num_nvm_bits}
2647 @item @var{freq_khz} ... required if an external clock is provided,
2648 optional (but recommended) when the oscillator frequency is known
2651 It is recommended that you provide zeroes for all of those values
2652 except the clock frequency, so that everything except that frequency
2653 will be autoconfigured.
2654 Knowing the frequency helps ensure correct timings for flash access.
2656 The flash controller handles erases automatically on a page (128/256 byte)
2657 basis, so explicit erase commands are not necessary for flash programming.
2658 However, there is an ``EraseAll`` command that can erase an entire flash
2659 plane (of up to 256KB), and it will be used automatically when you issue
2660 @command{flash erase_sector} or @command{flash erase_address} commands.
2662 @deffn Command {at91sam7 gpnvm} bitnum (set|clear)
2663 Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
2664 bit for the processor. Each processor has a number of such bits,
2665 used for controlling features such as brownout detection (so they
2666 are not truly general purpose).
2668 This assumes that the first flash bank (number 0) is associated with
2669 the appropriate at91sam7 target.
2674 @deffn {Flash Driver} avr
2675 The AVR 8-bit microcontrollers from Atmel integrate flash memory.
2676 @emph{The current implementation is incomplete.}
2677 @comment - defines mass_erase ... pointless given flash_erase_address
2680 @deffn {Flash Driver} ecosflash
2681 @emph{No idea what this is...}
2682 The @var{ecosflash} driver defines one mandatory parameter,
2683 the name of a modules of target code which is downloaded
2687 @deffn {Flash Driver} lpc2000
2688 Most members of the LPC2000 microcontroller family from NXP
2689 include internal flash and use ARM7TDMI cores.
2690 The @var{lpc2000} driver defines two mandatory and one optional parameters,
2691 which must appear in the following order:
2694 @item @var{variant} ... required, may be
2695 @var{lpc2000_v1} (older LPC21xx and LPC22xx)
2696 or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
2697 @item @var{clock_kHz} ... the frequency, in kiloHertz,
2698 at which the core is running
2699 @item @var{calc_checksum} ... optional (but you probably want to provide this!),
2700 telling the driver to calculate a valid checksum for the exception vector table.
2703 LPC flashes don't require the chip and bus width to be specified.
2706 flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
2707 lpc2000_v2 14765 calc_checksum
2711 @deffn {Flash Driver} lpc288x
2712 The LPC2888 microcontroller from NXP needs slightly different flash
2713 support from its lpc2000 siblings.
2714 The @var{lpc288x} driver defines one mandatory parameter,
2715 the programming clock rate in Hz.
2716 LPC flashes don't require the chip and bus width to be specified.
2719 flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000
2723 @deffn {Flash Driver} ocl
2724 @emph{No idea what this is, other than using some arm7/arm9 core.}
2727 flash bank ocl 0 0 0 0 $_TARGETNAME
2731 @deffn {Flash Driver} pic32mx
2732 The PIC32MX microcontrollers are based on the MIPS 4K cores,
2733 and integrate flash memory.
2734 @emph{The current implementation is incomplete.}
2737 flash bank pix32mx 0 0 0 0 $_TARGETNAME
2740 @comment numerous *disabled* commands are defined:
2741 @comment - chip_erase ... pointless given flash_erase_address
2742 @comment - lock, unlock ... pointless given protect on/off (yes?)
2743 @comment - pgm_word ... shouldn't bank be deduced from address??
2744 Some pic32mx-specific commands are defined:
2745 @deffn Command {pic32mx pgm_word} address value bank
2746 Programs the specified 32-bit @var{value} at the given @var{address}
2747 in the specified chip @var{bank}.
2751 @deffn {Flash Driver} stellaris
2752 All members of the Stellaris LM3Sxxx microcontroller family from
2754 include internal flash and use ARM Cortex M3 cores.
2755 The driver automatically recognizes a number of these chips using
2756 the chip identification register, and autoconfigures itself.
2757 @footnote{Currently there is a @command{stellaris mass_erase} command.
2758 That seems pointless since the same effect can be had using the
2759 standard @command{flash erase_address} command.}
2762 flash bank stellaris 0 0 0 0 $_TARGETNAME
2766 @deffn {Flash Driver} stm32x
2767 All members of the STM32 microcontroller family from ST Microelectronics
2768 include internal flash and use ARM Cortex M3 cores.
2769 The driver automatically recognizes a number of these chips using
2770 the chip identification register, and autoconfigures itself.
2773 flash bank stm32x 0 0 0 0 $_TARGETNAME
2776 Some stm32x-specific commands
2777 @footnote{Currently there is a @command{stm32x mass_erase} command.
2778 That seems pointless since the same effect can be had using the
2779 standard @command{flash erase_address} command.}
2782 @deffn Command {stm32x lock} num
2783 Locks the entire stm32 device.
2784 The @var{num} parameter is a value shown by @command{flash banks}.
2787 @deffn Command {stm32x unlock} num
2788 Unlocks the entire stm32 device.
2789 The @var{num} parameter is a value shown by @command{flash banks}.
2792 @deffn Command {stm32x options_read} num
2793 Read and display the stm32 option bytes written by
2794 the @command{stm32x options_write} command.
2795 The @var{num} parameter is a value shown by @command{flash banks}.
2798 @deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
2799 Writes the stm32 option byte with the specified values.
2800 The @var{num} parameter is a value shown by @command{flash banks}.
2804 @deffn {Flash Driver} str7x
2805 All members of the STR7 microcontroller family from ST Microelectronics
2806 include internal flash and use ARM7TDMI cores.
2807 The @var{str7x} driver defines one mandatory parameter, @var{variant},
2808 which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
2811 flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
2815 @deffn {Flash Driver} str9x
2816 Most members of the STR9 microcontroller family from ST Microelectronics
2817 include internal flash and use ARM966E cores.
2818 The str9 needs the flash controller to be configured using
2819 the @command{str9x flash_config} command prior to Flash programming.
2822 flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
2823 str9x flash_config 0 4 2 0 0x80000
2826 @deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
2827 Configures the str9 flash controller.
2828 The @var{num} parameter is a value shown by @command{flash banks}.
2831 @item @var{bbsr} - Boot Bank Size register
2832 @item @var{nbbsr} - Non Boot Bank Size register
2833 @item @var{bbadr} - Boot Bank Start Address register
2834 @item @var{nbbadr} - Boot Bank Start Address register
2840 @deffn {Flash Driver} tms470
2841 Most members of the TMS470 microcontroller family from Texas Instruments
2842 include internal flash and use ARM7TDMI cores.
2843 This driver doesn't require the chip and bus width to be specified.
2845 Some tms470-specific commands are defined:
2847 @deffn Command {tms470 flash_keyset} key0 key1 key2 key3
2848 Saves programming keys in a register, to enable flash erase and write commands.
2851 @deffn Command {tms470 osc_mhz} clock_mhz
2852 Reports the clock speed, which is used to calculate timings.
2855 @deffn Command {tms470 plldis} (0|1)
2856 Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
2861 @subsection str9xpec driver
2864 Here is some background info to help
2865 you better understand how this driver works. OpenOCD has two flash drivers for
2869 Standard driver @option{str9x} programmed via the str9 core. Normally used for
2870 flash programming as it is faster than the @option{str9xpec} driver.
2872 Direct programming @option{str9xpec} using the flash controller. This is an
2873 ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
2874 core does not need to be running to program using this flash driver. Typical use
2875 for this driver is locking/unlocking the target and programming the option bytes.
2878 Before we run any commands using the @option{str9xpec} driver we must first disable
2879 the str9 core. This example assumes the @option{str9xpec} driver has been
2880 configured for flash bank 0.
2882 # assert srst, we do not want core running
2883 # while accessing str9xpec flash driver
2885 # turn off target polling
2888 str9xpec enable_turbo 0
2890 str9xpec options_read 0
2891 # re-enable str9 core
2892 str9xpec disable_turbo 0
2896 The above example will read the str9 option bytes.
2897 When performing a unlock remember that you will not be able to halt the str9 - it
2898 has been locked. Halting the core is not required for the @option{str9xpec} driver
2899 as mentioned above, just issue the commands above manually or from a telnet prompt.
2901 @subsubsection str9xpec driver options
2903 @b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
2904 @*Before using the flash commands the turbo mode must be enabled using str9xpec
2905 @option{enable_turbo} <@var{num>.}
2907 Only use this driver for locking/unlocking the device or configuring the option bytes.
2908 Use the standard str9 driver for programming.
2910 @subsubsection str9xpec specific commands
2911 @cindex str9xpec specific commands
2912 These are flash specific commands when using the str9xpec driver.
2915 @item @b{str9xpec enable_turbo} <@var{num}>
2916 @cindex str9xpec enable_turbo
2917 @*enable turbo mode, will simply remove the str9 from the chain and talk
2918 directly to the embedded flash controller.
2919 @item @b{str9xpec disable_turbo} <@var{num}>
2920 @cindex str9xpec disable_turbo
2921 @*restore the str9 into JTAG chain.
2922 @item @b{str9xpec lock} <@var{num}>
2923 @cindex str9xpec lock
2924 @*lock str9 device. The str9 will only respond to an unlock command that will
2926 @item @b{str9xpec unlock} <@var{num}>
2927 @cindex str9xpec unlock
2928 @*unlock str9 device.
2929 @item @b{str9xpec options_read} <@var{num}>
2930 @cindex str9xpec options_read
2931 @*read str9 option bytes.
2932 @item @b{str9xpec options_write} <@var{num}>
2933 @cindex str9xpec options_write
2934 @*write str9 option bytes.
2937 @subsubsection STR9 option byte configuration
2938 @cindex STR9 option byte configuration
2941 @item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
2942 @cindex str9xpec options_cmap
2943 @*configure str9 boot bank.
2944 @item @b{str9xpec options_lvdthd} <@var{num}> <@option{2.4v}|@option{2.7v}>
2945 @cindex str9xpec options_lvdthd
2946 @*configure str9 lvd threshold.
2947 @item @b{str9xpec options_lvdsel} <@var{num}> <@option{vdd}|@option{vdd_vddq}>
2948 @cindex str9xpec options_lvdsel
2949 @*configure str9 lvd source.
2950 @item @b{str9xpec options_lvdwarn} <@var{bank}> <@option{vdd}|@option{vdd_vddq}>
2951 @cindex str9xpec options_lvdwarn
2952 @*configure str9 lvd reset warning source.
2957 @subsection mFlash Configuration
2958 @cindex mFlash Configuration
2959 @b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
2961 @*Configures a mflash for <@var{soc}> host bank at
2962 <@var{base}>. Pin number format is dependent on host GPIO calling convention.
2963 Currently, mflash bank support s3c2440 and pxa270.
2965 (ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
2968 mflash bank s3c2440 0x10000000 1b 0
2971 (ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
2974 mflash bank pxa270 0x08000000 43 0
2977 @subsection mFlash commands
2978 @cindex mFlash commands
2981 @item @b{mflash probe}
2982 @cindex mflash probe
2984 @item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
2985 @cindex mflash write
2986 @*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
2987 <@var{offset}> bytes from the beginning of the bank.
2988 @item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
2990 @*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
2992 @item @b{mflash config pll} <@var{frequency}>
2993 @cindex mflash config pll
2994 @*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
2995 Issuing this command will erase mflash's whole internal nand and write new pll.
2996 After this command, mflash needs power-on-reset for normal operation.
2997 If pll was newly configured, storage and boot(optional) info also need to be update.
2998 @item @b{mflash config boot}
2999 @cindex mflash config boot
3000 @*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
3002 @item @b{mflash config storage}
3003 @cindex mflash config storage
3004 @*Configure storage information. For the normal storage operation, this information must be
3008 @node NAND Flash Commands
3009 @chapter NAND Flash Commands
3012 Compared to NOR or SPI flash, NAND devices are inexpensive
3013 and high density. Today's NAND chips, and multi-chip modules,
3014 commonly hold multiple GigaBytes of data.
3016 NAND chips consist of a number of ``erase blocks'' of a given
3017 size (such as 128 KBytes), each of which is divided into a
3018 number of pages (of perhaps 512 or 2048 bytes each). Each
3019 page of a NAND flash has an ``out of band'' (OOB) area to hold
3020 Error Correcting Code (ECC) and other metadata, usually 16 bytes
3021 of OOB for every 512 bytes of page data.
3023 One key characteristic of NAND flash is that its error rate
3024 is higher than that of NOR flash. In normal operation, that
3025 ECC is used to correct and detect errors. However, NAND
3026 blocks can also wear out and become unusable; those blocks
3027 are then marked "bad". NAND chips are even shipped from the
3028 manufacturer with a few bad blocks. The highest density chips
3029 use a technology (MLC) that wears out more quickly, so ECC
3030 support is increasingly important as a way to detect blocks
3031 that have begun to fail, and help to preserve data integrity
3032 with techniques such as wear leveling.
3034 Software is used to manage the ECC. Some controllers don't
3035 support ECC directly; in those cases, software ECC is used.
3036 Other controllers speed up the ECC calculations with hardware.
3037 Single-bit error correction hardware is routine. Controllers
3038 geared for newer MLC chips may correct 4 or more errors for
3039 every 512 bytes of data.
3041 You will need to make sure that any data you write using
3042 OpenOCD includes the apppropriate kind of ECC. For example,
3043 that may mean passing the @code{oob_softecc} flag when
3044 writing NAND data, or ensuring that the correct hardware
3047 The basic steps for using NAND devices include:
3049 @item Declare via the command @command{nand device}
3050 @* Do this in a board-specific configuration file,
3051 passing parameters as needed by the controller.
3052 @item Configure each device using @command{nand probe}.
3053 @* Do this only after the associated target is set up,
3054 such as in its reset-init script or in procures defined
3055 to access that device.
3056 @item Operate on the flash via @command{nand subcommand}
3057 @* Often commands to manipulate the flash are typed by a human, or run
3058 via a script in some automated way. Common task include writing a
3059 boot loader, operating system, or other data needed to initialize or
3063 @b{NOTE:} At the time this text was written, the largest NAND
3064 flash fully supported by OpenOCD is 2 GiBytes (16 GiBits).
3065 This is because the variables used to hold offsets and lengths
3066 are only 32 bits wide.
3067 (Larger chips may work in some cases, unless an offset or length
3068 is larger than 0xffffffff, the largest 32-bit unsigned integer.)
3069 Some larger devices will work, since they are actually multi-chip
3070 modules with two smaller chips and individual chipselect lines.
3072 @section NAND Configuration Commands
3073 @cindex NAND configuration
3075 NAND chips must be declared in configuration scripts,
3076 plus some additional configuration that's done after
3077 OpenOCD has initialized.
3079 @deffn {Config Command} {nand device} controller target [configparams...]
3080 Declares a NAND device, which can be read and written to
3081 after it has been configured through @command{nand probe}.
3082 In OpenOCD, devices are single chips; this is unlike some
3083 operating systems, which may manage multiple chips as if
3084 they were a single (larger) device.
3085 In some cases, configuring a device will activate extra
3086 commands; see the controller-specific documentation.
3088 @b{NOTE:} This command is not available after OpenOCD
3089 initialization has completed. Use it in board specific
3090 configuration files, not interactively.
3093 @item @var{controller} ... identifies the controller driver
3094 associated with the NAND device being declared.
3095 @xref{NAND Driver List}.
3096 @item @var{target} ... names the target used when issuing
3097 commands to the NAND controller.
3098 @comment Actually, it's currently a controller-specific parameter...
3099 @item @var{configparams} ... controllers may support, or require,
3100 additional parameters. See the controller-specific documentation
3101 for more information.
3105 @deffn Command {nand list}
3106 Prints a one-line summary of each device declared
3107 using @command{nand device}, numbered from zero.
3108 Note that un-probed devices show no details.
3111 @deffn Command {nand probe} num
3112 Probes the specified device to determine key characteristics
3113 like its page and block sizes, and how many blocks it has.
3114 The @var{num} parameter is the value shown by @command{nand list}.
3115 You must (successfully) probe a device before you can use
3116 it with most other NAND commands.
3119 @section Erasing, Reading, Writing to NAND Flash
3121 @deffn Command {nand dump} num filename offset length [oob_option]
3122 @cindex NAND reading
3123 Reads binary data from the NAND device and writes it to the file,
3124 starting at the specified offset.
3125 The @var{num} parameter is the value shown by @command{nand list}.
3127 Use a complete path name for @var{filename}, so you don't depend
3128 on the directory used to start the OpenOCD server.
3130 The @var{offset} and @var{length} must be exact multiples of the
3131 device's page size. They describe a data region; the OOB data
3132 associated with each such page may also be accessed.
3134 @b{NOTE:} At the time this text was written, no error correction
3135 was done on the data that's read, unless raw access was disabled
3136 and the underlying NAND controller driver had a @code{read_page}
3137 method which handled that error correction.
3139 By default, only page data is saved to the specified file.
3140 Use an @var{oob_option} parameter to save OOB data:
3142 @item no oob_* parameter
3143 @*Output file holds only page data; OOB is discarded.
3144 @item @code{oob_raw}
3145 @*Output file interleaves page data and OOB data;
3146 the file will be longer than "length" by the size of the
3147 spare areas associated with each data page.
3148 Note that this kind of "raw" access is different from
3149 what's implied by @command{nand raw_access}, which just
3150 controls whether a hardware-aware access method is used.
3151 @item @code{oob_only}
3152 @*Output file has only raw OOB data, and will
3153 be smaller than "length" since it will contain only the
3154 spare areas associated with each data page.
3158 @deffn Command {nand erase} num offset length
3159 @cindex NAND erasing
3160 @cindex NAND programming
3161 Erases blocks on the specified NAND device, starting at the
3162 specified @var{offset} and continuing for @var{length} bytes.
3163 Both of those values must be exact multiples of the device's
3164 block size, and the region they specify must fit entirely in the chip.
3165 The @var{num} parameter is the value shown by @command{nand list}.
3167 @b{NOTE:} This command will try to erase bad blocks, when told
3168 to do so, which will probably invalidate the manufacturer's bad
3170 For the remainder of the current server session, @command{nand info}
3171 will still report that the block ``is'' bad.
3174 @deffn Command {nand write} num filename offset [option...]
3175 @cindex NAND writing
3176 @cindex NAND programming
3177 Writes binary data from the file into the specified NAND device,
3178 starting at the specified offset. Those pages should already
3179 have been erased; you can't change zero bits to one bits.
3180 The @var{num} parameter is the value shown by @command{nand list}.
3182 Use a complete path name for @var{filename}, so you don't depend
3183 on the directory used to start the OpenOCD server.
3185 The @var{offset} must be an exact multiple of the device's page size.
3186 All data in the file will be written, assuming it doesn't run
3187 past the end of the device.
3188 Only full pages are written, and any extra space in the last
3189 page will be filled with 0xff bytes. (That includes OOB data,
3190 if that's being written.)
3192 @b{NOTE:} At the time this text was written, bad blocks are
3193 ignored. That is, this routine will not skip bad blocks,
3194 but will instead try to write them. This can cause problems.
3196 Provide at most one @var{option} parameter. With some
3197 NAND drivers, the meanings of these parameters may change
3198 if @command{nand raw_access} was used to disable hardware ECC.
3200 @item no oob_* parameter
3201 @*File has only page data, which is written.
3202 If raw acccess is in use, the OOB area will not be written.
3203 Otherwise, if the underlying NAND controller driver has
3204 a @code{write_page} routine, that routine may write the OOB
3205 with hardware-computed ECC data.
3206 @item @code{oob_only}
3207 @*File has only raw OOB data, which is written to the OOB area.
3208 Each page's data area stays untouched. @i{This can be a dangerous
3209 option}, since it can invalidate the ECC data.
3210 You may need to force raw access to use this mode.
3211 @item @code{oob_raw}
3212 @*File interleaves data and OOB data, both of which are written
3213 If raw access is enabled, the data is written first, then the
3215 Otherwise, if the underlying NAND controller driver has
3216 a @code{write_page} routine, that routine may modify the OOB
3217 before it's written, to include hardware-computed ECC data.
3218 @item @code{oob_softecc}
3219 @*File has only page data, which is written.
3220 The OOB area is filled with 0xff, except for a standard 1-bit
3221 software ECC code stored in conventional locations.
3222 You might need to force raw access to use this mode, to prevent
3223 the underlying driver from applying hardware ECC.
3224 @item @code{oob_softecc_kw}
3225 @*File has only page data, which is written.
3226 The OOB area is filled with 0xff, except for a 4-bit software ECC
3227 specific to the boot ROM in Marvell Kirkwood SoCs.
3228 You might need to force raw access to use this mode, to prevent
3229 the underlying driver from applying hardware ECC.
3233 @section Other NAND commands
3234 @cindex NAND other commands
3236 @deffn Command {nand check_bad_blocks} [offset length]
3237 Checks for manufacturer bad block markers on the specified NAND
3238 device. If no parameters are provided, checks the whole
3239 device; otherwise, starts at the specified @var{offset} and
3240 continues for @var{length} bytes.
3241 Both of those values must be exact multiples of the device's
3242 block size, and the region they specify must fit entirely in the chip.
3243 The @var{num} parameter is the value shown by @command{nand list}.
3245 @b{NOTE:} Before using this command you should force raw access
3246 with @command{nand raw_access enable} to ensure that the underlying
3247 driver will not try to apply hardware ECC.
3250 @deffn Command {nand info} num
3251 The @var{num} parameter is the value shown by @command{nand list}.
3252 This prints the one-line summary from "nand list", plus for
3253 devices which have been probed this also prints any known
3254 status for each block.
3257 @deffn Command {nand raw_access} num <enable|disable>
3258 Sets or clears an flag affecting how page I/O is done.
3259 The @var{num} parameter is the value shown by @command{nand list}.
3261 This flag is cleared (disabled) by default, but changing that
3262 value won't affect all NAND devices. The key factor is whether
3263 the underlying driver provides @code{read_page} or @code{write_page}
3264 methods. If it doesn't provide those methods, the setting of
3265 this flag is irrelevant; all access is effectively ``raw''.
3267 When those methods exist, they are normally used when reading
3268 data (@command{nand dump} or reading bad block markers) or
3269 writing it (@command{nand write}). However, enabling
3270 raw access (setting the flag) prevents use of those methods,
3271 bypassing hardware ECC logic.
3272 @i{This can be a dangerous option}, since writing blocks
3273 with the wrong ECC data can cause them to be marked as bad.
3276 @section NAND Drivers, Options, and Commands
3277 @anchor{NAND Driver List}
3278 As noted above, the @command{nand device} command allows
3279 driver-specific options and behaviors.
3280 Some controllers also activate controller-specific commands.
3282 @deffn {NAND Driver} davinci
3283 This driver handles the NAND controllers found on DaVinci family
3284 chips from Texas Instruments.
3285 It takes three extra parameters:
3286 address of the NAND chip;
3287 hardware ECC mode to use (hwecc1, hwecc4, hwecc4_infix);
3288 address of the AEMIF controller on this processor.
3290 nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
3292 All DaVinci processors support the single-bit ECC hardware,
3293 and newer ones also support the four-bit ECC hardware.
3294 The @code{write_page} and @code{read_page} methods are used
3295 to implement those ECC modes, unless they are disabled using
3296 the @command{nand raw_access} command.
3299 @deffn {NAND Driver} lpc3180
3300 These controllers require an extra @command{nand device}
3301 parameter: the clock rate used by the controller.
3302 @deffn Command {lpc3180 select} num [mlc|slc]
3303 Configures use of the MLC or SLC controller mode.
3304 MLC implies use of hardware ECC.
3305 The @var{num} parameter is the value shown by @command{nand list}.
3308 At this writing, this driver includes @code{write_page}
3309 and @code{read_page} methods. Using @command{nand raw_access}
3310 to disable those methods will prevent use of hardware ECC
3311 in the MLC controller mode, but won't change SLC behavior.
3313 @comment current lpc3180 code won't issue 5-byte address cycles
3315 @deffn {NAND Driver} orion
3316 These controllers require an extra @command{nand device}
3317 parameter: the address of the controller.
3319 nand device orion 0xd8000000
3321 These controllers don't define any specialized commands.
3322 At this writing, their drivers don't include @code{write_page}
3323 or @code{read_page} methods, so @command{nand raw_access} won't
3324 change any behavior.
3327 @deffn {NAND Driver} s3c2410
3328 @deffnx {NAND Driver} s3c2412
3329 @deffnx {NAND Driver} s3c2440
3330 @deffnx {NAND Driver} s3c2443
3331 These S3C24xx family controllers don't have any special
3332 @command{nand device} options, and don't define any
3333 specialized commands.
3334 At this writing, their drivers don't include @code{write_page}
3335 or @code{read_page} methods, so @command{nand raw_access} won't
3336 change any behavior.
3339 @node General Commands
3340 @chapter General Commands
3343 The commands documented in this chapter here are common commands that
3344 you, as a human, may want to type and see the output of. Configuration type
3345 commands are documented elsewhere.
3349 @item @b{Source Of Commands}
3350 @* OpenOCD commands can occur in a configuration script (discussed
3351 elsewhere) or typed manually by a human or supplied programatically,
3352 or via one of several TCP/IP Ports.
3354 @item @b{From the human}
3355 @* A human should interact with the telnet interface (default port: 4444)
3356 or via GDB (default port 3333).
3358 To issue commands from within a GDB session, use the @option{monitor}
3359 command, e.g. use @option{monitor poll} to issue the @option{poll}
3360 command. All output is relayed through the GDB session.
3362 @item @b{Machine Interface}
3363 The Tcl interface's intent is to be a machine interface. The default Tcl
3368 @section Daemon Commands
3370 @subsection sleep [@var{msec}]
3372 @*Wait for n milliseconds before resuming. Useful in connection with script files
3373 (@var{script} command and @var{target_script} configuration).
3375 @subsection shutdown
3377 @*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
3379 @subsection debug_level [@var{n}]
3381 @anchor{debug_level}
3382 @*Display or adjust debug level to n<0-3>
3384 @subsection fast [@var{enable|disable}]
3386 @*Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory
3387 downloads and fast memory access will work if the JTAG interface isn't too fast and
3388 the core doesn't run at a too low frequency. Note that this option only changes the default
3389 and that the indvidual options, like DCC memory downloads, can be enabled and disabled
3392 The target specific "dangerous" optimisation tweaking options may come and go
3393 as more robust and user friendly ways are found to ensure maximum throughput
3394 and robustness with a minimum of configuration.
3396 Typically the "fast enable" is specified first on the command line:
3399 openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
3402 @subsection echo <@var{message}>
3404 @*Output message to stdio. e.g. echo "Programming - please wait"
3406 @subsection log_output <@var{file}>
3408 @*Redirect logging to <file> (default: stderr)
3410 @subsection script <@var{file}>
3412 @*Execute commands from <file>
3413 See also: ``source [find FILENAME]''
3415 @section Target state handling
3416 @subsection power <@var{on}|@var{off}>
3418 @*Turn power switch to target on/off.
3419 No arguments: print status.
3420 Not all interfaces support this.
3422 @subsection reg [@option{#}|@option{name}] [value]
3424 @*Access a single register by its number[@option{#}] or by its [@option{name}].
3425 No arguments: list all available registers for the current target.
3426 Number or name argument: display a register.
3427 Number or name and value arguments: set register value.
3429 @subsection poll [@option{on}|@option{off}]
3431 @*Poll the target for its current state. If the target is in debug mode, architecture
3432 specific information about the current state is printed. An optional parameter
3433 allows continuous polling to be enabled and disabled.
3435 @subsection halt [@option{ms}]
3437 @*Send a halt request to the target and wait for it to halt for up to [@option{ms}] milliseconds.
3438 Default [@option{ms}] is 5 seconds if no arg given.
3439 Optional arg @option{ms} is a timeout in milliseconds. Using 0 as the [@option{ms}]
3440 will stop OpenOCD from waiting.
3442 @subsection wait_halt [@option{ms}]
3444 @*Wait for the target to enter debug mode. Optional [@option{ms}] is
3445 a timeout in milliseconds. Default [@option{ms}] is 5 seconds if no
3448 @subsection resume [@var{address}]
3450 @*Resume the target at its current code position, or at an optional address.
3451 OpenOCD will wait 5 seconds for the target to resume.
3453 @subsection step [@var{address}]
3455 @*Single-step the target at its current code position, or at an optional address.
3457 @anchor{Reset Command}
3458 @subsection reset [@option{run}|@option{halt}|@option{init}]
3460 @*Perform a hard-reset. The optional parameter specifies what should
3461 happen after the reset.
3462 If there is no parameter, a @command{reset run} is executed.
3463 The other options will not work on all systems.
3464 @xref{Reset Configuration}.
3468 @*Let the target run.
3471 @*Immediately halt the target (works only with certain configurations).
3474 @*Immediately halt the target, and execute the reset script (works only with certain
3478 @subsection soft_reset_halt
3480 @*Requesting target halt and executing a soft reset. This is often used
3481 when a target cannot be reset and halted. The target, after reset is
3482 released begins to execute code. OpenOCD attempts to stop the CPU and
3483 then sets the program counter back to the reset vector. Unfortunately
3484 the code that was executed may have left the hardware in an unknown
3488 @section Memory access commands
3489 @anchor{Memory access}
3491 display available RAM memory.
3492 @subsection Memory peek/poke type commands
3493 These commands allow accesses of a specific size to the memory
3494 system. Often these are used to configure the current target in some
3495 special way. For example - one may need to write certian values to the
3496 SDRAM controller to enable SDRAM.
3499 @item To change the current target see the ``targets'' (plural) command
3500 @item In system level scripts these commands are deprecated, please use the TARGET object versions.
3504 @item @b{mdw} <@var{addr}> [@var{count}]
3506 @*display memory words (32bit)
3507 @item @b{mdh} <@var{addr}> [@var{count}]
3509 @*display memory half-words (16bit)
3510 @item @b{mdb} <@var{addr}> [@var{count}]
3512 @*display memory bytes (8bit)
3513 @item @b{mww} <@var{addr}> <@var{value}>
3515 @*write memory word (32bit)
3516 @item @b{mwh} <@var{addr}> <@var{value}>
3518 @*write memory half-word (16bit)
3519 @item @b{mwb} <@var{addr}> <@var{value}>
3521 @*write memory byte (8bit)
3524 @section Image loading commands
3525 @anchor{Image access}
3526 @subsection load_image
3527 @b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
3530 @*Load image <@var{file}> to target memory at <@var{address}>
3531 @subsection fast_load_image
3532 @b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
3533 @cindex fast_load_image
3534 @anchor{fast_load_image}
3535 @*Normally you should be using @b{load_image} or GDB load. However, for
3536 testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
3537 host), storing the image in memory and uploading the image to the target
3538 can be a way to upload e.g. multiple debug sessions when the binary does not change.
3539 Arguments are the same as @b{load_image}, but the image is stored in OpenOCD host
3540 memory, i.e. does not affect target. This approach is also useful when profiling
3541 target programming performance as I/O and target programming can easily be profiled
3543 @subsection fast_load
3547 @*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
3548 @subsection dump_image
3549 @b{dump_image} <@var{file}> <@var{address}> <@var{size}>
3552 @*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
3553 (binary) <@var{file}>.
3554 @subsection verify_image
3555 @b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
3556 @cindex verify_image
3557 @*Verify <@var{file}> against target memory starting at <@var{address}>.
3558 This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare.
3561 @section Breakpoint commands
3562 @cindex Breakpoint commands
3564 @item @b{bp} <@var{addr}> <@var{len}> [@var{hw}]
3566 @*set breakpoint <address> <length> [hw]
3567 @item @b{rbp} <@var{addr}>
3569 @*remove breakpoint <adress>
3570 @item @b{wp} <@var{addr}> <@var{len}> <@var{r}|@var{w}|@var{a}> [@var{value}] [@var{mask}]
3572 @*set watchpoint <address> <length> <r/w/a> [value] [mask]
3573 @item @b{rwp} <@var{addr}>
3575 @*remove watchpoint <adress>
3578 @section Misc Commands
3579 @cindex Other Target Commands
3581 @item @b{profile} <@var{seconds}> <@var{gmon.out}>
3583 Profiling samples the CPU's program counter as quickly as possible, which is useful for non-intrusive stochastic profiling.
3587 @section Architecture and Core Specific Commands
3588 @cindex Architecture Specific Commands
3589 @cindex Core Specific Commands
3591 Most CPUs have specialized JTAG operations to support debugging.
3592 OpenOCD packages most such operations in its standard command framework.
3593 Some of those operations don't fit well in that framework, so they are
3594 exposed here using architecture or implementation specific commands.
3596 @anchor{ARM Tracing}
3597 @subsection ARM Tracing
3601 CPUs based on ARM cores may include standard tracing interfaces,
3602 based on an ``Embedded Trace Module'' (ETM) which sends voluminous
3603 address and data bus trace records to a ``Trace Port''.
3607 Development-oriented boards will sometimes provide a high speed
3608 trace connector for collecting that data, when the particular CPU
3609 supports such an interface.
3610 (The standard connector is a 38-pin Mictor, with both JTAG
3611 and trace port support.)
3612 Those trace connectors are supported by higher end JTAG adapters
3613 and some logic analyzer modules; frequently those modules can
3614 buffer several megabytes of trace data.
3615 Configuring an ETM coupled to such an external trace port belongs
3616 in the board-specific configuration file.
3618 If the CPU doesn't provide an external interface, it probably
3619 has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
3620 dedicated SRAM. 4KBytes is one common ETB size.
3621 Configuring an ETM coupled only to an ETB belongs in the CPU-specific
3622 (target) configuration file, since it works the same on all boards.
3625 ETM support in OpenOCD doesn't seem to be widely used yet.
3628 ETM support may be buggy, and at least some @command{etm config}
3629 parameters should be detected by asking the ETM for them.
3630 It seems like a GDB hookup should be possible,
3631 as well as triggering trace on specific events
3632 (perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
3633 There should be GUI tools to manipulate saved trace data and help
3634 analyse it in conjunction with the source code.
3635 It's unclear how much of a common interface is shared
3636 with the current XScale trace support, or should be
3637 shared with eventual Nexus-style trace module support.
3640 @subsubsection ETM Configuration
3641 ETM setup is coupled with the trace port driver configuration.
3643 @deffn {Config Command} {etm config} target width mode clocking driver
3644 Declares the ETM associated with @var{target}, and associates it
3645 with a given trace port @var{driver}. @xref{Trace Port Drivers}.
3647 Several of the parameters must reflect the trace port configuration.
3648 The @var{width} must be either 4, 8, or 16.
3649 The @var{mode} must be @option{normal}, @option{multiplexted},
3650 or @option{demultiplexted}.
3651 The @var{clocking} must be @option{half} or @option{full}.
3654 You can see the ETM registers using the @command{reg} command, although
3655 not all of those possible registers are present in every ETM.
3659 @deffn Command {etm info}
3660 Displays information about the current target's ETM.
3663 @deffn Command {etm status}
3664 Displays status of the current target's ETM:
3665 is the ETM idle, or is it collecting data?
3666 Did trace data overflow?
3670 @deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
3671 Displays what data that ETM will collect.
3672 If arguments are provided, first configures that data.
3673 When the configuration changes, tracing is stopped
3674 and any buffered trace data is invalidated.
3677 @item @var{type} ... one of
3678 @option{none} (save nothing),
3679 @option{data} (save data),
3680 @option{address} (save addresses),
3681 @option{all} (save data and addresses)
3682 @item @var{context_id_bits} ... 0, 8, 16, or 32
3683 @item @var{cycle_accurate} ... @option{enable} or @option{disable}
3684 @item @var{branch_output} ... @option{enable} or @option{disable}
3688 @deffn Command {etm trigger_percent} percent
3689 @emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
3692 @subsubsection ETM Trace Operation
3694 After setting up the ETM, you can use it to collect data.
3695 That data can be exported to files for later analysis.
3696 It can also be parsed with OpenOCD, for basic sanity checking.
3698 @deffn Command {etm analyze}
3699 Reads trace data into memory, if it wasn't already present.
3700 Decodes and prints the data that was collected.
3703 @deffn Command {etm dump} filename
3704 Stores the captured trace data in @file{filename}.
3707 @deffn Command {etm image} filename [base_address] [type]
3708 Opens an image file.
3711 @deffn Command {etm load} filename
3712 Loads captured trace data from @file{filename}.
3715 @deffn Command {etm start}
3716 Starts trace data collection.
3719 @deffn Command {etm stop}
3720 Stops trace data collection.
3723 @anchor{Trace Port Drivers}
3724 @subsubsection Trace Port Drivers
3726 To use an ETM trace port it must be associated with a driver.
3728 @deffn {Trace Port Driver} etb
3729 Use the @option{etb} driver if you are configuring an ETM
3730 to use on-chip ETB memory.
3731 @deffn {Config Command} {etb config} target etb_tap
3732 Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
3733 You can see the ETB registers using the @command{reg} command.
3737 @deffn {Trace Port Driver} etm_dummy
3738 Use the @option{etm_dummy} driver if you are configuring an ETM that's
3739 not connected to anything (on-chip ETB or off-chip trace connector).
3740 @emph{This driver lets OpenOCD talk to the ETM, but it does not expose
3741 any trace data collection.}
3742 @deffn {Config Command} {etm_dummy config} target
3743 Associates the ETM for @var{target} with a dummy driver.
3747 @deffn {Trace Port Driver} oocd_trace
3748 This driver isn't available unless OpenOCD was explicitly configured
3749 with the @option{--enable-oocd_trace} option. You probably don't want
3750 to configure it unless you've built the appropriate prototype hardware;
3751 it's @emph{proof-of-concept} software.
3753 Use the @option{oocd_trace} driver if you are configuring an ETM that's
3754 connected to an off-chip trace connector.
3756 @deffn {Config Command} {oocd_trace config} target tty
3757 Associates the ETM for @var{target} with a trace driver which
3758 collects data through the serial port @var{tty}.
3761 @deffn Command {oocd_trace resync}
3762 Re-synchronizes with the capture clock.
3765 @deffn Command {oocd_trace status}
3766 Reports whether the capture clock is locked or not.
3771 @subsection ARMv4 and ARMv5 Architecture
3772 @cindex ARMv4 specific commands
3773 @cindex ARMv5 specific commands
3775 These commands are specific to ARM architecture v4 and v5,
3776 including all ARM7 or ARM9 systems and Intel XScale.
3777 They are available in addition to other core-specific
3778 commands that may be available.
3780 @deffn Command {armv4_5 core_state} [arm|thumb]
3781 Displays the core_state, optionally changing it to process
3782 either @option{arm} or @option{thumb} instructions.
3783 The target may later be resumed in the currently set core_state.
3784 (Processors may also support the Jazelle state, but
3785 that is not currently supported in OpenOCD.)
3788 @deffn Command {armv4_5 disassemble} address count [thumb]
3790 Disassembles @var{count} instructions starting at @var{address}.
3791 If @option{thumb} is specified, Thumb (16-bit) instructions are used;
3792 else ARM (32-bit) instructions are used.
3793 (Processors may also support the Jazelle state, but
3794 those instructions are not currently understood by OpenOCD.)
3797 @deffn Command {armv4_5 reg}
3798 Display a list of all banked core registers, fetching the current value from every
3799 core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
3803 @subsubsection ARM7 and ARM9 specific commands
3804 @cindex ARM7 specific commands
3805 @cindex ARM9 specific commands
3807 These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
3808 ARM9TDMI, ARM920T or ARM926EJ-S.
3809 They are available in addition to the ARMv4/5 commands,
3810 and any other core-specific commands that may be available.
3812 @deffn Command {arm7_9 dbgrq} (enable|disable)
3813 Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
3814 instead of breakpoints. This should be
3815 safe for all but ARM7TDMI--S cores (like Philips LPC).
3818 @deffn Command {arm7_9 dcc_downloads} (enable|disable)
3820 Control the use of the debug communications channel (DCC) to write larger (>128 byte)
3821 amounts of memory. DCC downloads offer a huge speed increase, but might be
3822 unsafe, especially with targets running at very low speeds. This command was introduced
3823 with OpenOCD rev. 60, and requires a few bytes of working area.
3826 @anchor{arm7_9 fast_memory_access}
3827 @deffn Command {arm7_9 fast_memory_access} (enable|disable)
3828 Enable or disable memory writes and reads that don't check completion of
3829 the operation. This provides a huge speed increase, especially with USB JTAG
3830 cables (FT2232), but might be unsafe if used with targets running at very low
3831 speeds, like the 32kHz startup clock of an AT91RM9200.
3834 @deffn {Debug Command} {arm7_9 write_core_reg} num mode word
3835 @emph{This is intended for use while debugging OpenOCD; you probably
3838 Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
3839 as used in the specified @var{mode}
3840 (where e.g. mode 16 is "user" and mode 19 is "supervisor";
3841 the M4..M0 bits of the PSR).
3842 Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
3843 Register 16 is the mode-specific SPSR,
3844 unless the specified mode is 0xffffffff (32-bit all-ones)
3845 in which case register 16 is the CPSR.
3846 The write goes directly to the CPU, bypassing the register cache.
3849 @deffn {Debug Command} {arm7_9 write_xpsr} word (0|1)
3850 @emph{This is intended for use while debugging OpenOCD; you probably
3853 If the second parameter is zero, writes @var{word} to the
3854 Current Program Status register (CPSR).
3855 Else writes @var{word} to the current mode's Saved PSR (SPSR).
3856 In both cases, this bypasses the register cache.
3859 @deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (0|1)
3860 @emph{This is intended for use while debugging OpenOCD; you probably
3863 Writes eight bits to the CPSR or SPSR,
3864 first rotating them by @math{2*rotate} bits,
3865 and bypassing the register cache.
3866 This has lower JTAG overhead than writing the entire CPSR or SPSR
3867 with @command{arm7_9 write_xpsr}.
3870 @subsubsection ARM720T specific commands
3871 @cindex ARM720T specific commands
3873 These commands are available to ARM720T based CPUs,
3874 which are implementations of the ARMv4T architecture
3875 based on the ARM7TDMI-S integer core.
3876 They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
3878 @deffn Command {arm720t cp15} regnum [value]
3879 Display cp15 register @var{regnum};
3880 else if a @var{value} is provided, that value is written to that register.
3883 @deffn Command {arm720t mdw_phys} addr [count]
3884 @deffnx Command {arm720t mdh_phys} addr [count]
3885 @deffnx Command {arm720t mdb_phys} addr [count]
3886 Display contents of physical address @var{addr}, as
3887 32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
3888 or 8-bit bytes (@command{mdb_phys}).
3889 If @var{count} is specified, displays that many units.
3892 @deffn Command {arm720t mww_phys} addr word
3893 @deffnx Command {arm720t mwh_phys} addr halfword
3894 @deffnx Command {arm720t mwb_phys} addr byte
3895 Writes the specified @var{word} (32 bits),
3896 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
3897 at the specified physical address @var{addr}.
3900 @deffn Command {arm720t virt2phys} va
3901 Translate a virtual address @var{va} to a physical address
3902 and display the result.
3905 @subsubsection ARM9TDMI specific commands
3906 @cindex ARM9TDMI specific commands
3908 Many ARM9-family CPUs are built around ARM9TDMI integer cores,
3909 or processors resembling ARM9TDMI, and can use these commands.
3910 Such cores include the ARM920T, ARM926EJ-S, and ARM966.
3912 @deffn Command {arm9tdmi vector_catch} (all|none|list)
3913 Catch arm9 interrupt vectors, can be @option{all}, @option{none},
3914 or a list with one or more of the following:
3915 @option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
3916 @option{irq} @option{fiq}.
3919 @subsubsection ARM920T specific commands
3920 @cindex ARM920T specific commands
3922 These commands are available to ARM920T based CPUs,
3923 which are implementations of the ARMv4T architecture
3924 built using the ARM9TDMI integer core.
3925 They are available in addition to the ARMv4/5, ARM7/ARM9,
3926 and ARM9TDMI commands.
3928 @deffn Command {arm920t cache_info}
3929 Print information about the caches found. This allows to see whether your target
3930 is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
3933 @deffn Command {arm920t cp15} regnum [value]
3934 Display cp15 register @var{regnum};
3935 else if a @var{value} is provided, that value is written to that register.
3938 @deffn Command {arm920t cp15i} opcode [value [address]]
3939 Interpreted access using cp15 @var{opcode}.
3940 If no @var{value} is provided, the result is displayed.
3941 Else if that value is written using the specified @var{address},
3942 or using zero if no other address is not provided.
3945 @deffn Command {arm920t mdw_phys} addr [count]
3946 @deffnx Command {arm920t mdh_phys} addr [count]
3947 @deffnx Command {arm920t mdb_phys} addr [count]
3948 Display contents of physical address @var{addr}, as
3949 32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
3950 or 8-bit bytes (@command{mdb_phys}).
3951 If @var{count} is specified, displays that many units.
3954 @deffn Command {arm920t mww_phys} addr word
3955 @deffnx Command {arm920t mwh_phys} addr halfword
3956 @deffnx Command {arm920t mwb_phys} addr byte
3957 Writes the specified @var{word} (32 bits),
3958 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
3959 at the specified physical address @var{addr}.
3962 @deffn Command {arm920t read_cache} filename
3963 Dump the content of ICache and DCache to a file named @file{filename}.
3966 @deffn Command {arm920t read_mmu} filename
3967 Dump the content of the ITLB and DTLB to a file named @file{filename}.
3970 @deffn Command {arm920t virt2phys} @var{va}
3971 Translate a virtual address @var{va} to a physical address
3972 and display the result.
3975 @subsubsection ARM926EJ-S specific commands
3976 @cindex ARM926EJ-S specific commands
3978 These commands are available to ARM926EJ-S based CPUs,
3979 which are implementations of the ARMv5TEJ architecture
3980 based on the ARM9EJ-S integer core.
3981 They are available in addition to the ARMv4/5, ARM7/ARM9,
3982 and ARM9TDMI commands.
3984 @deffn Command {arm926ejs cache_info}
3985 Print information about the caches found.
3988 @deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
3989 Accesses cp15 register @var{regnum} using
3990 @var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
3991 If a @var{value} is provided, that value is written to that register.
3992 Else that register is read and displayed.
3995 @deffn Command {arm926ejs mdw_phys} addr [count]
3996 @deffnx Command {arm926ejs mdh_phys} addr [count]
3997 @deffnx Command {arm926ejs mdb_phys} addr [count]
3998 Display contents of physical address @var{addr}, as
3999 32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
4000 or 8-bit bytes (@command{mdb_phys}).
4001 If @var{count} is specified, displays that many units.
4004 @deffn Command {arm926ejs mww_phys} addr word
4005 @deffnx Command {arm926ejs mwh_phys} addr halfword
4006 @deffnx Command {arm926ejs mwb_phys} addr byte
4007 Writes the specified @var{word} (32 bits),
4008 @var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
4009 at the specified physical address @var{addr}.
4012 @deffn Command {arm926ejs virt2phys} @var{va}
4013 Translate a virtual address @var{va} to a physical address
4014 and display the result.
4017 @subsubsection ARM966E specific commands
4018 @cindex ARM966E specific commands
4020 These commands are available to ARM966 based CPUs,
4021 which are implementations of the ARMv5TE architecture.
4022 They are available in addition to the ARMv4/5, ARM7/ARM9,
4023 and ARM9TDMI commands.
4025 @deffn Command {arm966e cp15} regnum [value]
4026 Display cp15 register @var{regnum};
4027 else if a @var{value} is provided, that value is written to that register.
4030 @subsubsection XScale specific commands
4031 @cindex XScale specific commands
4033 These commands are available to XScale based CPUs,
4034 which are implementations of the ARMv5TE architecture.
4036 @deffn Command {xscale analyze_trace}
4037 Displays the contents of the trace buffer.
4040 @deffn Command {xscale cache_clean_address} address
4041 Changes the address used when cleaning the data cache.
4044 @deffn Command {xscale cache_info}
4045 Displays information about the CPU caches.
4048 @deffn Command {xscale cp15} regnum [value]
4049 Display cp15 register @var{regnum};
4050 else if a @var{value} is provided, that value is written to that register.
4053 @deffn Command {xscale debug_handler} target address
4054 Changes the address used for the specified target's debug handler.
4057 @deffn Command {xscale dcache} (enable|disable)
4058 Enables or disable the CPU's data cache.
4061 @deffn Command {xscale dump_trace} filename
4062 Dumps the raw contents of the trace buffer to @file{filename}.
4065 @deffn Command {xscale icache} (enable|disable)
4066 Enables or disable the CPU's instruction cache.
4069 @deffn Command {xscale mmu} (enable|disable)
4070 Enables or disable the CPU's memory management unit.
4073 @deffn Command {xscale trace_buffer} (enable|disable) [fill [n] | wrap]
4074 Enables or disables the trace buffer,
4075 and controls how it is emptied.
4078 @deffn Command {xscale trace_image} filename [offset [type]]
4079 Opens a trace image from @file{filename}, optionally rebasing
4080 its segment addresses by @var{offset}.
4081 The image @var{type} may be one of
4082 @option{bin} (binary), @option{ihex} (Intel hex),
4083 @option{elf} (ELF file), @option{s19} (Motorola s19),
4084 @option{mem}, or @option{builder}.
4087 @deffn Command {xscale vector_catch} mask
4088 Provide a bitmask showing the vectors to catch.
4091 @subsection ARMv6 Architecture
4093 @subsubsection ARM11 specific commands
4094 @cindex ARM11 specific commands
4096 @deffn Command {arm11 mcr} p1 p2 p3 p4 p5
4097 Read coprocessor register
4100 @deffn Command {arm11 memwrite burst} [value]
4101 Displays the value of the memwrite burst-enable flag,
4102 which is enabled by default.
4103 If @var{value} is defined, first assigns that.
4106 @deffn Command {arm11 memwrite error_fatal} [value]
4107 Displays the value of the memwrite error_fatal flag,
4108 which is enabled by default.
4109 If @var{value} is defined, first assigns that.
4112 @deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
4113 Write coprocessor register
4116 @deffn Command {arm11 no_increment} [value]
4117 Displays the value of the flag controlling whether
4118 some read or write operations increment the pointer
4119 (the default behavior) or not (acting like a FIFO).
4120 If @var{value} is defined, first assigns that.
4123 @deffn Command {arm11 step_irq_enable} [value]
4124 Displays the value of the flag controlling whether
4125 IRQs are enabled during single stepping;
4126 they is disabled by default.
4127 If @var{value} is defined, first assigns that.
4130 @subsection ARMv7 Architecture
4132 @subsubsection Cortex-M3 specific commands
4133 @cindex Cortex-M3 specific commands
4135 @deffn Command {cortex_m3 maskisr} (on|off)
4136 Control masking (disabling) interrupts during target step/resume.
4139 @section Target DCC Requests
4140 @cindex Linux-ARM DCC support
4143 OpenOCD can handle certain target requests; currently debugmsgs
4144 @command{target_request debugmsgs}
4145 are only supported for arm7_9 and cortex_m3.
4147 See libdcc in the contrib dir for more details.
4148 Linux-ARM kernels have a ``Kernel low-level debugging
4149 via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
4150 depends on CONFIG_DEBUG_LL) which uses this mechanism to
4151 deliver messages before a serial console can be activated.
4153 @deffn Command {target_request debugmsgs} [enable|disable|charmsg]
4154 Displays current handling of target DCC message requests.
4155 These messages may be sent to the debugger while the target is running.
4156 The optional @option{enable} and @option{charmsg} parameters are
4157 equivalent; both enable the messages, @option{disable} disables them.
4161 @chapter JTAG Commands
4162 @cindex JTAG Commands
4163 Generally most people will not use the bulk of these commands. They
4164 are mostly used by the OpenOCD developers or those who need to
4165 directly manipulate the JTAG taps.
4167 In general these commands control JTAG taps at a very low level. For
4168 example if you need to control a JTAG Route Controller (i.e.: the
4169 OMAP3530 on the Beagle Board has one) you might use these commands in
4170 a script or an event procedure.
4174 @item @b{scan_chain}
4176 @*Print current scan chain configuration.
4177 @item @b{jtag_reset} <@var{trst}> <@var{srst}>
4179 @*Toggle reset lines.
4180 @item @b{endstate} <@var{tap_state}>
4182 @*Finish JTAG operations in <@var{tap_state}>.
4183 @item @b{runtest} <@var{num_cycles}>
4185 @*Move to Run-Test/Idle, and execute <@var{num_cycles}>
4186 @item @b{statemove} [@var{tap_state}]
4188 @*Move to current endstate or [@var{tap_state}]
4189 @item @b{irscan} <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
4191 @*Execute IR scan <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
4192 @item @b{drscan} <@var{device}> [@var{dev2}] [@var{var2}] ...
4194 @*Execute DR scan <@var{device}> [@var{dev2}] [@var{var2}] ...
4195 @item @b{verify_ircapture} <@option{enable}|@option{disable}>
4196 @cindex verify_ircapture
4197 @*Verify value captured during Capture-IR. Default is enabled.
4198 @item @b{var} <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
4200 @*Allocate, display or delete variable <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
4201 @item @b{field} <@var{var}> <@var{field}> [@var{value}|@var{flip}]
4203 Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
4208 Available tap_states are:
4248 If OpenOCD runs on an embedded host(as ZY1000 does), then TFTP can
4249 be used to access files on PCs (either the developer's PC or some other PC).
4251 The way this works on the ZY1000 is to prefix a filename by
4252 "/tftp/ip/" and append the TFTP path on the TFTP
4253 server (tftpd). For example,
4256 load_image /tftp/10.0.0.96/c:\temp\abc.elf
4259 will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
4260 if the file was hosted on the embedded host.
4262 In order to achieve decent performance, you must choose a TFTP server
4263 that supports a packet size bigger than the default packet size (512 bytes). There
4264 are numerous TFTP servers out there (free and commercial) and you will have to do
4265 a bit of googling to find something that fits your requirements.
4267 @node Sample Scripts
4268 @chapter Sample Scripts
4271 This page shows how to use the Target Library.
4273 The configuration script can be divided into the following sections:
4275 @item Daemon configuration
4277 @item JTAG scan chain
4278 @item Target configuration
4279 @item Flash configuration
4282 Detailed information about each section can be found at OpenOCD configuration.
4284 @section AT91R40008 example
4285 @cindex AT91R40008 example
4286 To start OpenOCD with a target script for the AT91R40008 CPU and reset
4287 the CPU upon startup of the OpenOCD daemon.
4289 openocd -f interface/parport.cfg -f target/at91r40008.cfg \
4290 -c "init" -c "reset"
4294 @node GDB and OpenOCD
4295 @chapter GDB and OpenOCD
4297 OpenOCD complies with the remote gdbserver protocol, and as such can be used
4298 to debug remote targets.
4300 @section Connecting to GDB
4301 @cindex Connecting to GDB
4302 @anchor{Connecting to GDB}
4303 Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
4304 instance GDB 6.3 has a known bug that produces bogus memory access
4305 errors, which has since been fixed: look up 1836 in
4306 @url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
4308 OpenOCD can communicate with GDB in two ways:
4312 A socket (TCP/IP) connection is typically started as follows:
4314 target remote localhost:3333
4316 This would cause GDB to connect to the gdbserver on the local pc using port 3333.
4318 A pipe connection is typically started as follows:
4320 target remote | openocd --pipe
4322 This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
4323 Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
4327 To list the available OpenOCD commands type @command{monitor help} on the
4330 OpenOCD supports the gdb @option{qSupported} packet, this enables information
4331 to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical information includes
4332 packet size and the device's memory map.
4334 Previous versions of OpenOCD required the following GDB options to increase
4335 the packet size and speed up GDB communication:
4337 set remote memory-write-packet-size 1024
4338 set remote memory-write-packet-size fixed
4339 set remote memory-read-packet-size 1024
4340 set remote memory-read-packet-size fixed
4342 This is now handled in the @option{qSupported} PacketSize and should not be required.
4344 @section Programming using GDB
4345 @cindex Programming using GDB
4347 By default the target memory map is sent to GDB. This can be disabled by
4348 the following OpenOCD configuration option:
4350 gdb_memory_map disable
4352 For this to function correctly a valid flash configuration must also be set
4353 in OpenOCD. For faster performance you should also configure a valid
4356 Informing GDB of the memory map of the target will enable GDB to protect any
4357 flash areas of the target and use hardware breakpoints by default. This means
4358 that the OpenOCD option @command{gdb_breakpoint_override} is not required when
4359 using a memory map. @xref{gdb_breakpoint_override}.
4361 To view the configured memory map in GDB, use the GDB command @option{info mem}
4362 All other unassigned addresses within GDB are treated as RAM.
4364 GDB 6.8 and higher set any memory area not in the memory map as inaccessible.
4365 This can be changed to the old behaviour by using the following GDB command
4367 set mem inaccessible-by-default off
4370 If @command{gdb_flash_program enable} is also used, GDB will be able to
4371 program any flash memory using the vFlash interface.
4373 GDB will look at the target memory map when a load command is given, if any
4374 areas to be programmed lie within the target flash area the vFlash packets
4377 If the target needs configuring before GDB programming, an event
4378 script can be executed:
4380 $_TARGETNAME configure -event EVENTNAME BODY
4383 To verify any flash programming the GDB command @option{compare-sections}
4386 @node Tcl Scripting API
4387 @chapter Tcl Scripting API
4388 @cindex Tcl Scripting API
4392 The commands are stateless. E.g. the telnet command line has a concept
4393 of currently active target, the Tcl API proc's take this sort of state
4394 information as an argument to each proc.
4396 There are three main types of return values: single value, name value
4397 pair list and lists.
4399 Name value pair. The proc 'foo' below returns a name/value pair
4405 > set foo(you) Oyvind
4406 > set foo(mouse) Micky
4407 > set foo(duck) Donald
4415 me Duane you Oyvind mouse Micky duck Donald
4417 Thus, to get the names of the associative array is easy:
4419 foreach { name value } [set foo] {
4420 puts "Name: $name, Value: $value"
4424 Lists returned must be relatively small. Otherwise a range
4425 should be passed in to the proc in question.
4427 @section Internal low-level Commands
4429 By low-level, the intent is a human would not directly use these commands.
4431 Low-level commands are (should be) prefixed with "ocd_", e.g.
4432 @command{ocd_flash_banks}
4433 is the low level API upon which @command{flash banks} is implemented.
4436 @item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
4438 Read memory and return as a Tcl array for script processing
4439 @item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
4441 Convert a Tcl array to memory locations and write the values
4442 @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
4444 Return information about the flash banks
4447 OpenOCD commands can consist of two words, e.g. "flash banks". The
4448 startup.tcl "unknown" proc will translate this into a Tcl proc
4449 called "flash_banks".
4451 @section OpenOCD specific Global Variables
4455 Real Tcl has ::tcl_platform(), and platform::identify, and many other
4456 variables. JimTCL, as implemented in OpenOCD creates $HostOS which
4457 holds one of the following values:
4460 @item @b{winxx} Built using Microsoft Visual Studio
4461 @item @b{linux} Linux is the underlying operating sytem
4462 @item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
4463 @item @b{cygwin} Running under Cygwin
4464 @item @b{mingw32} Running under MingW32
4465 @item @b{other} Unknown, none of the above.
4468 Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
4471 We should add support for a variable like Tcl variable
4472 @code{tcl_platform(platform)}, it should be called
4473 @code{jim_platform} (because it
4474 is jim, not real tcl).
4478 @chapter Deprecated/Removed Commands
4479 @cindex Deprecated/Removed Commands
4480 Certain OpenOCD commands have been deprecated/removed during the various revisions.
4483 @item @b{arm7_9 fast_writes}
4484 @cindex arm7_9 fast_writes
4485 @*Use @command{arm7_9 fast_memory_access} instead.
4486 @xref{arm7_9 fast_memory_access}.
4487 @item @b{arm7_9 force_hw_bkpts}
4488 @cindex arm7_9 force_hw_bkpts
4489 @*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
4490 for flash if the GDB memory map has been set up(default when flash is declared in
4491 target configuration). @xref{gdb_breakpoint_override}.
4492 @item @b{arm7_9 sw_bkpts}
4493 @cindex arm7_9 sw_bkpts
4494 @*On by default. @xref{gdb_breakpoint_override}.
4495 @item @b{daemon_startup}
4496 @cindex daemon_startup
4497 @*this config option has been removed, simply adding @option{init} and @option{reset halt} to
4498 the end of your config script will give the same behaviour as using @option{daemon_startup reset}
4499 and @option{target cortex_m3 little reset_halt 0}.
4500 @item @b{dump_binary}
4502 @*use @option{dump_image} command with same args. @xref{dump_image}.
4503 @item @b{flash erase}
4505 @*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
4506 @item @b{flash write}
4508 @*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
4509 @item @b{flash write_binary}
4510 @cindex flash write_binary
4511 @*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
4512 @item @b{flash auto_erase}
4513 @cindex flash auto_erase
4514 @*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
4516 @item @b{jtag_speed} value
4517 @*@xref{JTAG Speed}.
4518 Usually, a value of zero means maximum
4519 speed. The actual effect of this option depends on the JTAG interface used.
4521 @item wiggler: maximum speed / @var{number}
4522 @item ft2232: 6MHz / (@var{number}+1)
4523 @item amt jtagaccel: 8 / 2**@var{number}
4524 @item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
4525 @item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
4526 @comment end speed list.
4529 @item @b{load_binary}
4531 @*use @option{load_image} command with same args. @xref{load_image}.
4532 @item @b{run_and_halt_time}
4533 @cindex run_and_halt_time
4534 @*This command has been removed for simpler reset behaviour, it can be simulated with the
4541 @item @b{target} <@var{type}> <@var{endian}> <@var{jtag-position}>
4543 @*use the create subcommand of @option{target}.
4544 @item @b{target_script} <@var{target#}> <@var{eventname}> <@var{scriptname}>
4545 @cindex target_script
4546 @*use <@var{target_name}> configure -event <@var{eventname}> "script <@var{scriptname}>"
4547 @item @b{working_area}
4548 @cindex working_area
4549 @*use the @option{configure} subcommand of @option{target} to set the work-area-virt, work-area-phy, work-area-size, and work-area-backup properties of the target.
4556 @item @b{RTCK, also known as: Adaptive Clocking - What is it?}
4559 @cindex adaptive clocking
4562 In digital circuit design it is often refered to as ``clock
4563 synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
4564 operating at some speed, your target is operating at another. The two
4565 clocks are not synchronised, they are ``asynchronous''
4567 In order for the two to work together they must be synchronised. Otherwise
4568 the two systems will get out of sync with each other and nothing will
4569 work. There are 2 basic options:
4572 Use a special circuit.
4574 One clock must be some multiple slower than the other.
4577 @b{Does this really matter?} For some chips and some situations, this
4578 is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some
4579 Atmel SAM7 and SAM9 chips start operation from reset at 32kHz -
4580 program/enable the oscillators and eventually the main clock. It is in
4581 those critical times you must slow the JTAG clock to sometimes 1 to
4584 Imagine debugging a 500MHz ARM926 hand held battery powered device
4585 that ``deep sleeps'' at 32kHz between every keystroke. It can be
4588 @b{Solution #1 - A special circuit}
4590 In order to make use of this, your JTAG dongle must support the RTCK
4591 feature. Not all dongles support this - keep reading!
4593 The RTCK signal often found in some ARM chips is used to help with
4594 this problem. ARM has a good description of the problem described at
4595 this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
4596 28/nov/2008]. Link title: ``How does the JTAG synchronisation logic
4597 work? / how does adaptive clocking work?''.
4599 The nice thing about adaptive clocking is that ``battery powered hand
4600 held device example'' - the adaptiveness works perfectly all the
4601 time. One can set a break point or halt the system in the deep power
4602 down code, slow step out until the system speeds up.
4604 @b{Solution #2 - Always works - but may be slower}
4606 Often this is a perfectly acceptable solution.
4608 In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
4609 the target clock speed. But what that ``magic division'' is varies
4610 depending on the chips on your board. @b{ARM rule of thumb} Most ARM
4611 based systems require an 8:1 division. @b{Xilinx rule of thumb} is
4612 1/12 the clock speed.
4614 Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
4616 You can still debug the 'low power' situations - you just need to
4617 manually adjust the clock speed at every step. While painful and
4618 tedious, it is not always practical.
4620 It is however easy to ``code your way around it'' - i.e.: Cheat a little,
4621 have a special debug mode in your application that does a ``high power
4622 sleep''. If you are careful - 98% of your problems can be debugged
4625 To set the JTAG frequency use the command:
4633 @item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
4635 OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
4636 around Windows filenames.
4649 @item @b{Missing: cygwin1.dll} OpenOCD complains about a missing cygwin1.dll.
4651 Make sure you have Cygwin installed, or at least a version of OpenOCD that
4652 claims to come with all the necessary DLLs. When using Cygwin, try launching
4653 OpenOCD from the Cygwin shell.
4655 @item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a frontend like Insight or
4656 Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
4657 arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
4659 GDB issues software breakpoints when a normal breakpoint is requested, or to implement
4660 source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720T or ARM920T,
4661 software breakpoints consume one of the two available hardware breakpoints.
4663 @item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
4665 Make sure the core frequency specified in the @option{flash lpc2000} line matches the
4666 clock at the time you're programming the flash. If you've specified the crystal's
4667 frequency, make sure the PLL is disabled. If you've specified the full core speed
4668 (e.g. 60MHz), make sure the PLL is enabled.
4670 @item @b{Amontec Chameleon} When debugging using an Amontec Chameleon in its JTAG Accelerator configuration,
4671 I keep getting "Error: amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel timed
4672 out while waiting for end of scan, rtck was disabled".
4674 Make sure your PC's parallel port operates in EPP mode. You might have to try several
4675 settings in your PC BIOS (ECP, EPP, and different versions of those).
4677 @item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
4678 I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
4679 memory read caused data abort".
4681 The errors are non-fatal, and are the result of GDB trying to trace stack frames
4682 beyond the last valid frame. It might be possible to prevent this by setting up
4683 a proper "initial" stack frame, if you happen to know what exactly has to
4684 be done, feel free to add this here.
4686 @b{Simple:} In your startup code - push 8 registers of zeros onto the
4687 stack before calling main(). What GDB is doing is ``climbing'' the run
4688 time stack by reading various values on the stack using the standard
4689 call frame for the target. GDB keeps going - until one of 2 things
4690 happen @b{#1} an invalid frame is found, or @b{#2} some huge number of
4691 stackframes have been processed. By pushing zeros on the stack, GDB
4694 @b{Debugging Interrupt Service Routines} - In your ISR before you call
4695 your C code, do the same - artifically push some zeros onto the stack,
4696 remember to pop them off when the ISR is done.
4698 @b{Also note:} If you have a multi-threaded operating system, they
4699 often do not @b{in the intrest of saving memory} waste these few
4703 @item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
4704 "Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
4706 This warning doesn't indicate any serious problem, as long as you don't want to
4707 debug your core right out of reset. Your .cfg file specified @option{jtag_reset
4708 trst_and_srst srst_pulls_trst} to tell OpenOCD that either your board,
4709 your debugger or your target uC (e.g. LPC2000) can't assert the two reset signals
4710 independently. With this setup, it's not possible to halt the core right out of
4711 reset, everything else should work fine.
4713 @item @b{USB Power} When using OpenOCD in conjunction with Amontec JTAGkey and the Yagarto
4714 toolchain (Eclipse, arm-elf-gcc, arm-elf-gdb), the debugging seems to be
4715 unstable. When single-stepping over large blocks of code, GDB and OpenOCD
4716 quit with an error message. Is there a stability issue with OpenOCD?
4718 No, this is not a stability issue concerning OpenOCD. Most users have solved
4719 this issue by simply using a self-powered USB hub, which they connect their
4720 Amontec JTAGkey to. Apparently, some computers do not provide a USB power
4721 supply stable enough for the Amontec JTAGkey to be operated.
4723 @b{Laptops running on battery have this problem too...}
4725 @item @b{USB Power} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the
4726 following error messages: "Error: ft2232.c:201 ft2232_read(): FT_Read returned:
4727 4" and "Error: ft2232.c:365 ft2232_send_and_recv(): couldn't read from FT2232".
4728 What does that mean and what might be the reason for this?
4730 First of all, the reason might be the USB power supply. Try using a self-powered
4731 hub instead of a direct connection to your computer. Secondly, the error code 4
4732 corresponds to an FT_IO_ERROR, which means that the driver for the FTDI USB
4733 chip ran into some sort of error - this points us to a USB problem.
4735 @item @b{GDB Disconnects} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following
4736 error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054".
4737 What does that mean and what might be the reason for this?
4739 Error code 10054 corresponds to WSAECONNRESET, which means that the debugger (GDB)
4740 has closed the connection to OpenOCD. This might be a GDB issue.
4742 @item @b{LPC2000 Flash} In the configuration file in the section where flash device configurations
4743 are described, there is a parameter for specifying the clock frequency
4744 for LPC2000 internal flash devices (e.g. @option{flash bank lpc2000
4745 0x0 0x40000 0 0 0 lpc2000_v1 14746 calc_checksum}), which must be
4746 specified in kilohertz. However, I do have a quartz crystal of a
4747 frequency that contains fractions of kilohertz (e.g. 14,745,600 Hz,
4748 i.e. 14,745.600 kHz). Is it possible to specify real numbers for the
4751 No. The clock frequency specified here must be given as an integral number.
4752 However, this clock frequency is used by the In-Application-Programming (IAP)
4753 routines of the LPC2000 family only, which seems to be very tolerant concerning
4754 the given clock frequency, so a slight difference between the specified clock
4755 frequency and the actual clock frequency will not cause any trouble.
4757 @item @b{Command Order} Do I have to keep a specific order for the commands in the configuration file?
4759 Well, yes and no. Commands can be given in arbitrary order, yet the
4760 devices listed for the JTAG scan chain must be given in the right
4761 order (jtag newdevice), with the device closest to the TDO-Pin being
4762 listed first. In general, whenever objects of the same type exist
4763 which require an index number, then these objects must be given in the
4764 right order (jtag newtap, targets and flash banks - a target
4765 references a jtag newtap and a flash bank references a target).
4767 You can use the ``scan_chain'' command to verify and display the tap order.
4769 Also, some commands can't execute until after @command{init} has been
4770 processed. Such commands include @command{nand probe} and everything
4771 else that needs to write to controller registers, perhaps for setting
4772 up DRAM and loading it with code.
4774 @item @b{JTAG Tap Order} JTAG tap order - command order
4776 Many newer devices have multiple JTAG taps. For example: ST
4777 Microsystems STM32 chips have two taps, a ``boundary scan tap'' and
4778 ``Cortex-M3'' tap. Example: The STM32 reference manual, Document ID:
4779 RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
4780 connected to the boundary scan tap, which then connects to the
4781 Cortex-M3 tap, which then connects to the TDO pin.
4783 Thus, the proper order for the STM32 chip is: (1) The Cortex-M3, then
4784 (2) The boundary scan tap. If your board includes an additional JTAG
4785 chip in the scan chain (for example a Xilinx CPLD or FPGA) you could
4786 place it before or after the STM32 chip in the chain. For example:
4789 @item OpenOCD_TDI(output) -> STM32 TDI Pin (BS Input)
4790 @item STM32 BS TDO (output) -> STM32 Cortex-M3 TDI (input)
4791 @item STM32 Cortex-M3 TDO (output) -> SM32 TDO Pin
4792 @item STM32 TDO Pin (output) -> Xilinx TDI Pin (input)
4793 @item Xilinx TDO Pin -> OpenOCD TDO (input)
4796 The ``jtag device'' commands would thus be in the order shown below. Note:
4799 @item jtag newtap Xilinx tap -irlen ...
4800 @item jtag newtap stm32 cpu -irlen ...
4801 @item jtag newtap stm32 bs -irlen ...
4802 @item # Create the debug target and say where it is
4803 @item target create stm32.cpu -chain-position stm32.cpu ...
4807 @item @b{SYSCOMP} Sometimes my debugging session terminates with an error. When I look into the
4808 log file, I can see these error messages: Error: arm7_9_common.c:561
4809 arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
4815 @node Tcl Crash Course
4816 @chapter Tcl Crash Course
4819 Not everyone knows Tcl - this is not intended to be a replacement for
4820 learning Tcl, the intent of this chapter is to give you some idea of
4821 how the Tcl scripts work.
4823 This chapter is written with two audiences in mind. (1) OpenOCD users
4824 who need to understand a bit more of how JIM-Tcl works so they can do
4825 something useful, and (2) those that want to add a new command to
4828 @section Tcl Rule #1
4829 There is a famous joke, it goes like this:
4831 @item Rule #1: The wife is always correct
4832 @item Rule #2: If you think otherwise, See Rule #1
4835 The Tcl equal is this:
4838 @item Rule #1: Everything is a string
4839 @item Rule #2: If you think otherwise, See Rule #1
4842 As in the famous joke, the consequences of Rule #1 are profound. Once
4843 you understand Rule #1, you will understand Tcl.
4845 @section Tcl Rule #1b
4846 There is a second pair of rules.
4848 @item Rule #1: Control flow does not exist. Only commands
4849 @* For example: the classic FOR loop or IF statement is not a control
4850 flow item, they are commands, there is no such thing as control flow
4852 @item Rule #2: If you think otherwise, See Rule #1
4853 @* Actually what happens is this: There are commands that by
4854 convention, act like control flow key words in other languages. One of
4855 those commands is the word ``for'', another command is ``if''.
4858 @section Per Rule #1 - All Results are strings
4859 Every Tcl command results in a string. The word ``result'' is used
4860 deliberatly. No result is just an empty string. Remember: @i{Rule #1 -
4861 Everything is a string}
4863 @section Tcl Quoting Operators
4864 In life of a Tcl script, there are two important periods of time, the
4865 difference is subtle.
4868 @item Evaluation Time
4871 The two key items here are how ``quoted things'' work in Tcl. Tcl has
4872 three primary quoting constructs, the [square-brackets] the
4873 @{curly-braces@} and ``double-quotes''
4875 By now you should know $VARIABLES always start with a $DOLLAR
4876 sign. BTW: To set a variable, you actually use the command ``set'', as
4877 in ``set VARNAME VALUE'' much like the ancient BASIC langauge ``let x
4878 = 1'' statement, but without the equal sign.
4881 @item @b{[square-brackets]}
4882 @* @b{[square-brackets]} are command substitutions. It operates much
4883 like Unix Shell `back-ticks`. The result of a [square-bracket]
4884 operation is exactly 1 string. @i{Remember Rule #1 - Everything is a
4885 string}. These two statements are roughly identical:
4889 echo "The Date is: $X"
4892 puts "The Date is: $X"
4894 @item @b{``double-quoted-things''}
4895 @* @b{``double-quoted-things''} are just simply quoted
4896 text. $VARIABLES and [square-brackets] are expanded in place - the
4897 result however is exactly 1 string. @i{Remember Rule #1 - Everything
4901 puts "It is now \"[date]\", $x is in 1 hour"
4903 @item @b{@{Curly-Braces@}}
4904 @*@b{@{Curly-Braces@}} are magic: $VARIABLES and [square-brackets] are
4905 parsed, but are NOT expanded or executed. @{Curly-Braces@} are like
4906 'single-quote' operators in BASH shell scripts, with the added
4907 feature: @{curly-braces@} can be nested, single quotes can not. @{@{@{this is
4908 nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of
4909 28/nov/2008, Jim/OpenOCD does not have a date command.
4912 @section Consequences of Rule 1/2/3/4
4914 The consequences of Rule 1 are profound.
4916 @subsection Tokenisation & Execution.
4918 Of course, whitespace, blank lines and #comment lines are handled in
4921 As a script is parsed, each (multi) line in the script file is
4922 tokenised and according to the quoting rules. After tokenisation, that
4923 line is immedatly executed.
4925 Multi line statements end with one or more ``still-open''
4926 @{curly-braces@} which - eventually - closes a few lines later.
4928 @subsection Command Execution
4930 Remember earlier: There are no ``control flow''
4931 statements in Tcl. Instead there are COMMANDS that simply act like
4932 control flow operators.
4934 Commands are executed like this:
4937 @item Parse the next line into (argc) and (argv[]).
4938 @item Look up (argv[0]) in a table and call its function.
4939 @item Repeat until End Of File.
4942 It sort of works like this:
4945 ReadAndParse( &argc, &argv );
4947 cmdPtr = LookupCommand( argv[0] );
4949 (*cmdPtr->Execute)( argc, argv );
4953 When the command ``proc'' is parsed (which creates a procedure
4954 function) it gets 3 parameters on the command line. @b{1} the name of
4955 the proc (function), @b{2} the list of parameters, and @b{3} the body
4956 of the function. Not the choice of words: LIST and BODY. The PROC
4957 command stores these items in a table somewhere so it can be found by
4960 @subsection The FOR command
4962 The most interesting command to look at is the FOR command. In Tcl,
4963 the FOR command is normally implemented in C. Remember, FOR is a
4964 command just like any other command.
4966 When the ascii text containing the FOR command is parsed, the parser
4967 produces 5 parameter strings, @i{(If in doubt: Refer to Rule #1)} they
4971 @item The ascii text 'for'
4972 @item The start text
4973 @item The test expression
4978 Sort of reminds you of ``main( int argc, char **argv )'' does it not?
4979 Remember @i{Rule #1 - Everything is a string.} The key point is this:
4980 Often many of those parameters are in @{curly-braces@} - thus the
4981 variables inside are not expanded or replaced until later.
4983 Remember that every Tcl command looks like the classic ``main( argc,
4984 argv )'' function in C. In JimTCL - they actually look like this:
4988 MyCommand( Jim_Interp *interp,
4990 Jim_Obj * const *argvs );
4993 Real Tcl is nearly identical. Although the newer versions have
4994 introduced a byte-code parser and intepreter, but at the core, it
4995 still operates in the same basic way.
4997 @subsection FOR command implementation
4999 To understand Tcl it is perhaps most helpful to see the FOR
5000 command. Remember, it is a COMMAND not a control flow structure.
5002 In Tcl there are two underlying C helper functions.
5004 Remember Rule #1 - You are a string.
5006 The @b{first} helper parses and executes commands found in an ascii
5007 string. Commands can be seperated by semicolons, or newlines. While
5008 parsing, variables are expanded via the quoting rules.
5010 The @b{second} helper evaluates an ascii string as a numerical
5011 expression and returns a value.
5013 Here is an example of how the @b{FOR} command could be
5014 implemented. The pseudo code below does not show error handling.
5016 void Execute_AsciiString( void *interp, const char *string );
5018 int Evaluate_AsciiExpression( void *interp, const char *string );
5021 MyForCommand( void *interp,
5026 SetResult( interp, "WRONG number of parameters");
5030 // argv[0] = the ascii string just like C
5032 // Execute the start statement.
5033 Execute_AsciiString( interp, argv[1] );
5037 i = Evaluate_AsciiExpression(interp, argv[2]);
5042 Execute_AsciiString( interp, argv[3] );
5044 // Execute the LOOP part
5045 Execute_AsciiString( interp, argv[4] );
5049 SetResult( interp, "" );
5054 Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
5055 in the same basic way.
5057 @section OpenOCD Tcl Usage
5059 @subsection source and find commands
5060 @b{Where:} In many configuration files
5061 @* Example: @b{ source [find FILENAME] }
5062 @*Remember the parsing rules
5064 @item The FIND command is in square brackets.
5065 @* The FIND command is executed with the parameter FILENAME. It should
5066 find the full path to the named file. The RESULT is a string, which is
5067 substituted on the orginal command line.
5068 @item The command source is executed with the resulting filename.
5069 @* SOURCE reads a file and executes as a script.
5071 @subsection format command
5072 @b{Where:} Generally occurs in numerous places.
5073 @* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
5079 puts [format "The answer: %d" [expr $x * $y]]
5082 @item The SET command creates 2 variables, X and Y.
5083 @item The double [nested] EXPR command performs math
5084 @* The EXPR command produces numerical result as a string.
5086 @item The format command is executed, producing a single string
5087 @* Refer to Rule #1.
5088 @item The PUTS command outputs the text.
5090 @subsection Body or Inlined Text
5091 @b{Where:} Various TARGET scripts.
5094 proc someproc @{@} @{
5095 ... multiple lines of stuff ...
5097 $_TARGETNAME configure -event FOO someproc
5098 #2 Good - no variables
5099 $_TARGETNAME confgure -event foo "this ; that;"
5100 #3 Good Curly Braces
5101 $_TARGETNAME configure -event FOO @{
5104 #4 DANGER DANGER DANGER
5105 $_TARGETNAME configure -event foo "puts \"Time: [date]\""
5108 @item The $_TARGETNAME is an OpenOCD variable convention.
5109 @*@b{$_TARGETNAME} represents the last target created, the value changes
5110 each time a new target is created. Remember the parsing rules. When
5111 the ascii text is parsed, the @b{$_TARGETNAME} becomes a simple string,
5112 the name of the target which happens to be a TARGET (object)
5114 @item The 2nd parameter to the @option{-event} parameter is a TCBODY
5115 @*There are 4 examples:
5117 @item The TCLBODY is a simple string that happens to be a proc name
5118 @item The TCLBODY is several simple commands seperated by semicolons
5119 @item The TCLBODY is a multi-line @{curly-brace@} quoted string
5120 @item The TCLBODY is a string with variables that get expanded.
5123 In the end, when the target event FOO occurs the TCLBODY is
5124 evaluated. Method @b{#1} and @b{#2} are functionally identical. For
5125 Method @b{#3} and @b{#4} it is more interesting. What is the TCLBODY?
5127 Remember the parsing rules. In case #3, @{curly-braces@} mean the
5128 $VARS and [square-brackets] are expanded later, when the EVENT occurs,
5129 and the text is evaluated. In case #4, they are replaced before the
5130 ``Target Object Command'' is executed. This occurs at the same time
5131 $_TARGETNAME is replaced. In case #4 the date will never
5132 change. @{BTW: [date] is perhaps a bad example, as of 28/nov/2008,
5133 Jim/OpenOCD does not have a date command@}
5135 @subsection Global Variables
5136 @b{Where:} You might discover this when writing your own procs @* In
5137 simple terms: Inside a PROC, if you need to access a global variable
5138 you must say so. See also ``upvar''. Example:
5140 proc myproc @{ @} @{
5141 set y 0 #Local variable Y
5142 global x #Global variable X
5143 puts [format "X=%d, Y=%d" $x $y]
5146 @section Other Tcl Hacks
5147 @b{Dynamic variable creation}
5149 # Dynamically create a bunch of variables.
5150 for @{ set x 0 @} @{ $x < 32 @} @{ set x [expr $x + 1]@} @{
5152 set vn [format "BIT%d" $x]
5156 set $vn [expr (1 << $x)]
5159 @b{Dynamic proc/command creation}
5161 # One "X" function - 5 uart functions.
5162 foreach who @{A B C D E@}
5163 proc [format "show_uart%c" $who] @{ @} "show_UARTx $who"
5167 @node Target Library
5168 @chapter Target Library
5169 @cindex Target Library
5171 OpenOCD comes with a target configuration script library. These scripts can be
5172 used as-is or serve as a starting point.
5174 The target library is published together with the OpenOCD executable and
5175 the path to the target library is in the OpenOCD script search path.
5176 Similarly there are example scripts for configuring the JTAG interface.
5178 The command line below uses the example parport configuration script
5179 that ship with OpenOCD, then configures the str710.cfg target and
5180 finally issues the init and reset commands. The communication speed
5181 is set to 10kHz for reset and 8MHz for post reset.
5184 openocd -f interface/parport.cfg -f target/str710.cfg \
5185 -c "init" -c "reset"
5188 To list the target scripts available:
5191 $ ls /usr/local/lib/openocd/target
5193 arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg
5194 at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg
5195 at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg
5196 at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg
5201 @node OpenOCD Concept Index
5202 @comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
5203 @comment case issue with ``Index.html'' and ``index.html''
5204 @comment Occurs when creating ``--html --no-split'' output
5205 @comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
5206 @unnumbered OpenOCD Concept Index
5210 @node Command and Driver Index
5211 @unnumbered Command and Driver Index