@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
-@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
+@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
-@item Copyright @copyright{} 2009 David Brownell
+@item Copyright @copyright{} 2009-2010 David Brownell
@end itemize
@quotation
@menu
* About:: About OpenOCD
-* Developers:: OpenOCD Developers
-* JTAG Hardware Dongles:: JTAG Hardware Dongles
-* About JIM-Tcl:: About JIM-Tcl
+* Developers:: OpenOCD Developer Resources
+* Debug Adapter Hardware:: Debug Adapter Hardware
+* About Jim-Tcl:: About Jim-Tcl
* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
* Daemon Configuration:: Daemon Configuration
-* Interface - Dongle Configuration:: Interface - Dongle Configuration
+* Debug Adapter Configuration:: Debug Adapter Configuration
* Reset Configuration:: Reset Configuration
* TAP Declaration:: TAP Declaration
* CPU Configuration:: CPU Configuration
in-system programming and boundary-scan testing for embedded target
devices.
-@b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
-with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
+It does so with the assistance of a @dfn{debug adapter}, which is
+a small hardware module which helps provide the right kind of
+electrical signaling to the target being debugged. These are
+required since the debug host (on which OpenOCD runs) won't
+usually have native support for such signaling, or the connector
+needed to hook up to the target.
+
+Such debug adapters support one or more @dfn{transport} protocols,
+each of which involves different electrical signaling (and uses
+different messaging protocols on top of that signaling). There
+are many types of debug adapter, and little uniformity in what
+they are called. (There are also product naming differences.)
+
+These adapters are sometimes packaged as discrete dongles, which
+may generically be called @dfn{hardware interface dongles}.
+Some development boards also integrate them directly, which may
+let the development board can be directly connected to the debug
+host over USB (and sometimes also to power it over USB).
+
+For example, a @dfn{JTAG Adapter} supports JTAG
+signaling, and is used to communicate
+with JTAG (IEEE 1149.1) compliant TAPs on your target board.
A @dfn{TAP} is a ``Test Access Port'', a module which processes
special instructions and data. TAPs are daisy-chained within and
-between chips and boards.
+between chips and boards. JTAG supports debugging and boundary
+scan operations.
+
+There are also @dfn{SWD Adapters} that support Serial Wire Debug (SWD)
+signaling to communicate with some newer ARM cores, as well as debug
+adapters which support both JTAG and SWD transports. SWD only supports
+debugging, whereas JTAG also supports boundary scan operations.
+
+For some chips, there are also @dfn{Programming Adapters} supporting
+special transports used only to write code to flash memory, without
+support for on-chip debugging or boundary scan.
+(At this writing, OpenOCD does not support such non-debug adapters.)
+
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
-OpenOCD internally. @xref{JTAG Hardware Dongles}.
+OpenOCD internally. @xref{Debug Adapter Hardware}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
-Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
+Cortex-M3 (Stellaris LM3, ST STM32 and Energy Micro EFM32) based cores to be
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
-STM32x). Preliminary support for various NAND flash controllers
+internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3,
+STM32x and EFM32). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@section OpenOCD Web Site
The OpenOCD web site provides the latest public news from the community:
-@uref{http://openocd.berlios.de/web/}
+@uref{http://openocd.sourceforge.net/}
@section Latest User's Guide:
The user's guide you are now reading may not be the latest one
available. A version for more recent code may be available.
-Its HTML form is published irregularly at:
+Its HTML form is published regularly at:
-@uref{http://openocd.berlios.de/doc/html/index.html}
+@uref{http://openocd.sourceforge.net/doc/html/index.html}
PDF form is likewise published at:
-@uref{http://openocd.berlios.de/doc/pdf/openocd.pdf}
+@uref{http://openocd.sourceforge.net/doc/pdf/openocd.pdf}
@section OpenOCD User's Forum
@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+@section OpenOCD User's Mailing List
+
+The OpenOCD User Mailing List provides the primary means of
+communication between users:
+
+@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-user}
+
+@section OpenOCD IRC
+
+Support can also be found on irc:
+@uref{irc://irc.freenode.net/openocd}
@node Developers
@chapter OpenOCD Developer Resources
technical information about the software internals, development
processes, and similar documentation:
-@uref{http://openocd.berlios.de/doc/doxygen/index.html}
+@uref{http://openocd.sourceforge.net/doc/doxygen/html/index.html}
This document is a work-in-progress, but contributions would be welcome
to fill in the gaps. All of the source files are provided in-tree,
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
-@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel}
Discuss and submit patches to this list.
-The @file{PATCHES} file contains basic information about how
+The @file{HACKING} file contains basic information about how
to prepare patches.
+@section OpenOCD Bug Database
+
+During the 0.4.x release cycle the OpenOCD project team began
+using Trac for its bug database:
+
+@uref{https://sourceforge.net/apps/trac/openocd}
-@node JTAG Hardware Dongles
-@chapter JTAG Hardware Dongles
+
+@node Debug Adapter Hardware
+@chapter Debug Adapter Hardware
@cindex dongles
@cindex FTDI
@cindex wiggler
Defined: @b{dongle}: A small device that plugins into a computer and serves as
an adapter .... [snip]
-In the OpenOCD case, this generally refers to @b{a small adapater} one
-attaches to your computer via USB or the Parallel Printer Port. The
-execption being the Zylin ZY1000 which is a small box you attach via
+In the OpenOCD case, this generally refers to @b{a small adapter} that
+attaches to your computer via USB or the Parallel Printer Port. One
+exception is the Zylin ZY1000, packaged as a small box you attach via
an ethernet cable. The Zylin ZY1000 has the advantage that it does not
require any drivers to be installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
There are several things you should keep in mind when choosing a dongle.
@enumerate
+@item @b{Transport} Does it support the kind of communication that you need?
+OpenOCD focusses mostly on JTAG. Your version may also support
+other ways to communicate with target devices.
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
Does your dongle support it? You might need a level converter.
@item @b{Pinout} What pinout does your target board use?
wires, or an "octopus" connector, to convert pinouts.
@item @b{Connection} Does your computer have the USB, printer, or
Ethernet port needed?
-@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
+@item @b{RTCK} Do you expect to use it with ARM chips and boards with
+RTCK support? Also known as ``adaptive clocking''
@end enumerate
@section Stand alone Systems
-@b{ZY1000} See: @url{http://www.zylin.com/zy1000.html} Technically, not a
+@b{ZY1000} See: @url{http://www.ultsol.com/index.php/component/content/article/8/33-zylin-zy1000-jtag-probe} Technically, not a
dongle, but a standalone box. The ZY1000 has the advantage that it does
not require any drivers installed on the developer PC. It also has
a built in web interface. It supports RTCK/RCLK or adaptive clocking
known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
See: @url{http://www.ftdichip.com} for more information.
In summer 2009, USB high speed (480 Mbps) versions of these FTDI
-chips are starting to become available in JTAG adapters.
+chips are starting to become available in JTAG adapters. (Adapters
+using those high speed FT2232H chips may support adaptive clocking.)
+
+The FT2232 chips are flexible enough to support some other
+transport options, such as SWD or the SPI variants used to
+program some chips. They have two communications channels,
+and one can be used for a UART adapter at the same time the
+other one is used to provide a debug adapter.
+
+Also, some development boards integrate an FT2232 chip to serve as
+a built-in low cost debug adapter and usb-to-serial solution.
@itemize @bullet
@item @b{usbjtag}
-@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
+@* Link @url{http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
@item @b{jtagkey2}
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{Stellaris Eval Boards}
-@* See: @url{http://www.luminarymicro.com} - The Stellaris eval boards
+@* See: @url{http://www.ti.com} - The Stellaris eval boards
bundle FT2232-based JTAG and SWD support, which can be used to debug
the Stellaris chips. Using separate JTAG adapters is optional.
-These boards can also be used as JTAG adapters to other target boards,
-disabling the Stellaris chip.
-@item @b{Luminary ICDI}
-@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug
-Interface (ICDI) Boards are included in Stellaris LM3S9B90 and LM3S9B92
+These boards can also be used in a "pass through" mode as JTAG adapters
+to other target boards, disabling the Stellaris chip.
+@item @b{TI/Luminary ICDI}
+@* See: @url{http://www.ti.com} - TI/Luminary In-Circuit Debug
+Interface (ICDI) Boards are included in Stellaris LM3S9B9x
Evaluation Kits. Like the non-detachable FT2232 support on the other
Stellaris eval boards, they can be used to debug other target boards.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
-@item @b{flyswatter}
+@item @b{Flyswatter/Flyswatter2}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
@* See:
@item @b{stm32stick}
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
-@* Axiom AXM-0432 Link @url{http://www.axman.com}
+@* Axiom AXM-0432 Link @url{http://www.axman.com} - NOTE: This JTAG does not appear
+to be available anymore as of April 2012.
@item @b{cortino}
@* Link @url{http://www.hitex.com/index.php?id=cortino}
+@item @b{dlp-usb1232h}
+@* Link @url{http://www.dlpdesign.com/usb/usb1232h.shtml}
+@item @b{digilent-hs1}
+@* Link @url{http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1}
@end itemize
@section USB-JTAG / Altera USB-Blaster compatibles
@itemize
@item @b{USB-JTAG} Kolja Waschk's USB Blaster-compatible adapter
-@* Link: @url{http://www.ixo.de/info/usb_jtag/}
+@* Link: @url{http://ixo-jtag.sourceforge.net/}
@item @b{Altera USB-Blaster}
@* Link: @url{http://www.altera.com/literature/ug/ug_usb_blstr.pdf}
@end itemize
@item @b{SEGGER JLINK}
@* Link: @url{http://www.segger.com/jlink.html}
@item @b{IAR J-Link}
-@* Link: @url{http://www.iar.com/website1/1.0.1.0/369/1/index.php}
+@* Link: @url{http://www.iar.com/en/products/hardware-debug-probes/iar-j-link/}
@end itemize
@section USB RLINK based
@itemize @bullet
@item @b{Raisonance RLink}
-@* Link: @url{http://www.raisonance.com/products/RLink.php}
+@* Link: @url{http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html}
@item @b{STM32 Primer}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer.php}
@item @b{STM32 Primer2}
@* Link: @url{http://www.stm32circle.com/resources/stm32primer2.php}
@end itemize
+@section USB ST-LINK based
+ST Micro has an adapter called @b{ST-LINK}.
+They only work with ST Micro chips, notably STM32 and STM8.
+
+@itemize @bullet
+@item @b{ST-LINK}
+@* This is available standalone and as part of some kits, eg. STM32VLDISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/219866.jsp}
+@item @b{ST-LINK/V2}
+@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
+@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
+@end itemize
+
+For info the original ST-LINK enumerates using the mass storage usb class, however
+it's implementation is completely broken. The result is this causes issues under linux.
+The simplest solution is to get linux to ignore the ST-LINK using one of the following methods:
+@itemize @bullet
+@item modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
+@item add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
+@end itemize
+
+@section USB TI/Stellaris ICDI based
+Texas Instruments has an adapter called @b{ICDI}.
+It is not to be confused with the FTDI based adapters that were originally fitted to their
+evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
-@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
+@* Link: @url{http://shop.embedded-projects.net/} - which uses an Atmel MEGA32 and a UBN9604
@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
-@* Link: @url{http://www.simonqian.com/en/Versaloon}
+@* Link: @url{http://www.versaloon.com}
@item @b{ARM-JTAG-EW}
@* Link: @url{http://www.olimex.com/dev/arm-jtag-ew.html}
+
+@item @b{Buspirate}
+@* Link: @url{http://dangerousprototypes.com/bus-pirate-manual/}
+
+@item @b{opendous}
+@* Link: @url{http://code.google.com/p/opendous-jtag/}
+
+@item @b{estick}
+@* Link: @url{http://code.google.com/p/estick-jtag/}
+
+@item @b{Keil ULINK v1}
+@* Link: @url{http://www.keil.com/ulink1/}
@end itemize
@section IBM PC Parallel Printer Port Based
The two well known ``JTAG Parallel Ports'' cables are the Xilnx DLC5
-and the MacGraigor Wiggler. There are many clones and variations of
+and the Macraigor Wiggler. There are many clones and variations of
these on the market.
Note that parallel ports are becoming much less common, so if you
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
@item @b{Wiggler2}
-@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
-Improved parallel-port wiggler-style JTAG adapter}
+@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@item @b{flashlink}
@* From ST Microsystems;
-@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
-FlashLINK JTAG programing cable for PSD and uPSD}
+@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
@end itemize
@end itemize
-@node About JIM-Tcl
-@chapter About JIM-Tcl
-@cindex JIM Tcl
+@node About Jim-Tcl
+@chapter About Jim-Tcl
+@cindex Jim-Tcl
@cindex tcl
-OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
+OpenOCD uses a small ``Tcl Interpreter'' known as Jim-Tcl.
This programming language provides a simple and extensible
command interpreter.
-All commands presented in this Guide are extensions to JIM-Tcl.
+All commands presented in this Guide are extensions to Jim-Tcl.
You can use them as simple commands, without needing to learn
much of anything about Tcl.
Alternatively, can write Tcl programs with them.
-You can learn more about JIM at its website, @url{http://jim.berlios.de}.
+You can learn more about Jim at its website, @url{http://jim.berlios.de}.
+There is an active and responsive community, get on the mailing list
+if you have any questions. Jim-Tcl maintainers also lurk on the
+OpenOCD mailing list.
@itemize @bullet
-@item @b{JIM vs. Tcl}
-@* JIM-TCL is a stripped down version of the well known Tcl language,
-which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
-fewer features. JIM-Tcl is a single .C file and a single .H file and
+@item @b{Jim vs. Tcl}
+@* Jim-Tcl is a stripped down version of the well known Tcl language,
+which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far
+fewer features. Jim-Tcl is several dozens of .C files and .H files and
implements the basic Tcl command set. In contrast: Tcl 8.6 is a
4.2 MB .zip file containing 1540 files.
@item @b{Missing Features}
@* Our practice has been: Add/clone the real Tcl feature if/when
-needed. We welcome JIM Tcl improvements, not bloat.
+needed. We welcome Jim-Tcl improvements, not bloat. Also there
+are a large number of optional Jim-Tcl features that are not
+enabled in OpenOCD.
@item @b{Scripts}
-@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
+@* OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
command interpreter today is a mixture of (newer)
-JIM-Tcl commands, and (older) the orginal command interpreter.
+Jim-Tcl commands, and (older) the orginal command interpreter.
@item @b{Commands}
-@* At the OpenOCD telnet command line (or via the GDB mon command) one
+@* At the OpenOCD telnet command line (or via the GDB monitor command) one
can type a Tcl for() loop, set variables, etc.
Some of the commands documented in this guide are implemented
as Tcl scripts, from a @file{startup.tcl} file internal to the server.
@item @b{Historical Note}
-@* JIM-Tcl was introduced to OpenOCD in spring 2008.
+@* Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
+before OpenOCD 0.5 release OpenOCD switched to using Jim Tcl
+as a git submodule, which greatly simplified upgrading Jim Tcl
+to benefit from new features and bugfixes in Jim Tcl.
@item @b{Need a crash course in Tcl?}
@*@xref{Tcl Crash Course}.
@cindex logfile
@cindex directory search
+Properly installing OpenOCD sets up your operating system to grant it access
+to the debug adapters. On Linux, this usually involves installing a file
+in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs
+complex and confusing driver configuration for every peripheral. Such issues
+are unique to each operating system, and are not detailed in this User's Guide.
+
+Then later you will invoke the OpenOCD server, with various options to
+tell it how each debug session should work.
The @option{--help} option shows:
@verbatim
bash$ openocd --help
--debug | -d set debug level <0-3>
--log_output | -l redirect log output to file <name>
--command | -c run <command>
---pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the configuration file @file{openocd.cfg}.
-To specify a different (or multiple)
-configuration file, you can use the @option{-f} option. For example:
+If you don't give any @option{-f} or @option{-c} options,
+OpenOCD tries to read the configuration file @file{openocd.cfg}.
+To specify one or more different
+configuration files, use @option{-f} options. For example:
@example
openocd -f config1.cfg -f config2.cfg -f config3.cfg
@enumerate
@item the current directory,
@item any search dir specified on the command line using the @option{-s} option,
+@item any search dir specified using the @command{add_script_search_dir} command,
@item @file{$HOME/.openocd} (not on Windows),
@item the site wide script library @file{$pkgdatadir/site} and
@item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}.
@end enumerate
The first found file with a matching file name will be used.
+@quotation Note
+Don't try to use configuration script names or paths which
+include the "#" character. That character begins Tcl comments.
+@end quotation
+
@section Simple setup, no customization
In the best case, you can use two scripts from one of the script
@example
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
For bug reports, read
- http://openocd.berlios.de/doc/doxygen/bugs.html
+ http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
(mfg: 0x23b, part: 0xba00, ver: 0x3)
@end example
If you are having problems, you can enable internal debug messages via
the @option{-d} option.
-Also it is possible to interleave JIM-Tcl commands w/config scripts using the
+Also it is possible to interleave Jim-Tcl commands w/config scripts using the
@option{-c} command line switch.
To enable debug output (when reporting problems or working on OpenOCD
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
-For details on the @option{-p} option. @xref{Connecting to GDB}.
-
Note! OpenOCD will launch the GDB & telnet server even if it can not
establish a connection with the target. In general, it is possible for
the JTAG controller to be unresponsive until the target is set up
own subdirectory in the @file{scripts} directory:
@enumerate
-@item @b{interface} -- one for each kind of JTAG adapter/dongle
+@item @b{interface} -- one for each different debug adapter;
@item @b{board} -- one for each different board
@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
@end enumerate
@item Maybe you don't know yet what your board looks like to JTAG.
Once you know the @file{interface.cfg} file to use, you may
need help from OpenOCD to discover what's on the board.
-Once you find the TAPs, you can just search for appropriate
+Once you find the JTAG TAPs, you can just search for appropriate
+target and board
configuration files ... or write your own, from the bottom up.
@xref{Autoprobing}.
@item
You may may need to write some C code.
It may be as simple as a supporting a new ft2232 or parport
-based dongle; a bit more involved, like a NAND or NOR flash
+based adapter; a bit more involved, like a NAND or NOR flash
controller driver; or a big piece of work like supporting
a new chip architecture.
@end itemize
@itemize @bullet
+@item @b{Watchdog Timers}...
+Watchog timers are typically used to automatically reset systems if
+some application task doesn't periodically reset the timer. (The
+assumption is that the system has locked up if the task can't run.)
+When a JTAG debugger halts the system, that task won't be able to run
+and reset the timer ... potentially causing resets in the middle of
+your debug sessions.
+
+It's rarely a good idea to disable such watchdogs, since their usage
+needs to be debugged just like all other parts of your firmware.
+That might however be your only option.
+
+Look instead for chip-specific ways to stop the watchdog from counting
+while the system is in a debug halt state. It may be simplest to set
+that non-counting mode in your debugger startup scripts. You may however
+need a different approach when, for example, a motor could be physically
+damaged by firmware remaining inactive in a debug halt state. That might
+involve a type of firmware mode where that "non-counting" mode is disabled
+at the beginning then re-enabled at the end; a watchdog reset might fire
+and complicate the debug session, but hardware (or people) would be
+protected.@footnote{Note that many systems support a "monitor mode" debug
+that is a somewhat cleaner way to address such issues. You can think of
+it as only halting part of the system, maybe just one task,
+instead of the whole thing.
+At this writing, January 2010, OpenOCD based debugging does not support
+monitor mode debug, only "halt mode" debug.}
+
@item @b{ARM Semihosting}...
@cindex ARM semihosting
When linked with a special runtime library provided with many
You may want to @emph{disable that instruction} in source code,
or otherwise prevent using that state,
-to ensure you can get JTAG access at any time.
+to ensure you can get JTAG access at any time.@footnote{As a more
+polite alternative, some processors have special debug-oriented
+registers which can be used to change various features including
+how the low power states are clocked while debugging.
+The STM32 DBGMCU_CR register is an example; at the cost of extra
+power consumption, JTAG can be used during low power states.}
For example, the OpenOCD @command{halt} command may not
work for an idle processor otherwise.
@end itemize
+@section Target Hardware Setup
+
+Chip vendors often provide software development boards which
+are highly configurable, so that they can support all options
+that product boards may require. @emph{Make sure that any
+jumpers or switches match the system configuration you are
+working with.}
+
+Common issues include:
+
+@itemize @bullet
+
+@item @b{JTAG setup} ...
+Boards may support more than one JTAG configuration.
+Examples include jumpers controlling pullups versus pulldowns
+on the nTRST and/or nSRST signals, and choice of connectors
+(e.g. which of two headers on the base board,
+or one from a daughtercard).
+For some Texas Instruments boards, you may need to jumper the
+EMU0 and EMU1 signals (which OpenOCD won't currently control).
+
+@item @b{Boot Modes} ...
+Complex chips often support multiple boot modes, controlled
+by external jumpers. Make sure this is set up correctly.
+For example many i.MX boards from NXP need to be jumpered
+to "ATX mode" to start booting using the on-chip ROM, when
+using second stage bootloader code stored in a NAND flash chip.
+
+Such explicit configuration is common, and not limited to
+booting from NAND. You might also need to set jumpers to
+start booting using code loaded from an MMC/SD card; external
+SPI flash; Ethernet, UART, or USB links; NOR flash; OneNAND
+flash; some external host; or various other sources.
+
+
+@item @b{Memory Addressing} ...
+Boards which support multiple boot modes may also have jumpers
+to configure memory addressing. One board, for example, jumpers
+external chipselect 0 (used for booting) to address either
+a large SRAM (which must be pre-loaded via JTAG), NOR flash,
+or NAND flash. When it's jumpered to address NAND flash, that
+board must also be told to start booting from on-chip ROM.
+
+Your @file{board.cfg} file may also need to be told this jumper
+configuration, so that it can know whether to declare NOR flash
+using @command{flash bank} or instead declare NAND flash with
+@command{nand device}; and likewise which probe to perform in
+its @code{reset-init} handler.
+
+A closely related issue is bus width. Jumpers might need to
+distinguish between 8 bit or 16 bit bus access for the flash
+used to start booting.
+
+@item @b{Peripheral Access} ...
+Development boards generally provide access to every peripheral
+on the chip, sometimes in multiple modes (such as by providing
+multiple audio codec chips).
+This interacts with software
+configuration of pin multiplexing, where for example a
+given pin may be routed either to the MMC/SD controller
+or the GPIO controller. It also often interacts with
+configuration jumpers. One jumper may be used to route
+signals to an MMC/SD card slot or an expansion bus (which
+might in turn affect booting); others might control which
+audio or video codecs are used.
+
+@end itemize
+
+Plus you should of course have @code{reset-init} event handlers
+which set up the hardware to match that jumper configuration.
+That includes in particular any oscillator or PLL used to clock
+the CPU, and any memory controllers needed to access external
+memory and peripherals. Without such handlers, you won't be
+able to access those resources without working target firmware
+which can do that setup ... this can be awkward when you're
+trying to debug that target firmware. Even if there's a ROM
+bootloader which handles a few issues, it rarely provides full
+access to all board-specific capabilities.
+
+
@node Config File Guidelines
@chapter Config File Guidelines
Use them as-is where you can; or as models for new files.
@itemize @bullet
@item @file{interface} ...
-think JTAG Dongle. Files that configure JTAG adapters go here.
+These are for debug adapters.
+Files that configure JTAG adapters go here.
@example
$ ls interface
-arm-jtag-ew.cfg hitex_str9-comstick.cfg oocdlink.cfg
-arm-usb-ocd.cfg icebear.cfg openocd-usb.cfg
-at91rm9200.cfg jlink.cfg parport.cfg
-axm0432.cfg jtagkey2.cfg parport_dlc5.cfg
-calao-usb-a9260-c01.cfg jtagkey.cfg rlink.cfg
-calao-usb-a9260-c02.cfg jtagkey-tiny.cfg sheevaplug.cfg
-calao-usb-a9260.cfg luminary.cfg signalyzer.cfg
-chameleon.cfg luminary-icdi.cfg stm32-stick.cfg
-cortino.cfg luminary-lm3s811.cfg turtelizer2.cfg
-dummy.cfg olimex-arm-usb-ocd.cfg usbprog.cfg
-flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
+altera-usb-blaster.cfg hilscher_nxhx50_etm.cfg openrd.cfg
+arm-jtag-ew.cfg hilscher_nxhx50_re.cfg osbdm.cfg
+arm-usb-ocd.cfg hitex_str9-comstick.cfg parport.cfg
+at91rm9200.cfg icebear.cfg parport_dlc5.cfg
+axm0432.cfg jlink.cfg redbee-econotag.cfg
+busblaster.cfg jtagkey2.cfg redbee-usb.cfg
+buspirate.cfg jtagkey2p.cfg rlink.cfg
+calao-usb-a9260-c01.cfg jtagkey.cfg sheevaplug.cfg
+calao-usb-a9260-c02.cfg jtagkey-tiny.cfg signalyzer.cfg
+calao-usb-a9260.cfg kt-link.cfg signalyzer-h2.cfg
+chameleon.cfg lisa-l.cfg signalyzer-h4.cfg
+cortino.cfg luminary.cfg signalyzer-lite.cfg
+digilent-hs1.cfg luminary-icdi.cfg stlink-v1.cfg
+dlp-usb1232h.cfg luminary-lm3s811.cfg stlink-v2.cfg
+dummy.cfg minimodule.cfg stm32-stick.cfg
+estick.cfg neodb.cfg turtelizer2.cfg
+flashlink.cfg ngxtech.cfg ulink.cfg
+flossjtag.cfg olimex-arm-usb-ocd.cfg usb-jtag.cfg
+flossjtag-noeeprom.cfg olimex-arm-usb-ocd-h.cfg usbprog.cfg
+flyswatter2.cfg olimex-arm-usb-tiny-h.cfg vpaclink.cfg
+flyswatter.cfg olimex-jtag-tiny.cfg vsllink.cfg
+hilscher_nxhx10_etm.cfg oocdlink.cfg xds100v2.cfg
+hilscher_nxhx500_etm.cfg opendous.cfg
+hilscher_nxhx500_re.cfg openocd-usb.cfg
$
@end example
@item @file{board} ...
a CPU and an FPGA.
@example
$ ls board
-arm_evaluator7t.cfg keil_mcb1700.cfg
-at91rm9200-dk.cfg keil_mcb2140.cfg
-at91sam9g20-ek.cfg linksys_nslu2.cfg
-atmel_at91sam7s-ek.cfg logicpd_imx27.cfg
-atmel_at91sam9260-ek.cfg mini2440.cfg
-atmel_sam3u_ek.cfg olimex_LPC2378STK.cfg
-crossbow_tech_imote2.cfg olimex_lpc_h2148.cfg
-csb337.cfg olimex_sam7_ex256.cfg
-csb732.cfg olimex_sam9_l9260.cfg
-digi_connectcore_wi-9c.cfg olimex_stm32_h103.cfg
-dm355evm.cfg omap2420_h4.cfg
-dm365evm.cfg osk5912.cfg
-dm6446evm.cfg pic-p32mx.cfg
-eir.cfg propox_mmnet1001.cfg
-ek-lm3s1968.cfg pxa255_sst.cfg
-ek-lm3s3748.cfg sheevaplug.cfg
-ek-lm3s811.cfg stm3210e_eval.cfg
-ek-lm3s9b9x.cfg stm32f10x_128k_eval.cfg
-hammer.cfg str910-eval.cfg
-hitex_lpc2929.cfg telo.cfg
-hitex_stm32-performancestick.cfg ti_beagleboard.cfg
-hitex_str9-comstick.cfg topas910.cfg
-iar_str912_sk.cfg topasa900.cfg
-imx27ads.cfg unknown_at91sam9260.cfg
-imx27lnst.cfg x300t.cfg
-imx31pdk.cfg zy1000.cfg
+actux3.cfg logicpd_imx27.cfg
+am3517evm.cfg lubbock.cfg
+arm_evaluator7t.cfg mcb1700.cfg
+at91cap7a-stk-sdram.cfg microchip_explorer16.cfg
+at91eb40a.cfg mini2440.cfg
+at91rm9200-dk.cfg mini6410.cfg
+at91rm9200-ek.cfg olimex_LPC2378STK.cfg
+at91sam9261-ek.cfg olimex_lpc_h2148.cfg
+at91sam9263-ek.cfg olimex_sam7_ex256.cfg
+at91sam9g20-ek.cfg olimex_sam9_l9260.cfg
+atmel_at91sam7s-ek.cfg olimex_stm32_h103.cfg
+atmel_at91sam9260-ek.cfg olimex_stm32_h107.cfg
+atmel_at91sam9rl-ek.cfg olimex_stm32_p107.cfg
+atmel_sam3n_ek.cfg omap2420_h4.cfg
+atmel_sam3s_ek.cfg open-bldc.cfg
+atmel_sam3u_ek.cfg openrd.cfg
+atmel_sam3x_ek.cfg osk5912.cfg
+atmel_sam4s_ek.cfg phytec_lpc3250.cfg
+balloon3-cpu.cfg pic-p32mx.cfg
+colibri.cfg propox_mmnet1001.cfg
+crossbow_tech_imote2.cfg pxa255_sst.cfg
+csb337.cfg redbee.cfg
+csb732.cfg rsc-w910.cfg
+da850evm.cfg sheevaplug.cfg
+digi_connectcore_wi-9c.cfg smdk6410.cfg
+diolan_lpc4350-db1.cfg spear300evb.cfg
+dm355evm.cfg spear300evb_mod.cfg
+dm365evm.cfg spear310evb20.cfg
+dm6446evm.cfg spear310evb20_mod.cfg
+efikamx.cfg spear320cpu.cfg
+eir.cfg spear320cpu_mod.cfg
+ek-lm3s1968.cfg steval_pcc010.cfg
+ek-lm3s3748.cfg stm320518_eval_stlink.cfg
+ek-lm3s6965.cfg stm32100b_eval.cfg
+ek-lm3s811.cfg stm3210b_eval.cfg
+ek-lm3s811-revb.cfg stm3210c_eval.cfg
+ek-lm3s9b9x.cfg stm3210e_eval.cfg
+ek-lm4f232.cfg stm3220g_eval.cfg
+embedded-artists_lpc2478-32.cfg stm3220g_eval_stlink.cfg
+ethernut3.cfg stm3241g_eval.cfg
+glyn_tonga2.cfg stm3241g_eval_stlink.cfg
+hammer.cfg stm32f0discovery.cfg
+hilscher_nxdb500sys.cfg stm32f4discovery.cfg
+hilscher_nxeb500hmi.cfg stm32ldiscovery.cfg
+hilscher_nxhx10.cfg stm32vldiscovery.cfg
+hilscher_nxhx500.cfg str910-eval.cfg
+hilscher_nxhx50.cfg telo.cfg
+hilscher_nxsb100.cfg ti_beagleboard.cfg
+hitex_lpc2929.cfg ti_beagleboard_xm.cfg
+hitex_stm32-performancestick.cfg ti_beaglebone.cfg
+hitex_str9-comstick.cfg ti_blaze.cfg
+iar_lpc1768.cfg ti_pandaboard.cfg
+iar_str912_sk.cfg ti_pandaboard_es.cfg
+icnova_imx53_sodimm.cfg topas910.cfg
+icnova_sam9g45_sodimm.cfg topasa900.cfg
+imx27ads.cfg twr-k60n512.cfg
+imx27lnst.cfg tx25_stk5.cfg
+imx28evk.cfg tx27_stk5.cfg
+imx31pdk.cfg unknown_at91sam9260.cfg
+imx35pdk.cfg uptech_2410.cfg
+imx53loco.cfg verdex.cfg
+keil_mcb1700.cfg voipac.cfg
+keil_mcb2140.cfg voltcraft_dso-3062c.cfg
+kwikstik.cfg x300t.cfg
+linksys_nslu2.cfg zy1000.cfg
+lisa-l.cfg
$
@end example
@item @file{target} ...
the target config file defines all of them.
@example
$ ls target
-aduc702x.cfg imx27.cfg pxa255.cfg
-ar71xx.cfg imx31.cfg pxa270.cfg
-at91eb40a.cfg imx35.cfg readme.txt
-at91r40008.cfg is5114.cfg sam7se512.cfg
-at91rm9200.cfg ixp42x.cfg sam7x256.cfg
-at91sam3u1c.cfg lm3s1968.cfg samsung_s3c2410.cfg
-at91sam3u1e.cfg lm3s3748.cfg samsung_s3c2440.cfg
-at91sam3u2c.cfg lm3s6965.cfg samsung_s3c2450.cfg
-at91sam3u2e.cfg lm3s811.cfg samsung_s3c4510.cfg
-at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg
-at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg
-at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg
-at91sam7sx.cfg lpc2124.cfg smp8634.cfg
-at91sam9260.cfg lpc2129.cfg stm32.cfg
-c100.cfg lpc2148.cfg str710.cfg
-c100config.tcl lpc2294.cfg str730.cfg
-c100helper.tcl lpc2378.cfg str750.cfg
-c100regs.tcl lpc2478.cfg str912.cfg
-cs351x.cfg lpc2900.cfg telo.cfg
-davinci.cfg mega128.cfg ti_dm355.cfg
-dragonite.cfg netx500.cfg ti_dm365.cfg
-epc9301.cfg omap2420.cfg ti_dm6446.cfg
-feroceon.cfg omap3530.cfg tmpa900.cfg
-icepick.cfg omap5912.cfg tmpa910.cfg
-imx21.cfg pic32mx.cfg xba_revA3.cfg
-$
+$duc702x.cfg ixp42x.cfg
+am335x.cfg k40.cfg
+amdm37x.cfg k60.cfg
+ar71xx.cfg lpc1768.cfg
+at32ap7000.cfg lpc2103.cfg
+at91r40008.cfg lpc2124.cfg
+at91rm9200.cfg lpc2129.cfg
+at91sam3ax_4x.cfg lpc2148.cfg
+at91sam3ax_8x.cfg lpc2294.cfg
+at91sam3ax_xx.cfg lpc2378.cfg
+at91sam3nXX.cfg lpc2460.cfg
+at91sam3sXX.cfg lpc2478.cfg
+at91sam3u1c.cfg lpc2900.cfg
+at91sam3u1e.cfg lpc2xxx.cfg
+at91sam3u2c.cfg lpc3131.cfg
+at91sam3u2e.cfg lpc3250.cfg
+at91sam3u4c.cfg lpc4350.cfg
+at91sam3u4e.cfg mc13224v.cfg
+at91sam3uxx.cfg nuc910.cfg
+at91sam3XXX.cfg omap2420.cfg
+at91sam4sXX.cfg omap3530.cfg
+at91sam4XXX.cfg omap4430.cfg
+at91sam7se512.cfg omap4460.cfg
+at91sam7sx.cfg omap5912.cfg
+at91sam7x256.cfg omapl138.cfg
+at91sam7x512.cfg pic32mx.cfg
+at91sam9260.cfg pxa255.cfg
+at91sam9260_ext_RAM_ext_flash.cfg pxa270.cfg
+at91sam9261.cfg pxa3xx.cfg
+at91sam9263.cfg readme.txt
+at91sam9.cfg samsung_s3c2410.cfg
+at91sam9g10.cfg samsung_s3c2440.cfg
+at91sam9g20.cfg samsung_s3c2450.cfg
+at91sam9g45.cfg samsung_s3c4510.cfg
+at91sam9rl.cfg samsung_s3c6410.cfg
+atmega128.cfg sharp_lh79532.cfg
+avr32.cfg smp8634.cfg
+c100.cfg spear3xx.cfg
+c100config.tcl stellaris.cfg
+c100helper.tcl stm32.cfg
+c100regs.tcl stm32f0x_stlink.cfg
+cs351x.cfg stm32f1x.cfg
+davinci.cfg stm32f1x_stlink.cfg
+dragonite.cfg stm32f2x.cfg
+dsp56321.cfg stm32f2x_stlink.cfg
+dsp568013.cfg stm32f2xxx.cfg
+dsp568037.cfg stm32f4x.cfg
+epc9301.cfg stm32f4x_stlink.cfg
+faux.cfg stm32l.cfg
+feroceon.cfg stm32lx_stlink.cfg
+fm3.cfg stm32_stlink.cfg
+hilscher_netx10.cfg stm32xl.cfg
+hilscher_netx500.cfg str710.cfg
+hilscher_netx50.cfg str730.cfg
+icepick.cfg str750.cfg
+imx21.cfg str912.cfg
+imx25.cfg swj-dp.tcl
+imx27.cfg test_reset_syntax_error.cfg
+imx28.cfg test_syntax_error.cfg
+imx31.cfg ti_dm355.cfg
+imx35.cfg ti_dm365.cfg
+imx51.cfg ti_dm6446.cfg
+imx53.cfg tmpa900.cfg
+imx.cfg tmpa910.cfg
+is5114.cfg u8500.cfg
@end example
@item @emph{more} ... browse for other library files which may be useful.
For example, there are various generic and CPU-specific utilities.
source [find interface/FOOBAR.cfg]
@end example
-A preconfigured interface file should exist for every interface in use
-today, that said, perhaps some interfaces have only been used by the
-sole developer who created it.
+A preconfigured interface file should exist for every debug adapter
+in use today with OpenOCD.
+That said, perhaps some of these config files
+have only been used by the developer who created it.
A separate chapter gives information about how to set these up.
-@xref{Interface - Dongle Configuration}.
-Read the OpenOCD source code if you have a new kind of hardware interface
+@xref{Debug Adapter Configuration}.
+Read the OpenOCD source code (and Developer's Guide)
+if you have a new kind of hardware interface
and need to provide a driver for it.
@section Board Config Files
board and target config files communicate is by following a
convention on how to use certain variables.
-The full Tcl/Tk language supports ``namespaces'', but JIM-Tcl does not.
+The full Tcl/Tk language supports ``namespaces'', but Jim-Tcl does not.
Thus the rule we follow in OpenOCD is this: Variables that begin with
a leading underscore are temporary in nature, and can be modified and
used at will within a target configuration file.
solution just avoids using that instruction with JTAG debuggers.
@end quotation
-If the board supports adaptive clocking, use the @command{jtag_rclk}
+If both the chip and the board support adaptive clocking,
+use the @command{jtag_rclk}
command, in case your board is used with JTAG adapter which
-also supports it. Otherwise use @command{jtag_khz}.
+also supports it. Otherwise use @command{adapter_khz}.
Set the slow rate at the beginning of the reset sequence,
and the faster rate as soon as the clocks are at full speed.
+@anchor{The init_board procedure}
+@subsection The init_board procedure
+@cindex init_board procedure
+
+The concept of @code{init_board} procedure is very similar to @code{init_targets} (@xref{The init_targets procedure}.)
+- it's a replacement of ``linear'' configuration scripts. This procedure is meant to be executed when OpenOCD enters run
+stage (@xref{Entering the Run Stage},) after @code{init_targets}. The idea to have spearate @code{init_targets} and
+@code{init_board} procedures is to allow the first one to configure everything target specific (internal flash,
+internal RAM, etc.) and the second one to configure everything board specific (reset signals, chip frequency,
+reset-init event handler, external memory, etc.). Additionally ``linear'' board config file will most likely fail when
+target config file uses @code{init_targets} scheme (``linear'' script is executed before @code{init} and
+@code{init_targets} - after), so separating these two configuration stages is very convenient, as the easiest way to
+overcome this problem is to convert board config file to use @code{init_board} procedure. Board config scripts don't
+need to override @code{init_targets} defined in target config files when they only need to to add some specifics.
+
+Just as @code{init_targets}, the @code{init_board} procedure can be overriden by ``next level'' script (which sources
+the original), allowing greater code reuse.
+
+@example
+### board_file.cfg ###
+
+# source target file that does most of the config in init_targets
+source [find target/target.cfg]
+
+proc enable_fast_clock @{@} @{
+ # enables fast on-board clock source
+ # configures the chip to use it
+@}
+
+# initialize only board specifics - reset, clock, adapter frequency
+proc init_board @{@} @{
+ reset_config trst_and_srst trst_pulls_srst
+
+ $_TARGETNAME configure -event reset-init @{
+ adapter_khz 1
+ enable_fast_clock
+ adapter_khz 10000
+ @}
+@}
+@end example
+
@section Target Config Files
@cindex config file, target
@cindex target config file
-work-area-size 0x4000 -work-area-backup 0
@end example
+@anchor{Define CPU targets working in SMP}
+@subsection Define CPU targets working in SMP
+@cindex SMP
+After setting targets, you can define a list of targets working in SMP.
+
+@example
+set _TARGETNAME_1 $_CHIPNAME.cpu1
+set _TARGETNAME_2 $_CHIPNAME.cpu2
+target create $_TARGETNAME_1 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 0 -dbgbase $_DAP_DBG1
+target create $_TARGETNAME_2 cortex_a8 -chain-position $_CHIPNAME.dap \
+-coreid 1 -dbgbase $_DAP_DBG2
+#define 2 targets working in smp.
+target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
+@end example
+In the above example on cortex_a8, 2 cpus are working in SMP.
+In SMP only one GDB instance is created and :
+@itemize @bullet
+@item a set of hardware breakpoint sets the same breakpoint on all targets in the list.
+@item halt command triggers the halt of all targets in the list.
+@item resume command triggers the write context and the restart of all targets in the list.
+@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session.
+@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target
+displayed by the GDB session @pxref{Using openocd SMP with GDB}.
+@end itemize
+
+The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following
+command have been implemented.
+@itemize @bullet
+@item cortex_a8 smp_on : enable SMP mode, behaviour is as described above.
+@item cortex_a8 smp_off : disable SMP mode, the current target is the one
+displayed in the GDB session, only this target is now controlled by GDB
+session. This behaviour is useful during system boot up.
+@item cortex_a8 smp_gdb : display/fix the core id displayed in GDB session see
+following example.
+@end itemize
+
+@example
+>cortex_a8 smp_gdb
+gdb coreid 0 -> -1
+#0 : coreid 0 is displayed to GDB ,
+#-> -1 : next resume triggers a real resume
+> cortex_a8 smp_gdb 1
+gdb coreid 0 -> 1
+#0 :coreid 0 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> resume
+> cortex_a8 smp_gdb
+gdb coreid 1 -> 1
+#1 :coreid 1 is displayed to GDB ,
+#->1 : next resume displays coreid 1 to GDB
+> cortex_a8 smp_gdb -1
+gdb coreid 1 -> -1
+#1 :coreid 1 is displayed to GDB,
+#->-1 : next resume triggers a real resume
+@end example
+
+
@subsection Chip Reset Setup
As a rule, you should put the @command{reset_config} command
look at how you are setting up JTAG clocking.
@end quotation
+@anchor{The init_targets procedure}
+@subsection The init_targets procedure
+@cindex init_targets procedure
+
+Target config files can either be ``linear'' (script executed line-by-line when parsed in configuration stage,
+@xref{Configuration Stage},) or they can contain a special procedure called @code{init_targets}, which will be executed
+when entering run stage (after parsing all config files or after @code{init} command, @xref{Entering the Run Stage}.)
+Such procedure can be overriden by ``next level'' script (which sources the original). This concept faciliates code
+reuse when basic target config files provide generic configuration procedures and @code{init_targets} procedure, which
+can then be sourced and enchanced or changed in a ``more specific'' target config file. This is not possible with
+``linear'' config scripts, because sourcing them executes every initialization commands they provide.
+
+@example
+### generic_file.cfg ###
+
+proc setup_my_chip @{chip_name flash_size ram_size@} @{
+ # basic initialization procedure ...
+@}
+
+proc init_targets @{@} @{
+ # initializes generic chip with 4kB of flash and 1kB of RAM
+ setup_my_chip MY_GENERIC_CHIP 4096 1024
+@}
+
+### specific_file.cfg ###
+
+source [find target/generic_file.cfg]
+
+proc init_targets @{@} @{
+ # initializes specific chip with 128kB of flash and 64kB of RAM
+ setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
+@}
+@end example
+
+The easiest way to convert ``linear'' config files to @code{init_targets} version is to enclose every line of ``code''
+(i.e. not @code{source} commands, procedures, etc.) in this procedure.
+
+For an example of this scheme see LPC2000 target config files.
+
+The @code{init_boards} procedure is a similar concept concerning board config files (@xref{The init_board procedure}.)
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
When the OpenOCD server process starts up, it enters a
@emph{configuration stage} which is the only time that
certain commands, @emph{configuration commands}, may be issued.
+Normally, configuration commands are only available
+inside startup scripts.
+
In this manual, the definition of a configuration command is
presented as a @emph{Config Command}, not as a @emph{Command}
which may be issued interactively.
+The runtime @command{help} command also highlights configuration
+commands, and those which may be issued at any time.
Those configuration commands include declaration of TAPs,
flash banks,
After it leaves this stage, configuration commands may no
longer be issued.
+@anchor{Entering the Run Stage}
@section Entering the Run Stage
The first thing OpenOCD does after leaving the configuration
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
-@deffn {Command} gdb_port (number)
+@deffn {Command} gdb_port [number]
@cindex GDB server
-Specify or query the first port used for incoming GDB connections.
-The GDB port for the
-first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+Normally gdb listens to a TCP/IP port, but GDB can also
+communicate via pipes(stdin/out or named pipes). The name
+"gdb_port" stuck because it covers probably more than 90% of
+the normal use cases.
+
+No arguments reports GDB port. "pipe" means listen to stdin
+output to stdout, an integer is base port number, "disable"
+disables the gdb server.
+
+When using "pipe", also use log_output to redirect the log
+output to a file so as not to flood the stdin/out pipes.
+
+The -p/--pipe option is deprecated and a warning is printed
+as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log".
+
+Any other string is interpreted as named pipe to listen to.
+Output pipe is the same name as input pipe, but with 'o' appended,
+e.g. /var/gdb, /var/gdbo.
+
+The GDB port for the first target will be the base port, the
+second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
-When specified as zero, this port is not activated.
@end deffn
-@deffn {Command} tcl_port (number)
+@deffn {Command} tcl_port [number]
Specify or query the port used for a simplified RPC
connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
Intended as a machine interface.
When not specified during the configuration stage,
the port @var{number} defaults to 6666.
-When specified as zero, this port is not activated.
+
@end deffn
-@deffn {Command} telnet_port (number)
+@deffn {Command} telnet_port [number]
Specify or query the
port on which to listen for incoming telnet connections.
This port is intended for interaction with one human through TCL commands.
@end example
@end deffn
-@node Interface - Dongle Configuration
-@chapter Interface - Dongle Configuration
+@node Debug Adapter Configuration
+@chapter Debug Adapter Configuration
@cindex config file, interface
@cindex interface config file
-JTAG Adapters/Interfaces/Dongles are normally configured
+Correctly installing OpenOCD includes making your operating system give
+OpenOCD access to debug adapters. Once that has been done, Tcl commands
+are used to select which one is used, and to configure how it is used.
+
+@quotation Note
+Because OpenOCD started out with a focus purely on JTAG, you may find
+places where it wrongly presumes JTAG is the only transport protocol
+in use. Be aware that recent versions of OpenOCD are removing that
+limitation. JTAG remains more functional than most other transports.
+Other transports do not support boundary scan operations, or may be
+specific to a given chip vendor. Some might be usable only for
+programming flash memory, instead of also for debugging.
+@end quotation
+
+Debug Adapters/Interfaces/Dongles are normally configured
through commands in an interface configuration
file which is sourced by your @file{openocd.cfg} file, or
through a command line @option{-f interface/....cfg} option.
@section Interface Configuration
-The interface command tells OpenOCD what type of JTAG dongle you are
-using. Depending on the type of dongle, you may need to have one or
-more additional commands.
+The interface command tells OpenOCD what type of debug adapter you are
+using. Depending on the type of adapter, you may need to use one or
+more additional commands to further identify or configure the adapter.
@deffn {Config Command} {interface} name
Use the interface driver @var{name} to connect to the
@end deffn
@deffn Command {interface_list}
-List the interface drivers that have been built into
+List the debug adapter drivers that have been built into
the running copy of OpenOCD.
@end deffn
+@deffn Command {interface transports} transport_name+
+Specifies the transports supported by this debug adapter.
+The adapter driver builds-in similar knowledge; use this only
+when external configuration (such as jumpering) changes what
+the hardware can support.
+@end deffn
+
+
-@deffn Command {jtag interface}
-Returns the name of the interface driver being used.
+@deffn Command {adapter_name}
+Returns the name of the debug adapter driver being used.
@end deffn
@section Interface Drivers
@deffn {Interface Driver} {ft2232}
FTDI FT2232 (USB) based devices over one of the userspace libraries.
+
+Note that this driver has several flaws and the @command{ftdi} driver is
+recommended as its replacement.
+
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
@item @b{axm0432_jtag} Axiom AXM-0432
@item @b{comstick} Hitex STR9 comstick
@item @b{cortino} Hitex Cortino JTAG interface
-@item @b{evb_lm3s811} Luminary Micro EVB_LM3S811 as a JTAG interface,
+@item @b{evb_lm3s811} TI/Luminary Micro EVB_LM3S811 as a JTAG interface,
either for the local Cortex-M3 (SRST only)
or in a passthrough mode (neither SRST nor TRST)
This layout can not support the SWO trace mechanism, and should be
used only for older boards (before rev C).
-@item @b{luminary_icdi} This layout should be used with most Luminary
+@item @b{luminary_icdi} This layout should be used with most TI/Luminary
eval boards, including Rev C LM3S811 eval boards and the eponymous
ICDI boards, to debug either the local Cortex-M3 or in passthrough mode
to debug some other target. It can support the SWO trace mechanism.
@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
@item @b{oocdlink} OOCDLink
@c oocdlink ~= jtagkey_prototype_v1
+@item @b{redbee-econotag} Integrated with a Redbee development board.
+@item @b{redbee-usb} Integrated with a Redbee USB-stick development board.
@item @b{sheevaplug} Marvell Sheevaplug development kit
@item @b{signalyzer} Xverve Signalyzer
@item @b{stm32stick} Hitex STM32 Performance Stick
@end example
@end deffn
+@deffn {Interface Driver} {ftdi}
+This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial
+Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H.
+It is a complete rewrite to address a large number of problems with the ft2232
+interface driver.
+
+The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
+bypassing intermediate libraries like libftdi of D2XX. Performance-wise it is
+consistently faster than the ft2232 driver, sometimes several times faster.
+
+A major improvement of this driver is that support for new FTDI based adapters
+can be added competely through configuration files, without the need to patch
+and rebuild OpenOCD.
+
+The driver uses a signal abstraction to enable Tcl configuration files to
+define outputs for one or several FTDI GPIO. These outputs can then be
+controlled using the @command{ftdi_set_signal} command. Special signal names
+are reserved for nTRST, nSRST and LED (for blink) so that they, if defined,
+will be used for their customary purpose.
+
+Depending on the type of buffer attached to the FTDI GPIO, the outputs have to
+be controlled differently. In order to support tristateable signals such as
+nSRST, both a data GPIO and an output-enable GPIO can be specified for each
+signal. The following output buffer configurations are supported:
+
+@itemize @minus
+@item Push-pull with one FTDI output as (non-)inverted data line
+@item Open drain with one FTDI output as (non-)inverted output-enable
+@item Tristate with one FTDI output as (non-)inverted data line and another
+ FTDI output as (non-)inverted output-enable
+@item Unbuffered, using the FTDI GPIO as a tristate output directly by
+ switching data and direction as necessary
+@end itemize
+
+These interfaces have several commands, used to configure the driver
+before initializing the JTAG scan chain:
+
+@deffn {Config Command} {ftdi_vid_pid} [vid pid]+
+The vendor ID and product ID of the adapter. If not specified, the FTDI
+default values are used.
+Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+@example
+ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+@end example
+@end deffn
+
+@deffn {Config Command} {ftdi_device_desc} description
+Provides the USB device description (the @emph{iProduct string})
+of the adapter. If not specified, the device description is ignored
+during device selection.
+@end deffn
+
+@deffn {Config Command} {ftdi_serial} serial-number
+Specifies the @var{serial-number} of the adapter to use,
+in case the vendor provides unique IDs and more than one adapter
+is connected to the host.
+If not specified, serial numbers are not considered.
+(Note that USB serial numbers can be arbitrary Unicode strings,
+and are not restricted to containing only decimal digits.)
+@end deffn
+
+@deffn {Config Command} {ftdi_channel} channel
+Selects the channel of the FTDI device to use for MPSSE operations. Most
+adapters use the default, channel 0, but there are exceptions.
+@end deffn
+
+@deffn {Config Command} {ftdi_layout_init} data direction
+Specifies the initial values of the FTDI GPIO data and direction registers.
+Each value is a 16-bit number corresponding to the concatenation of the high
+and low FTDI GPIO registers. The values should be selected based on the
+schematics of the adapter, such that all signals are set to safe levels with
+minimal impact on the target system. Avoid floating inputs, conflicting outputs
+and initially asserted reset signals.
+@end deffn
+
+@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask]
+Creates a signal with the specified @var{name}, controlled by one or more FTDI
+GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO
+register bitmasks to tell the driver the connection and type of the output
+buffer driving the respective signal. @var{data_mask} is the bitmask for the
+pin(s) connected to the data input of the output buffer. @option{-ndata} is
+used with inverting data inputs and @option{-data} with non-inverting inputs.
+The @option{-oe} (or @option{-noe}) option tells where the output-enable (or
+not-output-enable) input to the output buffer is connected.
+
+Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a
+simple open-collector transistor driver would be specified with @option{-oe}
+only. In that case the signal can only be set to drive low or to Hi-Z and the
+driver will complain if the signal is set to drive high. Which means that if
+it's a reset signal, @command{reset_config} must be specified as
+@option{srst_open_drain}, not @option{srst_push_pull}.
+
+A special case is provided when @option{-data} and @option{-oe} is set to the
+same bitmask. Then the FTDI pin is considered being connected straight to the
+target without any buffer. The FTDI pin is then switched between output and
+input as necessary to provide the full set of low, high and Hi-Z
+characteristics. In all other cases, the pins specified in a signal definition
+are always driven by the FTDI.
+@end deffn
+
+@deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z}
+Set a previously defined signal to the specified level.
+@itemize @minus
+@item @option{0}, drive low
+@item @option{1}, drive high
+@item @option{z}, set to high-impedance
+@end itemize
+@end deffn
+
+For example adapter definitions, see the configuration files shipped in the
+@file{interface/ftdi} directory.
+@end deffn
+
+@deffn {Interface Driver} {remote_bitbang}
+Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection
+with a remote process and sends ASCII encoded bitbang requests to that process
+instead of directly driving JTAG.
+
+The remote_bitbang driver is useful for debugging software running on
+processors which are being simulated.
+
+@deffn {Config Command} {remote_bitbang_port} number
+Specifies the TCP port of the remote process to connect to or 0 to use UNIX
+sockets instead of TCP.
+@end deffn
+
+@deffn {Config Command} {remote_bitbang_host} hostname
+Specifies the hostname of the remote process to connect to using TCP, or the
+name of the UNIX socket to use if remote_bitbang_port is 0.
+@end deffn
+
+For example, to connect remotely via TCP to the host foobar you might have
+something like:
+
+@example
+interface remote_bitbang
+remote_bitbang_port 3335
+remote_bitbang_host foobar
+@end example
+
+To connect to another process running locally via UNIX sockets with socket
+named mysocket:
+
+@example
+interface remote_bitbang
+remote_bitbang_port 0
+remote_bitbang_host mysocket
+@end example
+@end deffn
+
@deffn {Interface Driver} {usb_blaster}
USB JTAG/USB-Blaster compatibles over one of the userspace libraries
for FTDI chips. These interfaces have several commands, used to
Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for
Altera USB-Blaster (default):
@example
-ft2232_vid_pid 0x09FB 0x6001
+usb_blaster_vid_pid 0x09FB 0x6001
@end example
The following VID/PID is for Kolja Waschk's USB JTAG:
@example
-ft2232_vid_pid 0x16C0 0x06AD
+usb_blaster_vid_pid 0x16C0 0x06AD
@end example
@end deffn
Gateworks GW16012 JTAG programmer.
This has one driver-specific command:
-@deffn {Config Command} {parport_port} number
-Specifies either the address of the I/O port (default: 0x378 for LPT1) or
-the number of the @file{/dev/parport} device.
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
@end deffn
@end deffn
@deffn {Interface Driver} {jlink}
-Segger jlink USB adapter
-@c command: jlink_info
-@c dumps status
-@c command: jlink_hw_jtag (2|3)
-@c sets version 2 or 3
+Segger J-Link family of USB adapters. It currently supports only the JTAG transport.
+
+@quotation Compatibility Note
+Segger released many firmware versions for the many harware versions they
+produced. OpenOCD was extensively tested and intended to run on all of them,
+but some combinations were reported as incompatible. As a general
+recommendation, it is advisable to use the latest firmware version
+available for each hardware version. However the current V8 is a moving
+target, and Segger firmware versions released after the OpenOCD was
+released may not be compatible. In such cases it is recommended to
+revert to the last known functional version. For 0.5.0, this is from
+"Feb 8 2012 14:30:39", packed with 4.42c. For 0.6.0, the last known
+version is from "May 3 2012 18:36:22", packed with 4.46f.
+@end quotation
+
+@deffn {Command} {jlink caps}
+Display the device firmware capabilities.
+@end deffn
+@deffn {Command} {jlink info}
+Display various device information, like hardware version, firmware version, current bus status.
+@end deffn
+@deffn {Command} {jlink hw_jtag} [@option{2}|@option{3}]
+Set the JTAG protocol version to be used. Without argument, show the actual JTAG protocol version.
+@end deffn
+@deffn {Command} {jlink config}
+Display the J-Link configuration.
+@end deffn
+@deffn {Command} {jlink config kickstart} [val]
+Set the Kickstart power on JTAG-pin 19. Without argument, show the Kickstart configuration.
+@end deffn
+@deffn {Command} {jlink config mac_address} [@option{ff:ff:ff:ff:ff:ff}]
+Set the MAC address of the J-Link Pro. Without argument, show the MAC address.
+@end deffn
+@deffn {Command} {jlink config ip} [@option{A.B.C.D}(@option{/E}|@option{F.G.H.I})]
+Set the IP configuration of the J-Link Pro, where A.B.C.D is the IP address,
+ E the bit of the subnet mask and
+ F.G.H.I the subnet mask. Without arguments, show the IP configuration.
+@end deffn
+@deffn {Command} {jlink config usb_address} [@option{0x00} to @option{0x03} or @option{0xff}]
+Set the USB address; this will also change the product id. Without argument, show the USB address.
+@end deffn
+@deffn {Command} {jlink config reset}
+Reset the current configuration.
+@end deffn
+@deffn {Command} {jlink config save}
+Save the current configuration to the internal persistent storage.
+@end deffn
+@deffn {Config} {jlink pid} val
+Set the USB PID of the interface. As a configuration command, it can be used only before 'init'.
+@end deffn
@end deffn
@deffn {Interface Driver} {parport}
before initializing the JTAG scan chain:
@deffn {Config Command} {parport_cable} name
-The layout of the parallel port cable used to connect to the target.
+Set the layout of the parallel port cable used to connect to the target.
+This is a write-once setting.
Currently valid cable @var{name} values include:
@itemize @minus
@end itemize
@end deffn
-@deffn {Config Command} {parport_port} number
-Either the address of the I/O port (default: 0x378 for LPT1) or the number of
-the @file{/dev/parport} device
+@deffn {Config Command} {parport_port} [port_number]
+Display either the address of the I/O port
+(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device.
+If a parameter is provided, first switch to use that port.
+This is a write-once setting.
When using PPDEV to access the parallel port, use the number of the parallel port:
@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
@deffn Command {parport_toggling_time} [nanoseconds]
Displays how many nanoseconds the hardware needs to toggle TCK;
the parport driver uses this value to obey the
-@command{jtag_khz} configuration.
+@command{adapter_khz} configuration.
When the optional @var{nanoseconds} parameter is given,
that setting is changed before displaying the current value.
oscilloscope, follow the procedure below:
@example
> parport_toggling_time 1000
-> jtag_khz 500
+> adapter_khz 500
@end example
This sets the maximum JTAG clock speed of the hardware, but
the actual speed probably deviates from the requested 500 kHz.
@example
> parport_toggling_time <measured nanoseconds>
@end example
-Now the clock speed will be a better match for @command{jtag_khz rate}
+Now the clock speed will be a better match for @command{adapter_khz rate}
commands given in OpenOCD scripts and event handlers.
You can do something similar with many digital multimeters, but note
that you'll probably need to run the clock continuously for several
seconds before it decides what clock rate to show. Adjust the
toggling time up or down until the measured clock rate is a good
-match for the jtag_khz rate you specified; be conservative.
+match for the adapter_khz rate you specified; be conservative.
@end quotation
@end deffn
-@deffn {Config Command} {parport_write_on_exit} (on|off)
+@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off})
This will configure the parallel driver to write a known
-cable-specific value to the parallel interface on exiting OpenOCD
+cable-specific value to the parallel interface on exiting OpenOCD.
@end deffn
For example, the interface configuration file for a
-classic ``Wiggler'' cable might look something like this:
+classic ``Wiggler'' cable on LPT2 might look something like this:
@example
interface parport
-parport_port 0xc8b8
+parport_port 0x278
parport_cable wiggler
@end example
@end deffn
@deffn {Interface Driver} {presto}
ASIX PRESTO USB JTAG programmer.
-@c command: presto_serial str
-@c sets serial number
+@deffn {Config Command} {presto_serial} serial_string
+Configures the USB serial number of the Presto device to use.
+@end deffn
@end deffn
@deffn {Interface Driver} {rlink}
@end quotation
@end deffn
+@deffn {Interface Driver} {hla}
+This is a driver that supports multiple High Level Adapters.
+This type of adapter does not expose some of the lower level api's
+that OpenOCD would normally use to access the target.
+
+Currently supported adapters include the ST STLINK and TI ICDI.
+
+@deffn {Config Command} {hla_device_desc} description
+Currently Not Supported.
+@end deffn
+
+@deffn {Config Command} {hla_serial} serial
+Currently Not Supported.
+@end deffn
+
+@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi})
+Specifies the adapter layout to use.
+@end deffn
+
+@deffn {Config Command} {hla_vid_pid} vid pid
+The vendor ID and product ID of the device.
+@end deffn
+
+@deffn {Config Command} {stlink_api} api_level
+Manually sets the stlink api used, valid options are 1 or 2. (@b{STLINK Only}).
+@end deffn
+@end deffn
+
+@deffn {Interface Driver} {opendous}
+opendous-jtag is a freely programmable USB adapter.
+@end deffn
+
+@deffn {Interface Driver} {ulink}
+This is the Keil ULINK v1 JTAG debugger.
+@end deffn
+
@deffn {Interface Driver} {ZY1000}
This is the Zylin ZY1000 JTAG debugger.
+@end deffn
@quotation Note
This defines some driver-specific commands,
No arguments: print status.
@end deffn
+@section Transport Configuration
+@cindex Transport
+As noted earlier, depending on the version of OpenOCD you use,
+and the debug adapter you are using,
+several transports may be available to
+communicate with debug targets (or perhaps to program flash memory).
+@deffn Command {transport list}
+displays the names of the transports supported by this
+version of OpenOCD.
+@end deffn
+
+@deffn Command {transport select} transport_name
+Select which of the supported transports to use in this OpenOCD session.
+The transport must be supported by the debug adapter hardware and by the
+version of OPenOCD you are using (including the adapter's driver).
+No arguments: returns name of session's selected transport.
@end deffn
+@subsection JTAG Transport
+@cindex JTAG
+JTAG is the original transport supported by OpenOCD, and most
+of the OpenOCD commands support it.
+JTAG transports expose a chain of one or more Test Access Points (TAPs),
+each of which must be explicitly declared.
+JTAG supports both debugging and boundary scan testing.
+Flash programming support is built on top of debug support.
+@subsection SWD Transport
+@cindex SWD
+@cindex Serial Wire Debug
+SWD (Serial Wire Debug) is an ARM-specific transport which exposes one
+Debug Access Point (DAP, which must be explicitly declared.
+(SWD uses fewer signal wires than JTAG.)
+SWD is debug-oriented, and does not support boundary scan testing.
+Flash programming support is built on top of debug support.
+(Some processors support both JTAG and SWD.)
+@deffn Command {swd newdap} ...
+Declares a single DAP which uses SWD transport.
+Parameters are currently the same as "jtag newtap" but this is
+expected to change.
+@end deffn
+@deffn Command {swd wcr trn prescale}
+Updates TRN (turnaraound delay) and prescaling.fields of the
+Wire Control Register (WCR).
+No parameters: displays current settings.
+@end deffn
+
+@subsection SPI Transport
+@cindex SPI
+@cindex Serial Peripheral Interface
+The Serial Peripheral Interface (SPI) is a general purpose transport
+which uses four wire signaling. Some processors use it as part of a
+solution for flash programming.
+
@anchor{JTAG Speed}
@section JTAG Speed
JTAG clock setup is part of system setup.
may not be the fastest solution.
@b{NOTE:} Script writers should consider using @command{jtag_rclk}
-instead of @command{jtag_khz}.
+instead of @command{adapter_khz}, but only for (ARM) cores and boards
+which support adaptive clocking.
-@deffn {Command} jtag_khz max_speed_kHz
+@deffn {Command} adapter_khz max_speed_kHz
A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
JTAG interfaces usually support a limited number of
speeds. The speed actually used won't be faster
@emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
just the TAP controllers connected to the JTAG adapter.
Such resets should not be visible to the rest of the system; resetting a
-device's the TAP controller just puts that controller into a known state.
+device's TAP controller just puts that controller into a known state.
@item
@emph{Emulation Reset} ... many devices can be reset through JTAG
commands. These resets are often distinguishable from system
when either of those signals is not connected.
When SRST is not available, your code might not be able to rely
on controllers having been fully reset during code startup.
-Missing TRST is not a problem, since JTAG level resets can
+Missing TRST is not a problem, since JTAG-level resets can
be triggered using with TMS signaling.
@item @emph{Signals shorted} ... Sometimes a chip, board, or
requirements that all reset pulses last for at least a
certain amount of time; and reset buttons commonly have
hardware debouncing.
-Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
+Use the @command{adapter_nsrst_delay} and @command{jtag_ntrst_delay}
commands to say when extra delays are needed.
@item @emph{Drive type} ... Reset lines often have a pullup
@section Commands for Handling Resets
-@deffn {Command} jtag_nsrst_assert_width milliseconds
+@deffn {Command} adapter_nsrst_assert_width milliseconds
Minimum amount of time (in milliseconds) OpenOCD should wait
after asserting nSRST (active-low system reset) before
allowing it to be deasserted.
@end deffn
-@deffn {Command} jtag_nsrst_delay milliseconds
+@deffn {Command} adapter_nsrst_delay milliseconds
How long (in milliseconds) OpenOCD should wait after deasserting
nSRST (active-low system reset) before starting new JTAG operations.
When a board has a reset button connected to SRST line it will
with a board that only wires up SRST.)
The @var{mode_flag} options can be specified in any order, but only one
-of each type -- @var{signals}, @var{combination},
-@var{gates},
-@var{trst_type},
-and @var{srst_type} -- may be specified at a time.
+of each type -- @var{signals}, @var{combination}, @var{gates},
+@var{trst_type}, @var{srst_type} and @var{connect_type}
+-- may be specified at a time.
If you don't provide a new value for a given type, its previous
value (perhaps the default) is unchanged.
For example, this means that you don't need to say anything at all about
The default behaviour if no option given is @option{separate},
indicating everything behaves normally.
@option{srst_pulls_trst} states that the
-test logic is reset together with the reset of the system (e.g. Philips
+test logic is reset together with the reset of the system (e.g. NXP
LPC2000, "broken" board layout), @option{trst_pulls_srst} says that
the system is reset together with the test logic (only hypothetical, I
haven't seen hardware with such a bug, and can be worked around).
while SRST is asserted.
Its converse is @option{srst_nogate}, indicating that JTAG commands
can safely be issued while SRST is active.
+
+@item
+The @var{connect_type} tokens control flags that describe some cases where
+SRST is asserted while connecting to the target. @option{srst_nogate}
+is required to use this option.
+@option{connect_deassert_srst} (default)
+indicates that SRST will not be asserted while connecting to the target.
+Its converse is @option{connect_assert_srst}, indicating that SRST will
+be asserted before any target connection.
+Only some targets support this feature, STM32 and STR9 are examples.
+This feature is useful if you are unable to connect to your target due
+to incorrect options byte config or illegal program execution.
@end itemize
The optional @var{trst_type} and @var{srst_type} parameters allow the
option. When vendors put out multiple versions of a chip, or use the same
JTAG-level ID for several largely-compatible chips, it may be more practical
to ignore the version field than to update config files to handle all of
-the various chip IDs.
+the various chip IDs. The version field is defined as bit 28-31 of the IDCODE.
@item @code{-ircapture} @var{NUMBER}
@*The bit pattern loaded by the TAP into the JTAG shift register
on entry to the @sc{ircapture} state, such as 0x01.
@item @code{arm11} -- this is a generation of ARMv6 cores
@item @code{arm720t} -- this is an ARMv4 core with an MMU
@item @code{arm7tdmi} -- this is an ARMv4 core
-@item @code{arm920t} -- this is an ARMv5 core with an MMU
+@item @code{arm920t} -- this is an ARMv4 core with an MMU
@item @code{arm926ejs} -- this is an ARMv5 core with an MMU
@item @code{arm966e} -- this is an ARMv5 core
@item @code{arm9tdmi} -- this is an ARMv4 core
(Support for this is preliminary and incomplete.)
@item @code{cortex_a8} -- this is an ARMv7 core with an MMU
@item @code{cortex_m3} -- this is an ARMv7 core, supporting only the
-compact Thumb2 instruction set. It supports one variant:
-@itemize @minus
-@item @code{lm3s} ... Use this when debugging older Stellaris LM3S targets.
-This will cause OpenOCD to use a software reset rather than asserting
-SRST, to avoid a issue with clearing the debug registers.
-This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
-be detected and the normal reset behaviour used.
-@end itemize
+compact Thumb2 instruction set.
@item @code{dragonite} -- resembles arm966e
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
-@itemize @minus
-@item @code{ejtag_srst} ... Use this when debugging targets that do not
-provide a functional SRST line on the EJTAG connector. This causes
-OpenOCD to instead use an EJTAG software reset command to reset the
-processor.
-You still need to enable @option{srst} on the @command{reset_config}
-command to enable OpenOCD hardware reset functionality.
-@end itemize
@item @code{xscale} -- this is actually an architecture,
not a CPU type. It is based on the ARMv5 architecture.
There are several variants defined:
The value should normally correspond to a static mapping for the
@code{-work-area-phys} address, set up by the current operating system.
+@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
+@var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|
+@option{FreeRTOS}|@option{linux}|@option{ChibiOS}.
+
@end itemize
@end deffn
mychip.cpu configure -event gdb-attach my_attach_proc
mychip.cpu configure -event gdb-attach @{
echo "Reset..."
- reset halt
+ # To make flash probe and gdb load to flash work we need a reset init.
+ reset init
@}
@end example
@* The target has resumed (i.e.: gdb said run)
@item @b{early-halted}
@* Occurs early in the halt process
-@ignore
-@item @b{examine-end}
-@* Currently not used (goal: when JTAG examine completes)
@item @b{examine-start}
-@* Currently not used (goal: when JTAG examine starts)
-@end ignore
+@* Before target examine is called.
+@item @b{examine-end}
+@* After target examine is called with no errors.
@item @b{gdb-attach}
-@* When GDB connects
+@* When GDB connects. This is before any communication with the target, so this
+can be used to set up the target so it is possible to probe flash. Probing flash
+is necessary during gdb connect if gdb load is to write the image to flash. Another
+use of the flash memory map is for GDB to automatically hardware/software breakpoints
+depending on whether the breakpoint is in RAM or read only memory.
@item @b{gdb-detach}
@* When GDB disconnects
@item @b{gdb-end}
@* Before the target steps, gdb is trying to start/resume the target
@item @b{halted}
@* The target has halted
-@ignore
-@item @b{old-gdb_program_config}
-@* DO NOT USE THIS: Used internally
-@item @b{old-pre_resume}
-@* DO NOT USE THIS: Used internally
-@end ignore
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after @command{reset_init} was triggered
before @command{reset_init} is called.
This is the most robust place to use @command{jtag_rclk}
-or @command{jtag_khz} to switch to a low JTAG clock rate,
+or @command{adapter_khz} to switch to a low JTAG clock rate,
when reset disables PLLs needed to use a fast clock.
@ignore
@item @b{reset-wait-pos}
@* Before any target is resumed
@item @b{resume-end}
@* After all targets have resumed
-@item @b{resume-ok}
-@* Success
@item @b{resumed}
@* Target has resumed
@end itemize
-
@node Flash Commands
@chapter Flash Commands
@itemize @bullet
@item @var{name} ... may be used to reference the flash bank
-in other flash commands.
+in other flash commands. A number is also available.
@item @var{driver} ... identifies the controller driver
associated with the flash bank being declared.
This is usually @code{cfi} for external flash, or else
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash erase_address} address length
+@deffn Command {flash erase_address} [@option{pad}] [@option{unlock}] address length
Erase sectors starting at @var{address} for @var{length} bytes.
+Unless @option{pad} is specified, @math{address} must begin a
+flash sector, and @math{address + length - 1} must end a sector.
+Specifying @option{pad} erases extra data at the beginning and/or
+end of the specified region, as needed to erase only full sectors.
The flash bank to use is inferred from the @var{address}, and
the specified length must stay within that bank.
As a special case, when @var{length} is zero and @var{address} is
the start of the bank, the whole flash is erased.
+If @option{unlock} is specified, then the flash is unprotected
+before erase starts.
@end deffn
@deffn Command {flash fillw} address word length
Check erase state of sectors in flash bank @var{num},
and display that status.
The @var{num} parameter is a value shown by @command{flash banks}.
-This is the only operation that
-updates the erase state information displayed by @option{flash info}. That means you have
-to issue a @command{flash erase_check} command after erasing or programming the device
-to get updated information.
-(Code execution may have invalidated any state records kept by OpenOCD.)
@end deffn
@deffn Command {flash info} num
Print info about flash bank @var{num}
The @var{num} parameter is a value shown by @command{flash banks}.
-The information includes per-sector protect status.
+This command will first query the hardware, it does not print cached
+and possibly stale information.
@end deffn
@anchor{flash protect}
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash protect_check} num
-Check protection state of sectors in flash bank @var{num}.
-The @var{num} parameter is a value shown by @command{flash banks}.
-@comment @option{flash erase_sector} using the same syntax.
-@end deffn
-
@anchor{Flash Driver List}
@section Flash Driver List
As noted above, the @command{flash bank} command requires a driver name,
wide on a sixteen bit bus:
@example
-flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
-flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
+flash bank $_FLASHNAME cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
+flash bank $_FLASHNAME cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
@end example
To configure one bank of 32 MBytes
to create a thirty-two bit (four byte) bus with doubled throughput:
@example
-flash bank cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
+flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
@end example
@c "cfi part_id" disabled
@end deffn
+@deffn {Flash Driver} lpcspifi
+@cindex NXP SPI Flash Interface
+@cindex SPIFI
+@cindex lpcspifi
+NXP's LPC43xx and LPC18xx families include a proprietary SPI
+Flash Interface (SPIFI) peripheral that can drive and provide
+memory mapped access to external SPI flash devices.
+
+The lpcspifi driver initializes this interface and provides
+program and erase functionality for these serial flash devices.
+Use of this driver @b{requires} a working area of at least 1kB
+to be configured on the target device; more than this will
+significantly reduce flash programming times.
+
+The setup command only requires the @var{base} parameter. All
+other parameters are ignored, and the flash size and layout
+are configured by the driver.
+
+@example
+flash bank $_FLASHNAME lpcspifi 0x14000000 0 0 0 $_TARGETNAME
+@end example
+
+@end deffn
+
+@deffn {Flash Driver} stmsmi
+@cindex STMicroelectronics Serial Memory Interface
+@cindex SMI
+@cindex stmsmi
+Some devices form STMicroelectronics (e.g. STR75x MCU family,
+SPEAr MPU family) include a proprietary
+``Serial Memory Interface'' (SMI) controller able to drive external
+SPI flash devices.
+Depending on specific device and board configuration, up to 4 external
+flash devices can be connected.
+
+SMI makes the flash content directly accessible in the CPU address
+space; each external device is mapped in a memory bank.
+CPU can directly read data, execute code and boot from SMI banks.
+Normal OpenOCD commands like @command{mdw} can be used to display
+the flash content.
+
+The setup command only requires the @var{base} parameter in order
+to identify the memory bank.
+All other parameters are ignored. Additional information, like
+flash size, are detected automatically.
+
+@example
+flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME
+@end example
+
+@end deffn
+
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
since all devices in this family have the same memory layout.
@example
-flash bank aduc702x 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME
@end example
@end deffn
+@anchor{at91sam3}
@deffn {Flash Driver} at91sam3
@cindex at91sam3
All members of the AT91SAM3 microcontroller family from
@example
# Flash bank 0 - all chips
-flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
+flash bank $_FLASHNAME at91sam3 0x00080000 0 1 1 $_TARGETNAME
# Flash bank 1 - only 256K chips
-flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
+flash bank $_FLASHNAME at91sam3 0x00100000 0 1 1 $_TARGETNAME
@end example
Internally, the AT91SAM3 flash memory is organized as follows.
@end deffn
@end deffn
+@deffn {Flash Driver} at91sam4
+@cindex at91sam4
+All members of the AT91SAM4 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M4 core.
+This driver uses the same cmd names/syntax as @xref{at91sam3}.
+@end deffn
+
@deffn {Flash Driver} at91sam7
All members of the AT91SAM7 microcontroller family from Atmel include
internal flash and use ARM7TDMI cores. The driver automatically
register, and autoconfigures itself.
@example
-flash bank at91sam7 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME at91sam7 0 0 0 0 $_TARGETNAME
@end example
For chips which are not recognized by the controller driver, you must
@command{flash erase_sector} or @command{flash erase_address} commands.
@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
are not truly general purpose).
@comment - defines mass_erase ... pointless given flash_erase_address
@end deffn
-@deffn {Flash Driver} ecosflash
-@emph{No idea what this is...}
-The @var{ecosflash} driver defines one mandatory parameter,
-the name of a modules of target code which is downloaded
-and executed.
+@deffn {Flash Driver} efm32
+All members of the EFM32 microcontroller family from Energy Micro include
+internal flash and use ARM Cortex M3 cores. The driver automatically recognizes
+a number of these chips using the chip identification register, and
+autoconfigures itself.
+@example
+flash bank $_FLASHNAME efm32 0 0 0 0 $_TARGETNAME
+@end example
+@emph{The current implementation is incomplete. Unprotecting flash pages is not
+supported.}
@end deffn
@deffn {Flash Driver} lpc2000
@itemize
@item @var{variant} ... required, may be
-@var{lpc2000_v1} (older LPC21xx and LPC22xx)
-@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
-or @var{lpc1700} (LPC175x and LPC176x)
+@option{lpc2000_v1} (older LPC21xx and LPC22xx)
+@option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+or @option{lpc1700} (LPC175x and LPC176x)
@item @var{clock_kHz} ... the frequency, in kiloHertz,
at which the core is running
-@item @var{calc_checksum} ... optional (but you probably want to provide this!),
+@item @option{calc_checksum} ... optional (but you probably want to provide this!),
telling the driver to calculate a valid checksum for the exception vector table.
+@quotation Note
+If you don't provide @option{calc_checksum} when you're writing the vector
+table, the boot ROM will almost certainly ignore your flash image.
+However, if you do provide it,
+with most tool chains @command{verify_image} will fail.
+@end quotation
@end itemize
LPC flashes don't require the chip and bus width to be specified.
@example
-flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
+flash bank $_FLASHNAME lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
lpc2000_v2 14765 calc_checksum
@end example
LPC flashes don't require the chip and bus width to be specified.
@example
-flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000
+flash bank $_FLASHNAME lpc288x 0 0 0 0 $_TARGETNAME 12000000
@end example
@end deffn
Example for a 125 MHz clock frequency:
@example
-flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
+flash bank $_FLASHNAME lpc2900 0 0 0 0 $_TARGETNAME 125000
@end example
Some @code{lpc2900}-specific commands are defined. In the following command list,
@emph{No idea what this is, other than using some arm7/arm9 core.}
@example
-flash bank ocl 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME ocl 0 0 0 0 $_TARGETNAME
@end example
@end deffn
@deffn {Flash Driver} pic32mx
The PIC32MX microcontrollers are based on the MIPS 4K cores,
and integrate flash memory.
-@emph{The current implementation is incomplete.}
@example
-flash bank pix32mx 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME pix32mx 0x1fc00000 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME pix32mx 0x1d000000 0 0 0 $_TARGETNAME
@end example
@comment numerous *disabled* commands are defined:
Programs the specified 32-bit @var{value} at the given @var{address}
in the specified chip @var{bank}.
@end deffn
+@deffn Command {pic32mx unlock} bank
+Unlock and erase specified chip @var{bank}.
+This will remove any Code Protection.
+@end deffn
@end deffn
@deffn {Flash Driver} stellaris
standard @command{flash erase_address} command.}
@example
-flash bank stellaris 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
@end example
@end deffn
-@deffn {Flash Driver} stm32x
-All members of the STM32 microcontroller family from ST Microelectronics
+@deffn Command {stellaris recover bank_id}
+Performs the @emph{Recovering a "Locked" Device} procedure to
+restore the flash specified by @var{bank_id} and its associated
+nonvolatile registers to their factory default values (erased).
+This is the only way to remove flash protection or re-enable
+debugging if that capability has been disabled.
+
+Note that the final "power cycle the chip" step in this procedure
+must be performed by hand, since OpenOCD can't do it.
+@quotation Warning
+if more than one Stellaris chip is connected, the procedure is
+applied to all of them.
+@end quotation
+@end deffn
+
+@deffn {Flash Driver} stm32f1x
+All members of the STM32f1x microcontroller family from ST Microelectronics
include internal flash and use ARM Cortex M3 cores.
The driver automatically recognizes a number of these chips using
the chip identification register, and autoconfigures itself.
@example
-flash bank stm32x 0 0 0 0 $_TARGETNAME
+flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
@end example
-Some stm32x-specific commands
-@footnote{Currently there is a @command{stm32x mass_erase} command.
+If you have a target with dual flash banks then define the second bank
+as per the following example.
+@example
+flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
+@end example
+
+Some stm32f1x-specific commands
+@footnote{Currently there is a @command{stm32f1x mass_erase} command.
That seems pointless since the same effect can be had using the
standard @command{flash erase_address} command.}
are defined:
-@deffn Command {stm32x lock} num
+@deffn Command {stm32f1x lock} num
Locks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x unlock} num
+@deffn Command {stm32f1x unlock} num
Unlocks the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_read} num
+@deffn Command {stm32f1x options_read} num
Read and display the stm32 option bytes written by
-the @command{stm32x options_write} command.
+the @command{stm32f1x options_write} command.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
+@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@end deffn
+@deffn {Flash Driver} stm32f2x
+All members of the STM32f2x microcontroller family from ST Microelectronics
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@end deffn
+
@deffn {Flash Driver} str7x
All members of the STR7 microcontroller family from ST Microelectronics
include internal flash and use ARM7TDMI cores.
which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
@example
-flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
+flash bank $_FLASHNAME str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
@deffn Command {str7x disable_jtag} bank
the @command{str9x flash_config} command prior to Flash programming.
@example
-flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
+flash bank $_FLASHNAME str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
str9x flash_config 0 4 2 0 0x80000
@end example
@end deffn
@end deffn
+@deffn {Flash Driver} virtual
+This is a special driver that maps a previously defined bank to another
+address. All bank settings will be copied from the master physical bank.
+
+The @var{virtual} driver defines one mandatory parameters,
+
+@itemize
+@item @var{master_bank} The bank that this virtual address refers to.
+@end itemize
+
+So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to
+the flash bank defined at address 0x1fc00000. Any cmds executed on
+the virtual banks are actually performed on the physical banks.
+@example
+flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
+flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME
+flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} fm3
+All members of the FM3 microcontroller family from Fujitsu
+include internal flash and use ARM Cortex M3 cores.
+The @var{fm3} driver uses the @var{target} parameter to select the
+correct bank config, it can currently be one of the following:
+@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu},
+@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}.
+
+@example
+flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
@subsection str9xpec driver
@cindex str9xpec
Example for s3c2440 mflash where @var{RST pin} is GPIO B1:
@example
-mflash bank s3c2440 0x10000000 1b 0
+mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0
@end example
Example for pxa270 mflash where @var{RST pin} is GPIO 43:
@example
-mflash bank pxa270 0x08000000 43 0
+mflash bank $_FLASHNAME pxa270 0x08000000 43 0
@end example
@end deffn
plus some additional configuration that's done after
OpenOCD has initialized.
-@deffn {Config Command} {nand device} name controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
Declares a NAND device, which can be read and written to
after it has been configured through @command{nand probe}.
In OpenOCD, devices are single chips; this is unlike some
@itemize @bullet
@item @var{name} ... may be used to reference the NAND bank
-in other commands.
-@item @var{controller} ... identifies the controller driver
+in most other NAND commands. A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@section Other NAND commands
@cindex NAND other commands
-@deffn Command {nand check_bad_blocks} [offset length]
+@deffn Command {nand check_bad_blocks} num [offset length]
Checks for manufacturer bad block markers on the specified NAND
device. If no parameters are provided, checks the whole
device; otherwise, starts at the specified @var{offset} and
@end deffn
@comment current lpc3180 code won't issue 5-byte address cycles
+@deffn {NAND Driver} mx3
+This driver handles the NAND controller in i.MX31. The mxc driver
+should work for this chip aswell.
+@end deffn
+
+@deffn {NAND Driver} mxc
+This driver handles the NAND controller found in Freescale i.MX
+chips. It has support for v1 (i.MX27 and i.MX31) and v2 (i.MX35).
+The driver takes 3 extra arguments, chip (@option{mx27},
+@option{mx31}, @option{mx35}), ecc (@option{noecc}, @option{hwecc})
+and optionally if bad block information should be swapped between
+main area and spare area (@option{biswap}), defaults to off.
+@example
+nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
+@end example
+@deffn Command {mxc biswap} bank_num [enable|disable]
+Turns on/off bad block information swaping from main area,
+without parameter query status.
+@end deffn
+@end deffn
+
@deffn {NAND Driver} orion
These controllers require an extra @command{nand device}
parameter: the address of the controller.
@deffnx {NAND Driver} s3c2412
@deffnx {NAND Driver} s3c2440
@deffnx {NAND Driver} s3c2443
-These S3C24xx family controllers don't have any special
+@deffnx {NAND Driver} s3c6400
+These S3C family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
At this writing, their drivers don't include @code{write_page}
Exits the current telnet session.
@end deffn
-@c note EXTREMELY ANNOYING word wrap at column 75
-@c even when lines are e.g. 100+ columns ...
-@c coded in startup.tcl
@deffn {Command} help [string]
With no parameters, prints help text for all commands.
Otherwise, prints each helptext containing @var{string}.
Not every command provides helptext.
+
+Configuration commands, and commands valid at any time, are
+explicitly noted in parenthesis.
+In most cases, no such restriction is listed; this indicates commands
+which are only available after the configuration stage has completed.
@end deffn
@deffn Command sleep msec [@option{busy}]
@xref{Running}.
@end deffn
-@deffn Command fast (@option{enable}|@option{disable})
-Default disabled.
-Set default behaviour of OpenOCD to be "fast and dangerous".
-
-At this writing, this only affects the defaults for two ARM7/ARM9 parameters:
-fast memory access, and DCC downloads. Those parameters may still be
-individually overridden.
-
-The target specific "dangerous" optimisation tweaking options may come and go
-as more robust and user friendly ways are found to ensure maximum throughput
-and robustness with a minimum of configuration.
-
-Typically the "fast enable" is specified first on the command line:
-
-@example
-openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
-@end example
-@end deffn
-
-@deffn Command echo message
+@deffn Command echo [-n] message
Logs a message at "user" priority.
Output @var{message} to stdout.
+Option "-n" suppresses trailing newline.
@example
echo "Downloading kernel -- please wait"
@end example
the initial log output channel is stderr.
@end deffn
+@deffn Command add_script_search_dir [directory]
+Add @var{directory} to the file/script search path.
+@end deffn
+
@anchor{Target State handling}
@section Target State handling
@cindex reset
current target. Must be preceeded by fast_load_image.
@end deffn
-@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
+@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
Normally you should be using @command{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
@end deffn
@anchor{load_image}
-@deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
-Load image from file @var{filename} to target memory at @var{address}.
+@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}]
+Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
-(@option{bin}, @option{ihex}, or @option{elf})
+(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
+In addition the following arguments may be specifed:
+@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address})
+@var{max_length} - maximum number of bytes to load.
+@example
+proc load_image_bin @{fname foffset address length @} @{
+ # Load data from fname filename at foffset offset to
+ # target at address. Load at most length bytes.
+ load_image $fname [expr $address - $foffset] bin $address $length
+@}
+@end example
@end deffn
@deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
core mode if necessary.
@end deffn
+@deffn Command {arm semihosting} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Display status of semihosting, after optionally changing that status.
+
+Semihosting allows for code executing on an ARM target to use the
+I/O facilities on the host computer i.e. the system where OpenOCD
+is running. The target application must be linked against a library
+implementing the ARM semihosting convention that forwards operation
+requests by using a special SVC instruction that is trapped at the
+Supervisor Call vector by OpenOCD.
+@end deffn
+
@section ARMv4 and ARMv5 Architecture
@cindex ARMv4
@cindex ARMv5
They are available in addition to the ARM commands,
and any other core-specific commands that may be available.
-@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
-Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
-instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+@deffn Command {arm7_9 dbgrq} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of the
+the EmbeddedIce DBGRQ signal to force entry into debug mode,
+instead of breakpoints.
+If a boolean parameter is provided, first assigns that flag.
+
+This should be
+safe for all but ARM7TDMI-S cores (like NXP LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
-@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
+@deffn Command {arm7_9 dcc_downloads} [@option{enable}|@option{disable}]
@cindex DCC
-Control the use of the debug communications channel (DCC) to write larger (>128 byte)
-amounts of memory. DCC downloads offer a huge speed increase, but might be
+Displays the value of the flag controlling use of the debug communications
+channel (DCC) to write larger (>128 byte) amounts of memory.
+If a boolean parameter is provided, first assigns that flag.
+
+DCC downloads offer a huge speed increase, but might be
unsafe, especially with targets running at very low speeds. This command was introduced
with OpenOCD rev. 60, and requires a few bytes of working area.
@end deffn
@anchor{arm7_9 fast_memory_access}
-@deffn Command {arm7_9 fast_memory_access} (@option{enable}|@option{disable})
-Enable or disable memory writes and reads that don't check completion of
-the operation. This provides a huge speed increase, especially with USB JTAG
+@deffn Command {arm7_9 fast_memory_access} [@option{enable}|@option{disable}]
+Displays the value of the flag controlling use of memory writes and reads
+that don't check completion of the operation.
+If a boolean parameter is provided, first assigns that flag.
+
+This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
-@deffn Command {arm7_9 semihosting} [@option{enable}|@option{disable}]
-@cindex ARM semihosting
-Display status of semihosting, after optionally changing that status.
-
-Semihosting allows for code executing on an ARM target to use the
-I/O facilities on the host computer i.e. the system where OpenOCD
-is running. The target application must be linked against a library
-implementing the ARM semihosting convention that forwards operation
-requests by using a special SVC instruction that is trapped at the
-Supervisor Call vector by OpenOCD.
-@end deffn
-
@subsection ARM720T specific commands
@cindex ARM720T
based on the ARM7TDMI-S integer core.
They are available in addition to the ARM and ARM7/ARM9 commands.
-@deffn Command {arm720t cp15} regnum [value]
-Display cp15 register @var{regnum};
+@deffn Command {arm720t cp15} opcode [value]
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Display cp15 register returned by the ARM instruction @var{opcode};
else if a @var{value} is provided, that value is written to that register.
+The @var{opcode} should be the value of either an MRC or MCR instruction.
@end deffn
@subsection ARM9 specific commands
@deffn Command {arm920t cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+This uses "physical access" and the register number is as
+shown in bits 38..33 of table 9-9 in the ARM920T TRM.
+(Not all registers can be written.)
@end deffn
@deffn Command {arm920t cp15i} opcode [value [address]]
-Interpreted access using cp15 @var{opcode}.
+@emph{DEPRECATED -- avoid using this.
+Use the @command{arm mrc} or @command{arm mcr} commands instead.}
+
+Interpreted access using ARM instruction @var{opcode}, which should
+be the value of either an MRC or MCR instruction
+(as shown tables 9-11, 9-12, and 9-13 in the ARM920T TRM).
If no @var{value} is provided, the result is displayed.
Else if that value is written using the specified @var{address},
-or using zero if no other address is not provided.
+or using zero if no other address is provided.
@end deffn
@deffn Command {arm920t read_cache} filename
@deffn Command {arm966e cp15} regnum [value]
Display cp15 register @var{regnum};
else if a @var{value} is provided, that value is written to that register.
+The six bit @var{regnum} values are bits 37..32 from table 7-2 of the
+ARM966E-S TRM.
+There is no current control over bits 31..30 from that table,
+as required for BIST support.
@end deffn
@subsection XScale specific commands
mini-IC is marked valid, which makes the CPU fetch all exception
handlers from the mini-IC, ignoring the code in RAM.
-OpenOCD currently does not sync the mini-IC entries with the RAM
-contents (which would fail anyway while the target is running), so
-the user must provide appropriate values using the @code{xscale
-vector_table} command.
+To address this situation, OpenOCD provides the @code{xscale
+vector_table} command, which allows the user to explicity write
+individual entries to either the high or low vector table stored in
+the mini-IC.
It is recommended to place a pc-relative indirect branch in the vector
table, and put the branch destination somewhere in memory. Doing so
.long real_fiq_handler
@end example
+Alternatively, you may choose to keep some or all of the mini-IC
+vector table entries synced with those written to memory by your
+system software. The mini-IC can not be modified while the processor
+is executing, but for each vector table entry not previously defined
+using the @code{xscale vector_table} command, OpenOCD will copy the
+value from memory to the mini-IC every time execution resumes from a
+halt. This is done for both high and low vector tables (although the
+table not in use may not be mapped to valid memory, and in this case
+that copy operation will silently fail). This means that you will
+need to briefly halt execution at some strategic point during system
+start-up; e.g., after the software has initialized the vector table,
+but before exceptions are enabled. A breakpoint can be used to
+accomplish this once the appropriate location in the start-up code has
+been identified. A watchpoint over the vector table region is helpful
+in finding the location if you're not sure. Note that the same
+situation exists any time the vector table is modified by the system
+software.
+
The debug handler must be placed somewhere in the address space using
the @code{xscale debug_handler} command. The allowed locations for the
debug handler are either (0x800 - 0x1fef800) or (0xfe000800 -
0xfffff800). The default value is 0xfe000800.
+XScale has resources to support two hardware breakpoints and two
+watchpoints. However, the following restrictions on watchpoint
+functionality apply: (1) the value and mask arguments to the @code{wp}
+command are not supported, (2) the watchpoint length must be a
+power of two and not less than four, and can not be greater than the
+watchpoint address, and (3) a watchpoint with a length greater than
+four consumes all the watchpoint hardware resources. This means that
+at any one time, you can have enabled either two watchpoints with a
+length of four, or one watchpoint with a length greater than four.
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
Changes the address used for the specified target's debug handler.
@end deffn
-@deffn Command {xscale dcache} (@option{enable}|@option{disable})
+@deffn Command {xscale dcache} [@option{enable}|@option{disable}]
Enables or disable the CPU's data cache.
@end deffn
Dumps the raw contents of the trace buffer to @file{filename}.
@end deffn
-@deffn Command {xscale icache} (@option{enable}|@option{disable})
+@deffn Command {xscale icache} [@option{enable}|@option{disable}]
Enables or disable the CPU's instruction cache.
@end deffn
-@deffn Command {xscale mmu} (@option{enable}|@option{disable})
+@deffn Command {xscale mmu} [@option{enable}|@option{disable}]
Enables or disable the CPU's memory management unit.
@end deffn
-@deffn Command {xscale trace_buffer} (@option{enable}|@option{disable}) [@option{fill} [n] | @option{wrap}]
-Enables or disables the trace buffer,
-and controls how it is emptied.
+@deffn Command {xscale trace_buffer} [@option{enable}|@option{disable} [@option{fill} [n] | @option{wrap}]]
+Displays the trace buffer status, after optionally
+enabling or disabling the trace buffer
+and modifying how it is emptied.
@end deffn
@deffn Command {xscale trace_image} filename [offset [type]]
@end deffn
@anchor{xscale vector_table}
-@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@deffn Command {xscale vector_table} [(@option{low}|@option{high}) index value]
@cindex vector_table
Set an entry in the mini-IC vector table. There are two tables: one for
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 memwrite burst} [value]
+@deffn Command {arm11 memwrite burst} [@option{enable}|@option{disable}]
Displays the value of the memwrite burst-enable flag,
-which is enabled by default. Burst writes are only used
-for memory writes larger than 1 word. Single word writes
-are likely to be from reset init scripts and those writes
-are often to non-memory locations which could easily have
-many wait states, which could easily break burst writes.
-If @var{value} is defined, first assigns that.
+which is enabled by default.
+If a boolean parameter is provided, first assigns that flag.
+Burst writes are only used for memory writes larger than 1 word.
+They improve performance by assuming that the CPU has read each data
+word over JTAG and completed its write before the next word arrives,
+instead of polling for a status flag to verify that completion.
+This is usually safe, because JTAG runs much slower than the CPU.
@end deffn
-@deffn Command {arm11 memwrite error_fatal} [value]
+@deffn Command {arm11 memwrite error_fatal} [@option{enable}|@option{disable}]
Displays the value of the memwrite error_fatal flag,
which is enabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that flag.
+When set, certain memory write errors cause earlier transfer termination.
@end deffn
-@deffn Command {arm11 step_irq_enable} [value]
+@deffn Command {arm11 step_irq_enable} [@option{enable}|@option{disable}]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
they are disabled by default.
-If @var{value} is defined, first assigns that.
+If a boolean parameter is provided, first assigns that.
@end deffn
@deffn Command {arm11 vcr} [value]
included on Cortex-M3 and Cortex-A8 systems.
They are available in addition to other core-specific commands that may be available.
-@deffn Command {dap info} [num]
-Displays dap info for ap @var{num}, defaulting to the currently selected AP.
+@deffn Command {dap apid} [num]
+Displays ID register from AP @var{num},
+defaulting to the currently selected AP.
@end deffn
@deffn Command {dap apsel} [num]
Select AP @var{num}, defaulting to 0.
@end deffn
-@deffn Command {dap apid} [num]
-Displays id register from AP @var{num},
+@deffn Command {dap baseaddr} [num]
+Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
-@deffn Command {dap baseaddr} [num]
-Displays debug base address from AP @var{num},
+@deffn Command {dap info} [num]
+Displays the ROM table for MEM-AP @var{num},
defaulting to the currently selected AP.
@end deffn
@deffn Command {dap memaccess} [value]
-Displays the number of extra tck for mem-ap memory bus access [0-255].
+Displays the number of extra tck cycles in the JTAG idle to use for MEM-AP
+memory bus access [0-255], giving additional time to respond to reads.
If @var{value} is defined, first assigns that.
@end deffn
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
-@deffn Command {cortex_m3 disassemble} address [count]
-@cindex disassemble
-Disassembles @var{count} Thumb2 instructions starting at @var{address}.
-If @var{count} is not specified, a single instruction is disassembled.
-@end deffn
-
-@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
+@deffn Command {cortex_m3 maskisr} (@option{auto}|@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
+
+The @option{auto} option handles interrupts during stepping a way they get
+served but don't disturb the program flow. The step command first allows
+pending interrupt handlers to execute, then disables interrupts and steps over
+the next instruction where the core was halted. After the step interrupts
+are enabled again. If the interrupt handlers don't complete within 500ms,
+the step command leaves with the core running.
+
+Note that a free breakpoint is required for the @option{auto} option. If no
+breakpoint is available at the time of the step, then the step is taken
+with interrupts enabled, i.e. the same way the @option{off} option does.
+
+Default is @option{auto}.
@end deffn
@deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list]
This finishes by listing the current vector catch configuration.
@end deffn
+@deffn Command {cortex_m3 reset_config} (@option{srst}|@option{sysresetreq}|@option{vectreset})
+Control reset handling. The default @option{srst} is to use srst if fitted,
+otherwise fallback to @option{vectreset}.
+@itemize @minus
+@item @option{srst} use hardware srst if fitted otherwise fallback to @option{vectreset}.
+@item @option{sysresetreq} use NVIC SYSRESETREQ to reset system.
+@item @option{vectreset} use NVIC VECTRESET to reset system.
+@end itemize
+Using @option{vectreset} is a safe option for all current Cortex-M3 cores.
+This however has the disadvantage of only resetting the core, all peripherals
+are uneffected. A solution would be to use a @code{reset-init} event handler to manually reset
+the peripherals.
+@xref{Target Events}.
+@end deffn
+
@anchor{Software Debug Messages and Tracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
If you're not debugging OpenOCD internals, or bringing up a
new JTAG adapter or a new type of TAP device (like a CPU or
JTAG router), you probably won't need to use these commands.
+In a debug session that doesn't use JTAG for its transport protocol,
+these commands are not available.
@deffn Command {drscan} tap [numbits value]+ [@option{-endstate} tap_state]
Loads the data register of @var{tap} with a series of bit fields
The Serial Vector Format, better known as @dfn{SVF}, is a
way to represent JTAG test patterns in text files.
+In a debug session using JTAG for its transport protocol,
OpenOCD supports running such test files.
@deffn Command {svf} filename [@option{quiet}]
The Xilinx Serial Vector Format, better known as @dfn{XSVF}, is a
binary representation of SVF which is optimized for use with
Xilinx devices.
+In a debug session using JTAG for its transport protocol,
OpenOCD supports running such test files.
@quotation Important
Setting up GDB to work with OpenOCD can involve several components:
@itemize
-@item OpenOCD itself may need to be configured. @xref{GDB Configuration}.
-@item GDB itself may need configuration, as shown in this chapter.
+@item The OpenOCD server support for GDB may need to be configured.
+@xref{GDB Configuration}.
+@item GDB's support for OpenOCD may need configuration,
+as shown in this chapter.
@item If you have a GUI environment like Eclipse,
that also will probably need to be configured.
@end itemize
target remote localhost:3333
@end example
This would cause GDB to connect to the gdbserver on the local pc using port 3333.
+
+It is also possible to use the GDB extended remote protocol as follows:
+@example
+target extended-remote localhost:3333
+@end example
@item
A pipe connection is typically started as follows:
@example
-target remote | openocd --pipe
+target remote | openocd -c "gdb_port pipe; log_output openocd.log"
@end example
This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
-session.
+session. log_output sends the log output to a file to ensure that the pipe is
+not saturated when using higher debug level outputs.
@end enumerate
To list the available OpenOCD commands type @command{monitor help} on the
only work for code running from flash memory. Most other ARM systems
do not have such restrictions.
+Another example of useful GDB configuration came from a user who
+found that single stepping his Cortex-M3 didn't work well with IRQs
+and an RTOS until he told GDB to disable the IRQs while stepping:
+
+@example
+define hook-step
+mon cortex_m3 maskisr on
+end
+define hookpost-step
+mon cortex_m3 maskisr off
+end
+@end example
+
+Rather than typing such commands interactively, you may prefer to
+save them in a file and have GDB execute them as it starts, perhaps
+using a @file{.gdbinit} in your project directory or starting GDB
+using @command{gdb -x filename}.
+
@section Programming using GDB
@cindex Programming using GDB
To verify any flash programming the GDB command @option{compare-sections}
can be used.
+@anchor{Using openocd SMP with GDB}
+@section Using openocd SMP with GDB
+@cindex SMP
+For SMP support following GDB serial protocol packet have been defined :
+@itemize @bullet
+@item j - smp status request
+@item J - smp set request
+@end itemize
+
+OpenOCD implements :
+@itemize @bullet
+@item @option{jc} packet for reading core id displayed by
+GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
+ @option{E01} for target not smp.
+@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
+(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
+for target not smp or @option{OK} on success.
+@end itemize
+
+Handling of this packet within GDB can be done :
+@itemize @bullet
+@item by the creation of an internal variable (i.e @option{_core}) by mean
+of function allocate_computed_value allowing following GDB command.
+@example
+set $_core 1
+#Jc01 packet is sent
+print $_core
+#jc packet is sent and result is affected in $
+@end example
+
+@item by the usage of GDB maintenance command as described in following example (2
+cpus in SMP with core id 0 and 1 @pxref{Define CPU targets working in SMP}).
+
+@example
+# toggle0 : force display of coreid 0
+define toggle0
+maint packet Jc0
+continue
+main packet Jc-1
+end
+# toggle1 : force display of coreid 1
+define toggle1
+maint packet Jc1
+continue
+main packet Jc-1
+end
+@end example
+@end itemize
+
@node Tcl Scripting API
@chapter Tcl Scripting API
is the low level API upon which @command{flash banks} is implemented.
@itemize @bullet
-@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+@item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
Read memory and return as a Tcl array for script processing
-@item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+@item @b{array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
Convert a Tcl array to memory locations and write the values
@item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
holds one of the following values:
@itemize @bullet
-@item @b{winxx} Built using Microsoft Visual Studio
-@item @b{linux} Linux is the underlying operating sytem
-@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
@item @b{cygwin} Running under Cygwin
+@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@item @b{freebsd} Running under FreeBSD
+@item @b{linux} Linux is the underlying operating sytem
@item @b{mingw32} Running under MingW32
+@item @b{winxx} Built using Microsoft Visual Studio
@item @b{other} Unknown, none of the above.
@end itemize
In digital circuit design it is often refered to as ``clock
synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
-operating at some speed, your target is operating at another. The two
-clocks are not synchronised, they are ``asynchronous''
+operating at some speed, your CPU target is operating at another.
+The two clocks are not synchronised, they are ``asynchronous''
-In order for the two to work together they must be synchronised. Otherwise
-the two systems will get out of sync with each other and nothing will
-work. There are 2 basic options:
+In order for the two to work together they must be synchronised
+well enough to work; JTAG can't go ten times faster than the CPU,
+for example. There are 2 basic options:
@enumerate
@item
-Use a special circuit.
+Use a special "adaptive clocking" circuit to change the JTAG
+clock rate to match what the CPU currently supports.
@item
-One clock must be some multiple slower than the other.
+The JTAG clock must be fixed at some speed that's enough slower than
+the CPU clock that all TMS and TDI transitions can be detected.
@end enumerate
@b{Does this really matter?} For some chips and some situations, this
-is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some
-Atmel SAM7 and SAM9 chips start operation from reset at 32kHz -
-program/enable the oscillators and eventually the main clock. It is in
-those critical times you must slow the JTAG clock to sometimes 1 to
-4kHz.
-
-Imagine debugging a 500MHz ARM926 hand held battery powered device
-that ``deep sleeps'' at 32kHz between every keystroke. It can be
-painful.
+is a non-issue, like a 500MHz ARM926 with a 5 MHz JTAG link;
+the CPU has no difficulty keeping up with JTAG.
+Startup sequences are often problematic though, as are other
+situations where the CPU clock rate changes (perhaps to save
+power).
+
+For example, Atmel AT91SAM chips start operation from reset with
+a 32kHz system clock. Boot firmware may activate the main oscillator
+and PLL before switching to a faster clock (perhaps that 500 MHz
+ARM926 scenario).
+If you're using JTAG to debug that startup sequence, you must slow
+the JTAG clock to sometimes 1 to 4kHz. After startup completes,
+JTAG can use a faster clock.
+
+Consider also debugging a 500MHz ARM926 hand held battery powered
+device that enters a low power ``deep sleep'' mode, at 32kHz CPU
+clock, between keystrokes unless it has work to do. When would
+that 5 MHz JTAG clock be usable?
@b{Solution #1 - A special circuit}
-In order to make use of this, your JTAG dongle must support the RTCK
-feature. Not all dongles support this - keep reading!
+In order to make use of this,
+your CPU, board, and JTAG adapter must all support the RTCK
+feature. Not all of them support this; keep reading!
-The RTCK signal often found in some ARM chips is used to help with
+The RTCK ("Return TCK") signal in some ARM chips is used to help with
this problem. ARM has a good description of the problem described at
this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked
28/nov/2008]. Link title: ``How does the JTAG synchronisation logic
ARM11 cores use an 8:1 division.
@b{Xilinx rule of thumb} is 1/12 the clock speed.
-Note: Many FTDI2232C based JTAG dongles are limited to 6MHz.
+Note: most full speed FT2232 based JTAG adapters are limited to a
+maximum of 6MHz. The ones using USB high speed chips (FT2232H)
+often support faster clock rates (and adaptive clocking).
You can still debug the 'low power' situations - you just need to
-manually adjust the clock speed at every step. While painful and
-tedious, it is not always practical.
+either use a fixed and very slow JTAG clock rate ... or else
+manually adjust the clock speed at every step. (Adjusting is painful
+and tedious, and is not always practical.)
It is however easy to ``code your way around it'' - i.e.: Cheat a little,
have a special debug mode in your application that does a ``high power
@example
# Example: 1.234MHz
-jtag_khz 1234
+adapter_khz 1234
@end example
@item @b{LPC2000 Flash} In the configuration file in the section where flash device configurations
are described, there is a parameter for specifying the clock frequency
-for LPC2000 internal flash devices (e.g. @option{flash bank lpc2000
-0x0 0x40000 0 0 0 lpc2000_v1 14746 calc_checksum}), which must be
+for LPC2000 internal flash devices (e.g. @option{flash bank $_FLASHNAME lpc2000
+0x0 0x40000 0 0 $_TARGETNAME lpc2000_v1 14746 calc_checksum}), which must be
specified in kilohertz. However, I do have a quartz crystal of a
frequency that contains fractions of kilohertz (e.g. 14,745,600 Hz,
i.e. 14,745.600 kHz). Is it possible to specify real numbers for the
how the Tcl scripts work.
This chapter is written with two audiences in mind. (1) OpenOCD users
-who need to understand a bit more of how JIM-Tcl works so they can do
+who need to understand a bit more of how Jim-Tcl works so they can do
something useful, and (2) those that want to add a new command to
OpenOCD.
@* Example: @b{ source [find FILENAME] }
@*Remember the parsing rules
@enumerate
-@item The FIND command is in square brackets.
-@* The FIND command is executed with the parameter FILENAME. It should
-find the full path to the named file. The RESULT is a string, which is
-substituted on the orginal command line.
-@item The command source is executed with the resulting filename.
-@* SOURCE reads a file and executes as a script.
+@item The @command{find} command is in square brackets,
+and is executed with the parameter FILENAME. It should find and return
+the full path to a file with that name; it uses an internal search path.
+The RESULT is a string, which is substituted into the command line in
+place of the bracketed @command{find} command.
+(Don't try to use a FILENAME which includes the "#" character.
+That character begins Tcl comments.)
+@item The @command{source} command is executed with the resulting filename;
+it reads a file and executes as a script.
@end enumerate
@subsection format command
@b{Where:} Generally occurs in numerous places.
Code Review / openocd.git / blobdiff