@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 Duane Ellis @email{openocd@@duaneellis.com}
+@item Copyright @copyright{} 2009 David Brownell
@end itemize
@quotation
* Developers:: OpenOCD Developers
* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
+* About JIM-Tcl:: About JIM-Tcl
* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
-* About JIM-Tcl:: About JIM-Tcl
* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
+* Boundary Scan Commands:: Boundary Scan Commands
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
+internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
+@item @b{luminary_icdi}
+@* See: @url{http://www.luminarymicro.com} - Luminary In-Circuit Debug Interface (ICDI) Board, included in the Stellaris LM3S9B90 and LM3S9B92 Evaluation Kits.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@end itemize
+@node About JIM-Tcl
+@chapter About JIM-Tcl
+@cindex JIM Tcl
+@cindex tcl
+
+OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
+This programming language provides a simple and extensible
+command interpreter.
+
+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}.
+
+@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
+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.
+
+@item @b{Scripts}
+@* 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.
+
+@item @b{Commands}
+@* At the OpenOCD telnet command line (or via the GDB mon 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.
+
+@item @b{Need a crash course in Tcl?}
+@*@xref{Tcl Crash Course}.
+@end itemize
+
@node Running
@chapter Running
@cindex command line options
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
-Also it is possible to interleave 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
A simple way to organize them all involves keeping a
single directory for your work with a given board.
When you start OpenOCD from that directory,
-it searches there first for configuration files
+it searches there first for configuration files, scripts,
and for code you upload to the target board.
-It is also be the natural place to write files,
+It is also the natural place to write files,
such as log files and data you download from the board.
@section Configuration Basics
You could wrap such long command lines in shell scripts,
each supporting a different development task.
-One might re-flash the board with specific firmware version.
+One might re-flash the board with a specific firmware version.
Another might set up a particular debugging or run-time environment.
Here we will focus on the simpler solution: one user config
Likewise, the @command{arm9tdmi vector_catch} command (or
its @command{xscale vector_catch} sibling) can be a timesaver
during some debug sessions, but don't make everyone use that either.
-Keep those kinds of debugging aids in your user config file.
+Keep those kinds of debugging aids in your user config file,
+along with messaging and tracing setup.
+(@xref{Software Debug Messages and Tracing}.)
+
+TCP/IP port configuration is another example of something which
+is environment-specific, and should only appear in
+a user config file. @xref{TCP/IP Ports}.
@section Project-Specific Utilities
needs to get a new board working smoothly.
It provides guidelines for creating those files.
-You should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
+You should find the following directories under @t{$(INSTALLDIR)/scripts}:
@itemize @bullet
-@item @b{interface}
-@*Think JTAG Dongle. Files that configure the JTAG dongle go here.
-@item @b{board}
-@* Think Circuit Board, PWA, PCB, they go by many names. Board files
-contain initialization items that are specific to a board - for
-example: The SDRAM initialization sequence for the board, or the type
-of external flash and what address it is found at. Any initialization
+@item @file{interface} ...
+think JTAG Dongle. Files that configure JTAG adapters go here.
+@item @file{board} ...
+think Circuit Board, PWA, PCB, they go by many names. Board files
+contain initialization items that are specific to a board. For
+example, the SDRAM initialization sequence for the board, or the type
+of external flash and what address it uses. Any initialization
sequence to enable that external flash or SDRAM should be found in the
-board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
+board file. Boards may also contain multiple targets: two CPUs; or
a CPU and an FPGA or CPLD.
-@item @b{target}
-@* Think chip. The ``target'' directory represents the JTAG TAPs
+@item @file{target} ...
+think chip. The ``target'' directory represents the JTAG TAPs
on a chip
which OpenOCD should control, not a board. Two common types of targets
are ARM chips and FPGA or CPLD chips.
@section Interface Config Files
The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
@example
source [find interface/FOOBAR.cfg]
Read the OpenOCD source code if you have a new kind of hardware interface
and need to provide a driver for it.
-Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
-
@section Board Config Files
@cindex config file, board
@cindex board config file
The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
@example
source [find board/FOOBAR.cfg]
@end example
-The board config file should contain one or more @command{source [find
-target/FOO.cfg]} statements along with any board specific things.
-
+The point of a board config file is to package everything
+about a given board that user config files need to know.
In summary the board files should contain (if present)
@enumerate
-@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
-@item SDRAM configuration (size, speed, etc.
-@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
-@item Multiple TARGET source statements
-@item Reset configuration
+@item One or more @command{source [target/...cfg]} statements
+@item NOR flash configuration (@pxref{NOR Configuration})
+@item NAND flash configuration (@pxref{NAND Configuration})
+@item Target @code{reset} handlers for SDRAM and I/O configuration
+@item JTAG adapter reset configuration (@pxref{Reset Configuration})
@item All things that are not ``inside a chip''
-@item Things inside a chip go in a 'target' file
@end enumerate
-@section Target Config Files
-@cindex config file, target
-@cindex target config file
+Generic things inside target chips belong in target config files,
+not board config files. So for example a @code{reset-init} event
+handler should know board-specific oscillator and PLL parameters,
+which it passes to target-specific utility code.
+
+The most complex task of a board config file is creating such a
+@code{reset-init} event handler.
+Define those handlers last, after you verify the rest of the board
+configuration works.
+
+@subsection Communication Between Config files
+
+In addition to target-specific utility code, another way that
+board and target config files communicate is by following a
+convention on how to use certain variables.
-Board config files should be able to source one or more
-target config files via a command like this:
+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.
+
+Complex board config files can do the things like this,
+for a board with three chips:
@example
-source [find target/FOOBAR.cfg]
+# Chip #1: PXA270 for network side, big endian
+set CHIPNAME network
+set ENDIAN big
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = network.cpu
+# other commands can refer to the "network.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #2: PXA270 for video side, little endian
+set CHIPNAME video
+set ENDIAN little
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = video.cpu
+# other commands can refer to the "video.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #3: Xilinx FPGA for glue logic
+set CHIPNAME xilinx
+unset ENDIAN
+source [find target/spartan3.cfg]
@end example
-In summary the target files should contain
+That example is oversimplified because it doesn't show any flash memory,
+or the @code{reset-init} event handlers to initialize external DRAM
+or (assuming it needs it) load a configuration into the FPGA.
+Such features are usually needed for low-level work with many boards,
+where ``low level'' implies that the board initialization software may
+not be working. (That's a common reason to need JTAG tools. Another
+is to enable working with microcontroller-based systems, which often
+have no debugging support except a JTAG connector.)
-@enumerate
-@item Set defaults
-@item Add TAPs to the scan chain
-@item Add CPU targets (includes GDB support)
-@item CPU/Chip/CPU-Core specific features
-@item On-Chip flash
-@end enumerate
-
-As a rule of thumb, a target file sets up only one chip.
-For a microcontroller, that will often include a single TAP,
-which is a CPU needing a GDB target; and its on-chip flash.
+Target config files may also export utility functions to board and user
+config files. Such functions should use name prefixes, to help avoid
+naming collisions.
-More complex chips may include multiple TAPs, and the target
-config file may need to define them all before OpenOCD
-can talk to the chip.
-For example, some phone chips have JTAG scan chains that include
-an ARM core for operating system use, a DSP,
-another ARM core embedded in an image processing engine,
-and other processing engines.
+Board files could also accept input variables from user config files.
+For example, there might be a @code{J4_JUMPER} setting used to identify
+what kind of flash memory a development board is using, or how to set
+up other clocks and peripherals.
-@subsection Important variable names
+@subsection Variable Naming Convention
+@cindex variable names
-Most boards will have only one instance of a chip.
+Most boards have only one instance of a chip.
However, it should be easy to create a board with more than
-one such chip.
-Accordingly, we encourage some conventions for naming
-variables associated with different TAPs, to promote
-consistency and
-so that board files can override target defaults, and
+one such chip (as shown above).
+Accordingly, we encourage these conventions for naming
+variables associated with different @file{target.cfg} files,
+to promote consistency and
+so that board files can override target defaults.
+
+Inputs to target config files include:
@itemize @bullet
-@item @b{CHIPNAME}
-@* This gives a name to the overall chip, and is used as part of the
-tap identifier dotted name.
-It's normally provided by the chip manufacturer.
-@item @b{ENDIAN}
-@* By default little - unless the chip or board is not normally used that way.
+@item @code{CHIPNAME} ...
+This gives a name to the overall chip, and is used as part of
+tap identifier dotted names.
+While the default is normally provided by the chip manufacturer,
+board files may need to distinguish between instances of a chip.
+@item @code{ENDIAN} ...
+By default @option{little} - although chips may hard-wire @option{big}.
Chips that can't change endianness don't need to use this variable.
-@item @b{CPUTAPID}
-@* When OpenOCD examines the JTAG chain, it will attempt to identify
-every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
-to verify the tap id number verses configuration file and may issue an
-error or warning like this. The hope is that this will help to pinpoint
-problems in OpenOCD configurations.
+@item @code{CPUTAPID} ...
+When OpenOCD examines the JTAG chain, it can be told verify the
+chips against the JTAG IDCODE register.
+The target file will hold one or more defaults, but sometimes the
+chip in a board will use a different ID (perhaps a newer revision).
+@end itemize
-@example
-Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
- (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
-Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678,
- Got: 0x3f0f0f0f
-Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
-Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
-@end example
+Outputs from target config files include:
-@item @b{_TARGETNAME}
-@* By convention, this variable is created by the target configuration
+@itemize @bullet
+@item @code{_TARGETNAME} ...
+By convention, this variable is created by the target configuration
script. The board configuration file may make use of this variable to
configure things like a ``reset init'' script, or other things
specific to that board and that target.
+If the chip has 2 targets, the names are @code{_TARGETNAME0},
+@code{_TARGETNAME1}, ... etc.
+@end itemize
-If the chip has 2 targets, use the names @b{_TARGETNAME0},
-@b{_TARGETNAME1}, ... etc.
+@subsection The reset-init Event Handler
+@cindex event, reset-init
+@cindex reset-init handler
-@emph{Remember:} The ``board file'' may include multiple targets.
-The user (or board) config file should reasonably be able to:
+Board config files run in the OpenOCD configuration stage;
+they can't use TAPs or targets, since they haven't been
+fully set up yet.
+This means you can't write memory or access chip registers;
+you can't even verify that a flash chip is present.
+That's done later in event handlers, of which the target @code{reset-init}
+handler is one of the most important.
-@example
-source [find target/FOO.cfg]
-$_TARGETNAME configure ... FOO specific parameters
+Except on microcontrollers, the basic job of @code{reset-init} event
+handlers is setting up flash and DRAM, as normally handled by boot loaders.
+Microcontrollers rarely use boot loaders; they run right out of their
+on-chip flash and SRAM memory. But they may want to use one of these
+handlers too, if just for developer convenience.
-source [find target/BAR.cfg]
-$_TARGETNAME configure ... BAR specific parameters
-@end example
-
-@end itemize
+@quotation Note
+Because this is so very board-specific, and chip-specific, no examples
+are included here.
+Instead, look at the board config files distributed with OpenOCD.
+If you have a boot loader, its source code may also be useful.
+@end quotation
-@subsection Tcl Variables Guide Line
-The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
+Some of this code could probably be shared between different boards.
+For example, setting up a DRAM controller often doesn't differ by
+much except the bus width (16 bits or 32?) and memory timings, so a
+reusable TCL procedure loaded by the @file{target.cfg} file might take
+those as parameters.
+Similarly with oscillator, PLL, and clock setup;
+and disabling the watchdog.
+Structure the code cleanly, and provide comments to help
+the next developer doing such work.
+(@emph{You might be that next person} trying to reuse init code!)
+
+The last thing normally done in a @code{reset-init} handler is probing
+whatever flash memory was configured. For most chips that needs to be
+done while the associated target is halted, either because JTAG memory
+access uses the CPU or to prevent conflicting CPU access.
+
+@subsection JTAG Clock Rate
+
+Before your @code{reset-init} handler has set up
+the PLLs and clocking, you may need to use
+a low JTAG clock rate; then you'd increase it later.
+(The rule of thumb for ARM-based processors is 1/8 the CPU clock.)
+If the board supports 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}.
+Set the slow rate at the beginning of the reset sequence,
+and the faster rate as soon as the clocks are at full speed.
-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.
+@section Target Config Files
+@cindex config file, target
+@cindex target config file
-@b{EXAMPLE:} The user config file should be able to do this:
+Board config files communicate with target config files using
+naming conventions as described above, and may source one or
+more target config files like this:
@example
- # Board has 3 chips,
- # PXA270 #1 network side, big endian
- # PXA270 #2 video side, little endian
- # Xilinx Glue logic
- set CHIPNAME network
- set ENDIAN big
- source [find target/pxa270.cfg]
- # variable: _TARGETNAME = network.cpu
- # other commands can refer to the "network.cpu" tap.
- $_TARGETNAME configure .... params for this CPU..
-
- set ENDIAN little
- set CHIPNAME video
- source [find target/pxa270.cfg]
- # variable: _TARGETNAME = video.cpu
- # other commands can refer to the "video.cpu" tap.
- $_TARGETNAME configure .... params for this CPU..
-
- unset ENDIAN
- set CHIPNAME xilinx
- source [find target/spartan3.cfg]
-
- # Since $_TARGETNAME is temporal..
- # these names still work!
- network.cpu configure ... params
- video.cpu configure ... params
+source [find target/FOOBAR.cfg]
@end example
+The point of a target config file is to package everything
+about a given chip that board config files need to know.
+In summary the target files should contain
+
+@enumerate
+@item Set defaults
+@item Add TAPs to the scan chain
+@item Add CPU targets (includes GDB support)
+@item CPU/Chip/CPU-Core specific features
+@item On-Chip flash
+@end enumerate
+
+As a rule of thumb, a target file sets up only one chip.
+For a microcontroller, that will often include a single TAP,
+which is a CPU needing a GDB target, and its on-chip flash.
+
+More complex chips may include multiple TAPs, and the target
+config file may need to define them all before OpenOCD
+can talk to the chip.
+For example, some phone chips have JTAG scan chains that include
+an ARM core for operating system use, a DSP,
+another ARM core embedded in an image processing engine,
+and other processing engines.
+
@subsection Default Value Boiler Plate Code
-All target configuration files should start with this (or a modified form)
+All target configuration files should start with code like this,
+letting board config files express environment-specific
+differences in how things should be set up.
@example
-# SIMPLE example
+# Boards may override chip names, perhaps based on role,
+# but the default should match what the vendor uses
if @{ [info exists CHIPNAME] @} @{
set _CHIPNAME $CHIPNAME
@} else @{
set _CHIPNAME sam7x256
@}
+# ONLY use ENDIAN with targets that can change it.
if @{ [info exists ENDIAN] @} @{
set _ENDIAN $ENDIAN
@} else @{
set _ENDIAN little
@}
+# TAP identifiers may change as chips mature, for example with
+# new revision fields (the "3" here). Pick a good default; you
+# can pass several such identifiers to the "jtag newtap" command.
if @{ [info exists CPUTAPID ] @} @{
set _CPUTAPID $CPUTAPID
@} else @{
set _CPUTAPID 0x3f0f0f0f
@}
@end example
+@c but 0x3f0f0f0f is for an str73x part ...
+
+@emph{Remember:} Board config files may include multiple target
+config files, or the same target file multiple times
+(changing at least @code{CHIPNAME}).
+
+Likewise, the target configuration file should define
+@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and
+use it later on when defining debug targets:
+
+@example
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
+@end example
@subsection Adding TAPs to the Scan Chain
After the ``defaults'' are set up,
values for @code{CHIPNAME}, so
it adds a different TAP each time.
+If there are one or more nonzero @option{-expected-id} values,
+OpenOCD attempts to verify the actual tap id against those values.
+It will issue error messages if there is mismatch, which
+can help to pinpoint problems in OpenOCD configurations.
+
+@example
+JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
+ (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
+ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
+ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
+ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
+@end example
+
There are more complex examples too, with chips that have
multiple TAPs. Ones worth looking at include:
@itemize
-@item @file{target/omap3530.cfg} -- with a disabled ARM, and a JRC
-(there's a DSP too, which is not listed)
+@item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
+plus a JRC to enable them
@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
is not currently used)
After adding a TAP for a CPU, you should set it up so that
GDB and other commands can use it.
@xref{CPU Configuration}.
-For the at91sam7 example above, the command can look like this:
+For the at91sam7 example above, the command can look like this;
+note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
+to little endian, and this chip doesn't support changing that.
@example
set _TARGETNAME $_CHIPNAME.cpu
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
-through a ``trace port''. (@xref{ARM Tracing}.)
+through a ``trace port''. (@xref{ARM Hardware Tracing}.)
If you are using an external trace port,
configure it in your board config file.
If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
-@node About JIM-Tcl
-@chapter About JIM-Tcl
-@cindex JIM Tcl
-@cindex tcl
-
-OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can
-learn more about JIM here: @url{http://jim.berlios.de}
-
-@itemize @bullet
-@item @b{JIM 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
-impliments the basic Tcl command set along. 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.
-
-@item @b{Scripts}
-@* 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.
-
-@item @b{Commands}
-@* At the OpenOCD telnet command line (or via the GDB mon command) one
-can type a Tcl for() loop, set variables, etc.
-
-@item @b{Historical Note}
-@* JIM-Tcl was introduced to OpenOCD in spring 2008.
-
-@item @b{Need a crash course in Tcl?}
-@*@xref{Tcl Crash Course}.
-@end itemize
-
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
@section Configuration Stage
@cindex configuration stage
-@cindex configuration command
+@cindex config command
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.
-Those configuration commands include declaration of TAPs
+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.
+
+Those configuration commands include declaration of TAPs,
+flash banks,
+the interface used for JTAG communication,
and other basic setup.
The server must leave the configuration stage before it
may access or activate TAPs.
the memory read/write commands. This includes @command{nand probe}.
@end deffn
+@anchor{TCP/IP Ports}
@section TCP/IP Ports
@cindex TCP port
@cindex server
breakpoints if the memory map has been set up for flash regions.
@end deffn
-@deffn {Config command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
+@deffn {Config Command} gdb_detach (@option{resume}|@option{reset}|@option{halt}|@option{nothing})
Configures what OpenOCD will do when GDB detaches from the daemon.
Default behaviour is @option{resume}.
@end deffn
@anchor{gdb_flash_program}
-@deffn {Config command} gdb_flash_program (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_flash_program (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @option{enable}.
@end deffn
-@deffn {Config command} gdb_memory_map (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_memory_map (@option{enable}|@option{disable})
Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
using the GDB load command. @command{gdb_flash_program enable} must also be enabled
@xref{gdb_flash_program}.
@end deffn
-@deffn {Config command} gdb_report_data_abort (@option{enable}|@option{disable})
+@deffn {Config Command} gdb_report_data_abort (@option{enable}|@option{disable})
Specifies whether data aborts cause an error to be reported
by GDB memory read packets.
The default behaviour is @option{disable};
in case the vendor provides unique IDs and more than one FT2232 device
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} {ft2232_layout} name
@item @b{evb_lm3s811} 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)
+@item @b{luminary_icdi} Luminary In-Circuit Debug Interface (ICDI) Board
@item @b{flyswatter} Tin Can Tools Flyswatter
@item @b{icebear} ICEbear JTAG adapter from Section 5
@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles)
@defun jtag_rclk fallback_speed_kHz
@cindex RTCK
-This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK.
+This Tcl proc (defined in @file{startup.tcl}) attempts to enable RTCK/RCLK.
If that fails (maybe the interface, board, or target doesn't
support it), falls back to the specified frequency.
@example
@option{str912}, to support more than one chip of each type.
@xref{Config File Guidelines}.
-At this writing there is only a single command to work with
-scan chains, and there is no support for enumerating
-TAPs or examining their attributes.
+@deffn Command {jtag names}
+Returns the names of all current TAPs in the scan chain.
+Use @command{jtag cget} or @command{jtag tapisenabled}
+to examine attributes and state of each TAP.
+@example
+foreach t [jtag names] @{
+ puts [format "TAP: %s\n" $t]
+@}
+@end example
+@end deffn
@deffn Command {scan_chain}
Displays the TAPs in the scan chain configuration,
each TAP's instruction register can also change.
@end deffn
-@c FIXME! there should be commands to enumerate TAPs
-@c and get their attributes, like there are for targets.
-@c "jtag cget ..." will handle attributes.
-@c "jtag names" for enumerating TAPs, maybe.
+@c FIXME! "jtag cget" should be able to return all TAP
+@c attributes, like "$target_name cget" does for targets.
@c Probably want "jtag eventlist", and a "tap-reset" event
@c (on entry to RESET state).
In older code, JTAG TAPs were numbered from 0..N.
This feature is still present.
However its use is highly discouraged, and
-should not be counted upon.
-Update all of your scripts to use TAP names rather than numbers.
+should not be relied on; it will be removed by mid-2010.
+Update all of your scripts to use TAP names rather than numbers,
+by paying attention to the runtime warnings they trigger.
Using TAP numbers in target configuration scripts prevents
reusing those scripts on boards with multiple targets.
@end quotation
@end enumerate
Many CPUs have the ablity to ``boot'' from the first flash bank.
-This means that misprograming that bank can ``brick'' a system,
+This means that misprogramming that bank can ``brick'' a system,
so that it can't boot.
JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
board by (re)installing working boot firmware.
+@anchor{NOR Configuration}
@section Flash Configuration Commands
@cindex flash configuration
flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
@end example
+@c "cfi part_id" disabled
@end deffn
@subsection Internal Flash (Microcontrollers)
@end example
@end deffn
+@deffn {Flash Driver} at91sam3
+@cindex at91sam3
+All members of the AT91SAM3 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M3 core. The driver
+currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
+that the driver was orginaly developed and tested using the
+AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
+the family was cribbed from the data sheet. @emph{Note to future
+readers/updaters: Please remove this worrysome comment after other
+chips are confirmed.}
+
+The AT91SAM3U4[E/C] (256K) chips have 2 flash banks, the other chips
+(3U[1/2][E/C]) have 1 flash bank. In all cases the flash banks are at
+the following fixed locations:
+
+@example
+# Flash bank 0 - all chips
+flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
+# Flash bank 1 - only 256K chips
+flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
+@end example
+
+Internally, the AT91SAM3 flash memory is organized as follows.
+Unlike the AT91SAM7 chips, these are not used as parameters
+to the @command{flash bank} command:
+
+@itemize
+@item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @emph{Bank Size:} 128K/64K Per flash bank
+@item @emph{Sectors:} 16 or 8 per bank
+@item @emph{SectorSize:} 8K Per Sector
+@item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@end itemize
+
+The AT91SAM3 driver adds some additional commands:
+
+@deffn Command {at91sam3 gpnvm}
+@deffnx Command {at91sam3 gpnvm clear} number
+@deffnx Command {at91sam3 gpnvm set} number
+@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+With no parameters, @command{show} or @command{show all},
+shows the status of all GPNVM bits.
+With @command{show} @var{number}, displays that bit.
+
+With @command{set} @var{number} or @command{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
+@deffn Command {at91sam3 info}
+This command attempts to display information about the AT91SAM3
+chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
+Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
+document id: doc6430A] and decodes the values. @emph{Second} it reads the
+various clock configuration registers and attempts to display how it
+believes the chip is configured. By default, the SLOWCLK is assumed to
+be 32768 Hz, see the command @command{at91sam3 slowclk}.
+@end deffn
+
+@deffn Command {at91sam3 slowclk} [value]
+This command shows/sets the slow clock frequency used in the
+@command{at91sam3 info} command calculations above.
+@end deffn
+@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 recognizes a number of these chips using
-the chip identification register, and autoconfigures itself.
+All members of the AT91SAM7 microcontroller family from Atmel include
+internal flash and use ARM7TDMI cores. The driver automatically
+recognizes a number of these chips using the chip identification
+register, and autoconfigures itself.
@example
flash bank at91sam7 0 0 0 0 $_TARGETNAME
plane (of up to 256KB), and it will be used automatically when you issue
@command{flash erase_sector} or @command{flash erase_address} commands.
-@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
lpc2000_v2 14765 calc_checksum
@end example
+
+@deffn {Command} {lpc2000 part_id} bank
+Displays the four byte part identifier associated with
+the specified flash @var{bank}.
+@end deffn
@end deffn
@deffn {Flash Driver} lpc288x
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+@deffn Command {stm32x 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
@example
flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
+
+@deffn Command {str7x disable_jtag} bank
+Activate the Debug/Readout protection mechanism
+for the specified flash bank.
+@end deffn
@end deffn
@deffn {Flash Driver} str9x
Some larger devices will work, since they are actually multi-chip
modules with two smaller chips and individual chipselect lines.
+@anchor{NAND Configuration}
@section NAND Configuration Commands
@cindex NAND configuration
@section Daemon Commands
+@deffn {Command} exit
+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.
+@end deffn
+
@deffn Command sleep msec [@option{busy}]
Wait for at least @var{msec} milliseconds before resuming.
If @option{busy} is passed, busy-wait instead of sleeping.
These commands are available when
OpenOCD is built with @option{--enable-ioutil}.
-They are mainly useful on embedded targets;
-PC type hosts have complementary tools.
+They are mainly useful on embedded targets,
+notably the ZY1000.
+Hosts with operating systems have complementary tools.
@emph{Note:} there are several more such commands.
+@deffn Command append_file filename [string]*
+Appends the @var{string} parameters to
+the text file @file{filename}.
+Each string except the last one is followed by one space.
+The last string is followed by a newline.
+@end deffn
+
+@deffn Command cat filename
+Reads and displays the text file @file{filename}.
+@end deffn
+
+@deffn Command cp src_filename dest_filename
+Copies contents from the file @file{src_filename}
+into @file{dest_filename}.
+@end deffn
+
+@deffn Command ip
+@emph{No description provided.}
+@end deffn
+
+@deffn Command ls
+@emph{No description provided.}
+@end deffn
+
+@deffn Command mac
+@emph{No description provided.}
+@end deffn
+
@deffn Command meminfo
Display available RAM memory on OpenOCD host.
Used in OpenOCD regression testing scripts.
@end deffn
+@deffn Command peek
+@emph{No description provided.}
+@end deffn
+
+@deffn Command poke
+@emph{No description provided.}
+@end deffn
+
+@deffn Command rm filename
+@c "rm" has both normal and Jim-level versions??
+Unlinks the file @file{filename}.
+@end deffn
+
+@deffn Command trunc filename
+Removes all data in the file @file{filename}.
+@end deffn
+
@anchor{Memory access}
@section Memory access commands
@cindex memory access
(@option{bin}, @option{ihex}, or @option{elf})
@end deffn
+@deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]]
+Displays image section sizes and addresses
+as if @var{filename} were loaded into target memory
+starting at @var{address} (defaults to zero).
+The file format may optionally be specified
+(@option{bin}, @option{ihex}, or @option{elf})
+@end deffn
+
@deffn Command {verify_image} filename address [@option{bin}|@option{ihex}|@option{elf}]
Verify @var{filename} against target memory starting at @var{address}.
The file format may optionally be specified
@end deffn
@section Misc Commands
-@cindex profiling
+@cindex profiling
@deffn Command {profile} seconds filename
Profiling samples the CPU's program counter as quickly as possible,
which is useful for non-intrusive stochastic profiling.
Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format.
@end deffn
+@deffn Command {version}
+Displays a string identifying the version of this OpenOCD server.
+@end deffn
+
+@deffn Command {virt2phys} virtual_address
+Requests the current target to map the specified @var{virtual_address}
+to its corresponding physical address, and displays the result.
+@end deffn
+
@node Architecture and Core Commands
@chapter Architecture and Core Commands
@cindex Architecture Specific Commands
Some of those operations don't fit well in that framework, so they are
exposed here as architecture or implementation (core) specific commands.
-@anchor{ARM Tracing}
-@section ARM Tracing
+@anchor{ARM Hardware Tracing}
+@section ARM Hardware Tracing
+@cindex tracing
@cindex ETM
@cindex ETB
Control masking (disabling) interrupts during target step/resume.
@end deffn
-@section Target DCC Requests
+@anchor{Software Debug Messages and Tracing}
+@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
+@cindex tracing
@cindex libdcc
@cindex DCC
-OpenOCD can handle certain target requests; currently debugmsgs
+OpenOCD can process certain requests from target software. Currently
@command{target_request debugmsgs}
-are only supported for arm7_9 and cortex_m3.
+is supported only for @option{arm7_9} and @option{cortex_m3} cores.
+These messages are received as part of target polling, so
+you need to have @command{poll on} active to receive them.
+They are intrusive in that they will affect program execution
+times. If that is a problem, @pxref{ARM Hardware Tracing}.
+
+See @file{libdcc} in the contrib dir for more details.
+In addition to sending strings, characters, and
+arrays of various size integers from the target,
+@file{libdcc} also exports a software trace point mechanism.
+The target being debugged may
+issue trace messages which include a 24-bit @dfn{trace point} number.
+Trace point support includes two distinct mechanisms,
+each supported by a command:
+
+@itemize
+@item @emph{History} ... A circular buffer of trace points
+can be set up, and then displayed at any time.
+This tracks where code has been, which can be invaluable in
+finding out how some fault was triggered.
+
+The buffer may overflow, since it collects records continuously.
+It may be useful to use some of the 24 bits to represent a
+particular event, and other bits to hold data.
+
+@item @emph{Counting} ... An array of counters can be set up,
+and then displayed at any time.
+This can help establish code coverage and identify hot spots.
+
+The array of counters is directly indexed by the trace point
+number, so trace points with higher numbers are not counted.
+@end itemize
-See libdcc in the contrib dir for more details.
Linux-ARM kernels have a ``Kernel low-level debugging
via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
depends on CONFIG_DEBUG_LL) which uses this mechanism to
deliver messages before a serial console can be activated.
+This is not the same format used by @file{libdcc}.
+Other software, such as the U-Boot boot loader, sometimes
+does the same thing.
@deffn Command {target_request debugmsgs} [@option{enable}|@option{disable}|@option{charmsg}]
Displays current handling of target DCC message requests.
These messages may be sent to the debugger while the target is running.
The optional @option{enable} and @option{charmsg} parameters
both enable the messages, while @option{disable} disables them.
+
With @option{charmsg} the DCC words each contain one character,
as used by Linux with CONFIG_DEBUG_ICEDCC;
otherwise the libdcc format is used.
@end deffn
+@deffn Command {trace history} (@option{clear}|count)
+With no parameter, displays all the trace points that have triggered
+in the order they triggered.
+With the parameter @option{clear}, erases all current trace history records.
+With a @var{count} parameter, allocates space for that many
+history records.
+@end deffn
+
+@deffn Command {trace point} (@option{clear}|identifier)
+With no parameter, displays all trace point identifiers and how many times
+they have been triggered.
+With the parameter @option{clear}, erases all current trace point counters.
+With a numeric @var{identifier} parameter, creates a new a trace point counter
+and associates it with that identifier.
+
+@emph{Important:} The identifier and the trace point number
+are not related except by this command.
+These trace point numbers always start at zero (from server startup,
+or after @command{trace point clear}) and count up from there.
+@end deffn
+
+
@node JTAG Commands
@chapter JTAG Commands
@cindex JTAG Commands
Consult the documentation for the TAP(s) you are working with.
@end itemize
+@node Boundary Scan Commands
+@chapter Boundary Scan Commands
+
+One of the original purposes of JTAG was to support
+boundary scan based hardware testing.
+Although its primary focus is to support On-Chip Debugging,
+OpenOCD also includes some boundary scan commands.
+
+@section SVF: Serial Vector Format
+@cindex Serial Vector Format
+@cindex SVF
+
+The Serial Vector Format, better known as @dfn{SVF}, is a
+way to represent JTAG test patterns in text files.
+OpenOCD supports running such test files.
+
+@deffn Command {svf} filename [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the SVF script from @file{filename}.
+Unless the @option{quiet} option is specified,
+each command is logged before it is executed.
+@end deffn
+
+@section XSVF: Xilinx Serial Vector Format
+@cindex Xilinx Serial Vector Format
+@cindex XSVF
+
+The Xilinx Serial Vector Format, better known as @dfn{XSVF}, is a
+binary representation of SVF which is optimized for use with
+Xilinx devices.
+OpenOCD supports running such test files.
+
+@quotation Important
+Not all XSVF commands are supported.
+@end quotation
+
+@deffn Command {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the XSVF script from @file{filename}.
+When a @var{tapname} is specified, the commands are directed at
+that TAP.
+When @option{virt2} is specified, the @sc{xruntest} command counts
+are interpreted as TCK cycles instead of microseconds.
+Unless the @option{quiet} option is specified,
+messages are logged for comments and some retries.
+@end deffn
+
@node TFTP
@chapter TFTP
@cindex TFTP
@end itemize
OpenOCD commands can consist of two words, e.g. "flash banks". The
-startup.tcl "unknown" proc will translate this into a Tcl proc
+@file{startup.tcl} "unknown" proc will translate this into a Tcl proc
called "flash_banks".
@section OpenOCD specific Global Variables
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
@*Use @command{arm7_9 fast_memory_access} instead.
+@xref{arm7_9 fast_memory_access}.
@item @b{endstate}
@cindex endstate
@*An buggy old command that would not really work since background polling would wipe out the global endstate
-@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
for flash if the GDB memory map has been set up(default when flash is declared in
Code Review / openocd.git / blobdiff