@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-2010 David Brownell
@end itemize
@menu
* About:: About OpenOCD
* Developers:: OpenOCD Developer Resources
-* JTAG Hardware Dongles:: JTAG Hardware Dongles
-* About JIM-Tcl:: About JIM-Tcl
+* 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
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:
available. A version for more recent code may be available.
Its HTML form is published irregularly 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
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.txt} file contains basic information about how
+The @file{HACKING} file contains basic information about how
to prepare patches.
@section OpenOCD 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}
@* See: @url{http://www.luminarymicro.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.
+These boards can also be used in a "pass through" mode 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
+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 Other
@itemize @bullet
@item @b{USBprog}
@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/}
@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 directory search
Properly installing OpenOCD sets up your operating system to grant it access
-to the JTAG adapters. On Linux, this usually involves installing a file
+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.
--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
If you don't give any @option{-f} or @option{-c} options,
@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}.
@quotation Note
Don't try to use configuration script names or paths which
-include the "#" character. That character begins Tcl comments.
+include the "#" character. That character begins Tcl comments.
@end quotation
@section Simple setup, no customization
@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
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
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
+at91sam9260.cfg lpc2129.cfg stm32f1x.cfg
c100.cfg lpc2148.cfg str710.cfg
c100config.tcl lpc2294.cfg str730.cfg
c100helper.tcl lpc2378.cfg str750.cfg
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.
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
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
@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, GDB remote access ports are not activated.
@end deffn
@deffn {Command} tcl_port [number]
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]
@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
Correctly installing OpenOCD includes making your operating system give
-OpenOCD access to JTAG adapters. Once that has been done, Tcl commands
+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.
-JTAG Adapters/Interfaces/Dongles are normally configured
+@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
@end example
@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
@deffn {Interface Driver} {jlink}
Segger jlink USB adapter
-@c command: jlink_info
+@c command: jlink caps
+@c dumps jlink capabilities
+@c command: jlink config
+@c access J-Link configurationif no argument this will dump the config
+@c command: jlink config kickstart [val]
+@c set Kickstart power on JTAG-pin 19.
+@c command: jlink config mac_address [ff:ff:ff:ff:ff:ff]
+@c set the MAC Address
+@c command: jlink config ip [A.B.C.D[/E] [F.G.H.I]]
+@c set the ip address of the J-Link Pro, "
+@c where A.B.C.D is the ip,
+@c E the bit of the subnet mask
+@c F.G.H.I the subnet mask
+@c command: jlink config reset
+@c reset the current config
+@c command: jlink config save
+@c save the current config
+@c command: jlink config usb_address [0x00 to 0x03 or 0xff]
+@c set the USB-Address,
+@c This will change the product id
+@c command: jlink info
@c dumps status
-@c command: jlink_hw_jtag (2|3)
+@c command: jlink hw_jtag (2|3)
@c sets version 2 or 3
+@c command: jlink pid
+@c set the pid of the interface we want to use
@end deffn
@deffn {Interface Driver} {parport}
@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
@end quotation
@end deffn
+@deffn {Interface Driver} {stlink}
+ST Micro ST-LINK adapter.
+@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}, but only for (ARM) cores and boards
+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
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:
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
@* Currently not used (goal: when JTAG examine starts)
@end ignore
@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 @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}
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {flash erase_address} [@option{pad}] 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.
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
@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, which may be
-incorrect (outdated) unless you first issue a
-@command{flash protect_check num} command.
+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.
-This updates the protection information displayed by @option{flash info}.
-(Code execution may have invalidated any state records kept by OpenOCD.)
-@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} 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
@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.
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
@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.
-@end deffn
-
@deffn {Flash Driver} lpc2000
Most members of the LPC1700 and LPC2000 microcontroller families from NXP
include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
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
@end quotation
@end deffn
-@deffn {Flash Driver} stm32x
-All members of the STM32 microcontroller family from ST Microelectronics
+@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
+
+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 stm32x-specific commands
-@footnote{Currently there is a @command{stm32x mass_erase} command.
+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
@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.
@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
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
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.
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
-@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
@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
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} ...]
@b{Solution #1 - A special circuit}
In order to make use of this,
-both your CPU and your JTAG dongle must support the RTCK
-feature. Not all dongles support this - keep reading!
+your CPU, board, and JTAG adapter must all support the RTCK
+feature. Not all of them support this; keep reading!
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
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
either use a fixed and very slow JTAG clock rate ... or else
@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.
Code Review / openocd.git / blobdiff