@menu
* About:: About OpenOCD
* Developers:: OpenOCD Developers
-* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
* About JIM-Tcl:: About JIM-Tcl
* Running:: Running OpenOCD
@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, AT91SAM3U, STR7x, STR9x, LM3, and
+internal flashes (LPC1700, LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@section OpenOCD Subversion Repository
-The ``Building From Source'' section provides instructions to retrieve
-and and build the latest version of the OpenOCD source code.
-@xref{Building OpenOCD}.
+You can download the current SVN version with an SVN client of your
+choice from the following repositories:
+
+ @uref{svn://svn.berlios.de/openocd/trunk}
+
+or
+
+ @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
+
+Using the SVN command line client, you can use the following command to
+fetch the latest version (make sure there is no (non-svn) directory
+called "openocd" in the current directory):
+
+ svn checkout svn://svn.berlios.de/openocd/trunk openocd
+
+If you prefer GIT based tools, the @command{git-svn} package works too:
+
+ git svn clone -s svn://svn.berlios.de/openocd
+
+The ``README'' file contains the instructions for building the project
+from the repository.
Developers that want to contribute patches to the OpenOCD system are
@b{strongly} encouraged to base their work off of the most recent trunk
@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
-@node Building OpenOCD
-@chapter Building OpenOCD
-@cindex building
-
-@section Pre-Built Tools
-If you are interested in getting actual work done rather than building
-OpenOCD, then check if your interface supplier provides binaries for
-you. Chances are that that binary is from some SVN version that is more
-stable than SVN trunk where bleeding edge development takes place.
-
-@section Packagers Please Read!
-
-You are a @b{PACKAGER} of OpenOCD if you
-
-@enumerate
-@item @b{Sell dongles} and include pre-built binaries
-@item @b{Supply tools} i.e.: A complete development solution
-@item @b{Supply IDEs} like Eclipse, or RHIDE, etc.
-@item @b{Build packages} i.e.: RPM files, or DEB files for a Linux Distro
-@end enumerate
-
-As a @b{PACKAGER}, you will experience first reports of most issues.
-When you fix those problems for your users, your solution may help
-prevent hundreds (if not thousands) of other questions from other users.
-
-If something does not work for you, please work to inform the OpenOCD
-developers know how to improve the system or documentation to avoid
-future problems, and follow-up to help us ensure the issue will be fully
-resolved in our future releases.
-
-That said, the OpenOCD developers would also like you to follow a few
-suggestions:
-
-@enumerate
-@item Send patches, including config files, upstream.
-@item Always build with printer ports enabled.
-@item Use libftdi + libusb for FT2232 support.
-@end enumerate
-
-@section Building From Source
-
-You can download the current SVN version with an SVN client of your choice from the
-following repositories:
-
- @uref{svn://svn.berlios.de/openocd/trunk}
-
-or
-
- @uref{http://svn.berlios.de/svnroot/repos/openocd/trunk}
-
-Using the SVN command line client, you can use the following command to fetch the
-latest version (make sure there is no (non-svn) directory called "openocd" in the
-current directory):
-
-@example
- svn checkout svn://svn.berlios.de/openocd/trunk openocd
-@end example
-
-If you prefer GIT based tools, the @command{git-svn} package works too:
-
-@example
- git svn clone -s svn://svn.berlios.de/openocd
-@end example
-
-Building OpenOCD from a repository requires a recent version of the
-GNU autotools (autoconf >= 2.59 and automake >= 1.9).
-For building on Windows,
-you have to use Cygwin. Make sure that your @env{PATH} environment variable contains no
-other locations with Unix utils (like UnxUtils) - these can't handle the Cygwin
-paths, resulting in obscure dependency errors (This is an observation I've gathered
-from the logs of one user - correct me if I'm wrong).
-
-You further need the appropriate driver files, if you want to build support for
-a FTDI FT2232 based interface:
-
-@itemize @bullet
-@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
-@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}),
-or the Amontec version (from @uref{http://www.amontec.com}),
-for easier support of JTAGkey's vendor and product IDs.
-@end itemize
-
-libftdi is supported under Windows. Do not use versions earlier than 0.14.
-To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps),
-you need libftdi version 0.16 or newer.
-
-Some people say that FTDI's libftd2xx code provides better performance.
-However, it is binary-only, while OpenOCD is licenced according
-to GNU GPLv2 without any exceptions.
-That means that @emph{distributing} copies of OpenOCD built with
-the FTDI code would violate the OpenOCD licensing terms.
-You may, however, build such copies for personal use.
-
-To build OpenOCD (on both Linux and Cygwin), use the following commands:
-
-@example
- ./bootstrap
-@end example
-
-Bootstrap generates the configure script, and prepares building on your system.
-
-@example
- ./configure [options, see below]
-@end example
-
-Configure generates the Makefiles used to build OpenOCD.
-
-@example
- make
- make install
-@end example
-
-Make builds OpenOCD, and places the final executable in ./src/, the last step, ``make install'' is optional.
-
-The configure script takes several options, specifying which JTAG interfaces
-should be included (among other things):
-
-@itemize @bullet
-@item
-@option{--enable-parport} - Enable building the PC parallel port driver.
-@item
-@option{--enable-parport_ppdev} - Enable use of ppdev (/dev/parportN) for parport.
-@item
-@option{--enable-parport_giveio} - Enable use of giveio for parport instead of ioperm.
-@item
-@option{--enable-amtjtagaccel} - Enable building the Amontec JTAG-Accelerator driver.
-@item
-@option{--enable-ecosboard} - Enable building support for eCosBoard based JTAG debugger.
-@item
-@option{--enable-ioutil} - Enable ioutil functions - useful for standalone OpenOCD implementations.
-@item
-@option{--enable-httpd} - Enable builtin httpd server - useful for standalone OpenOCD implementations.
-@item
-@option{--enable-ep93xx} - Enable building support for EP93xx based SBCs.
-@item
-@option{--enable-at91rm9200} - Enable building support for AT91RM9200 based SBCs.
-@item
-@option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
-@item
-@option{--enable-ft2232_ftd2xx} - Support FT2232-family chips using
-the closed-source library from FTDICHIP.COM
-(result not for re-distribution).
-@item
-@option{--enable-ft2232_libftdi} - Support FT2232-family chips using
-a GPL'd ft2232 support library (result OK for re-distribution).
-@item
-@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
-give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
-@item
-@option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver
-on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked.
-@item
-@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static.
-Specifies how the FTDICHIP.COM libftd2xx driver should be linked.
-Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}.
-The 'shared' value is supported, however you must manually install the required
-header files and shared libraries in an appropriate place.
-@item
-@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
-@item
-@option{--enable-presto_ftd2xx} - Enable building support for ASIX Presto programmer using the FTD2XX driver.
-@item
-@option{--enable-usbprog} - Enable building support for the USBprog JTAG programmer.
-@item
-@option{--enable-oocd_trace} - Enable building support for the OpenOCD+trace ETM capture device.
-@item
-@option{--enable-jlink} - Enable building support for the Segger J-Link JTAG programmer.
-@item
-@option{--enable-vsllink} - Enable building support for the Versaloon-Link JTAG programmer.
-@item
-@option{--enable-rlink} - Enable building support for the Raisonance RLink JTAG programmer.
-@item
-@option{--enable-arm-jtag-ew} - Enable building support for the Olimex ARM-JTAG-EW programmer.
-@item
-@option{--enable-dummy} - Enable building the dummy port driver.
-@end itemize
-
-@section Parallel Port Dongles
-
-If you want to access the parallel port using the PPDEV interface you have to specify
-both the @option{--enable-parport} AND the @option{--enable-parport_ppdev} option since
-the @option{--enable-parport_ppdev} option actually is an option to the parport driver
-(see @uref{http://forum.sparkfun.com/viewtopic.php?t=3795} for more info).
-
-The same is true for the @option{--enable-parport_giveio} option, you have to
-use both the @option{--enable-parport} AND the @option{--enable-parport_giveio} option if you want to use giveio instead of ioperm parallel port access method.
-
-@section FT2232C Based USB Dongles
-
-There are 2 methods of using the FTD2232, either (1) using the
-FTDICHIP.COM closed source driver, or (2) the open (and free) driver
-libftdi. Some claim the (closed) FTDICHIP.COM solution is faster,
-which is the motivation for supporting it even though its licensing
-restricts it to non-redistributable OpenOCD binaries, and it is
-not available for all operating systems used with OpenOCD.
-
-The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
-TAR.GZ file. You must unpack them ``some where'' convient. As of this
-writing FTDICHIP does not supply means to install these
-files ``in an appropriate place''.
-As a result, there are two
-``./configure'' options that help.
-
-Below is an example build process:
-
-@enumerate
-@item Check out the latest version of ``openocd'' from SVN.
-
-@item If you are using the FTDICHIP.COM driver, download
-and unpack the Windows or Linux FTD2xx drivers
-(@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
-If you are using the libftdi driver, install that package
-(e.g. @command{apt-get install libftdi} on systems with APT).
-
-@example
-/home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents
-/home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents
-@end example
-
-@item Configure with options resembling the following.
-
-@enumerate a
-@item Cygwin FTDICHIP solution:
-@example
-./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
-@end example
-
-@item Linux FTDICHIP solution:
-@example
-./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
-@end example
-
-@item Cygwin/Linux LIBFTDI solution ... assuming that
-@itemize
-@item For Windows -- that the Windows port of LIBUSB is in place.
-@item For Linux -- that libusb has been built/installed and is in place.
-@item That libftdi has been built and installed (relies on libusb).
-@end itemize
-
-Then configure the libftdi solution like this:
-
-@example
-./configure --prefix=/home/duane/mytools \
- --enable-ft2232_libftdi
-@end example
-@end enumerate
-
-@item Then just type ``make'', and perhaps ``make install''.
-@end enumerate
-
-
-@section Miscellaneous Configure Options
-
-@itemize @bullet
-@item
-@option{--disable-option-checking} - Ignore unrecognized @option{--enable} and @option{--with} options.
-@item
-@option{--enable-gccwarnings} - Enable extra gcc warnings during build.
-Default is enabled.
-@item
-@option{--enable-release} - Enable building of an OpenOCD release, generally
-this is for developers. It simply omits the svn version string when the
-openocd @option{-v} is executed.
-@end itemize
-
@node JTAG Hardware Dongles
@chapter JTAG Hardware Dongles
@cindex dongles
@section Choosing a Dongle
-There are three things you should keep in mind when choosing a dongle.
+There are several things you should keep in mind when choosing a dongle.
-@enumerate
-@item @b{Voltage} What voltage is your target? 1.8, 2.8, 3.3, or 5V? Does your dongle support it?
-@item @b{Connection} Printer Ports - Does your computer have one?
-@item @b{Connection} Is that long printer bit-bang cable practical?
-@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
+@enumerate
+@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?
+Does your dongle support it? You may be able to use jumper
+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''
@end enumerate
@section Stand alone Systems
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@item @b{jtagkey}
@* See: @url{http://www.amontec.com/jtagkey.shtml}
+@item @b{jtagkey2}
+@* See: @url{http://www.amontec.com/jtagkey2.shtml}
@item @b{oocdlink}
@* See: @url{http://www.oocdlink.com} By Joern Kaipf
@item @b{signalyzer}
@* 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}
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
-@item @b{USB - Presto}
+@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
and the MacGraigor Wiggler. There are many clones and variations of
these on the market.
+Note that parallel ports are becoming much less common, so if you
+have the choice you should probably avoid these adapters in favor
+of USB-based ones.
+
@itemize @bullet
@item @b{Wiggler} - There are many clones of this.
@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.
--pipe | -p use pipes when talking to gdb
@end verbatim
-By default OpenOCD reads the file configuration file ``openocd.cfg''
+By default OpenOCD reads the file configuration file @file{openocd.cfg}
in the current directory. To specify a different (or multiple)
configuration file, you can use the ``-f'' option. For example:
@example
- openocd -f config1.cfg -f config2.cfg -f config3.cfg
+openocd -f config1.cfg -f config2.cfg -f config3.cfg
@end example
-Once started, OpenOCD runs as a daemon, waiting for connections from
-clients (Telnet, GDB, Other).
+OpenOCD starts by processing the configuration commands provided
+on the command line or in @file{openocd.cfg}.
+@xref{Configuration Stage}.
+At the end of the configuration stage it verifies the JTAG scan
+chain defined using those commands; your configuration should
+ensure that this always succeeds.
+Normally, OpenOCD then starts running as a daemon.
+Alternatively, commands may be used to terminate the configuration
+stage early, perform work (such as updating some flash memory),
+and then shut down without acting as a daemon.
+
+Once OpenOCD starts running as a daemon, it waits for connections from
+clients (Telnet, GDB, Other) and processes the commands issued through
+those channels.
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
@item
You may may need to write some C code.
-It may be as simple as a supporting a new new ft2232 or parport
+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
controller driver; or a big piece of work like supporting
a new chip architecture.
When you write config files, separate the reusable parts
(things every user of that interface, chip, or board needs)
from ones specific to your environment and debugging approach.
+@itemize
+@item
For example, a @code{gdb-attach} event handler that invokes
the @command{reset init} command will interfere with debugging
early boot code, which performs some of the same actions
that the @code{reset-init} event handler does.
+
+@item
Likewise, the @command{arm9tdmi vector_catch} command (or
-its @command{xscale vector_catch} sibling) can be a timesaver
+@cindex vector_catch
+its siblings @command{xscale vector_catch}
+and @command{cortex_m3 vector_catch}) 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,
along with messaging and tracing setup.
(@xref{Software Debug Messages and Tracing}.)
+@item
+You might need to override some defaults.
+For example, you might need to move, shrink, or back up the target's
+work area if your application needs much SRAM.
+
+@item
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}.
+@end itemize
@section Project-Specific Utilities
Other helper scripts might be used to write production system images,
involving considerably more than just a three stage bootloader.
+@section Target Software Changes
+
+Sometimes you may want to make some small changes to the software
+you're developing, to help make JTAG debugging work better.
+For example, in C or assembly language code you might
+use @code{#ifdef JTAG_DEBUG} (or its converse) around code
+handling issues like:
+
+@itemize @bullet
+
+@item @b{ARM Wait-For-Interrupt}...
+Many ARM chips synchronize the JTAG clock using the core clock.
+Low power states which stop that core clock thus prevent JTAG access.
+Idle loops in tasking environments often enter those low power states
+via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
+
+You may want to @emph{disable that instruction} in source code,
+or otherwise prevent using that state,
+to ensure you can get JTAG access at any time.
+For example, the OpenOCD @command{halt} command may not
+work for an idle processor otherwise.
+
+@item @b{Delay after reset}...
+Not all chips have good support for debugger access
+right after reset; many LPC2xxx chips have issues here.
+Similarly, applications that reconfigure pins used for
+JTAG access as they start will also block debugger access.
+
+To work with boards like this, @emph{enable a short delay loop}
+the first thing after reset, before "real" startup activities.
+For example, one second's delay is usually more than enough
+time for a JTAG debugger to attach, so that
+early code execution can be debugged
+or firmware can be replaced.
+
+@item @b{Debug Communications Channel (DCC)}...
+Some processors include mechanisms to send messages over JTAG.
+Many ARM cores support these, as do some cores from other vendors.
+(OpenOCD may be able to use this DCC internally, speeding up some
+operations like writing to memory.)
+
+Your application may want to deliver various debugging messages
+over JTAG, by @emph{linking with a small library of code}
+provided with OpenOCD and using the utilities there to send
+various kinds of message.
+@xref{Software Debug Messages and Tracing}.
+
+@end itemize
@node Config File Guidelines
@chapter Config File Guidelines
@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.)
+the PLLs and clocking, you may need to run with
+a low JTAG clock rate.
+@xref{JTAG Speed}.
+Then you'd increase that rate after your handler has
+made it possible to use the faster JTAG clock.
+When the initial low speed is board-specific, for example
+because it depends on a board-specific oscillator speed, then
+you should probably set it up in the board config file;
+if it's target-specific, it belongs in the target config file.
+
+For most ARM-based processors the fastest JTAG clock@footnote{A FAQ
+@uref{http://www.arm.com/support/faqdev/4170.html} gives details.}
+is one sixth of the CPU clock; or one eighth for ARM11 cores.
+Consult chip documentation to determine the peak JTAG clock rate,
+which might be less than that.
+
+@quotation Warning
+On most ARMs, JTAG clock detection is coupled to the core clock, so
+software using a @option{wait for interrupt} operation blocks JTAG access.
+Adaptive clocking provides a partial workaround, but a more complete
+solution just avoids using that instruction with JTAG debuggers.
+@end quotation
+
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}.
values for @code{CHIPNAME}, so
it adds a different TAP each time.
-If there are one or more nonzero @option{-expected-id} values,
+If there are 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.
@code{reset-deassert-post} event handler that writes a chip
register to report that JTAG debugging is being done.
+JTAG clocking constraints often change during reset, and in
+some cases target config files (rather than board config files)
+are the right places to handle some of those issues.
+For example, immediately after reset most chips run using a
+slower clock than they will use later.
+That means that after reset (and potentially, as OpenOCD
+first starts up) they must use a slower JTAG clock rate
+than they will use later.
+@xref{JTAG Speed}.
+
+@quotation Important
+When you are debugging code that runs right after chip
+reset, getting these issues right is critical.
+In particular, if you see intermittent failures when
+OpenOCD verifies the scan chain after reset,
+look at how you are setting up JTAG clocking.
+@end quotation
+
@subsection ARM Core Specific Hacks
If the chip has a DCC, enable it. If the chip is an ARM9 with some
used to specify what TCP/IP ports are used, and how GDB should be
supported.
+@anchor{Configuration Stage}
@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.
After it leaves this stage, configuration commands may no
longer be issued.
+The first thing OpenOCD does after leaving the configuration
+stage is to verify that it can talk to the scan chain
+(list of TAPs) which has been configured.
+It will warn if it doesn't find TAPs it expects to find,
+or finds TAPs that aren't supposed to be there.
+You should see no errors at this point.
+If you see errors, resolve them by correcting the
+commands you used to configure the server.
+Common errors include using an initial JTAG speed that's too
+fast, and not providing the right IDCODE values for the TAPs
+on the scan chain.
+
@deffn {Config Command} init
This command terminates the configuration stage and
enters the normal command mode. This can be useful to add commands to
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)
+@item @b{jtagkey2} Amontec JTAGkey2 (and compatibles)
@item @b{m5960} American Microsystems M5960
@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny
@item @b{oocdlink} OOCDLink
oscillators used, the chip, the board design, and sometimes
power management software that may be active.
-The speed used during reset can be adjusted using pre_reset
-and post_reset event handlers.
+The speed used during reset, and the scan chain verification which
+follows reset, can be adjusted using a @code{reset-start}
+target event handler.
+It can then be reconfigured to a faster speed by a
+@code{reset-init} target event handler after it reprograms those
+CPU clocks, or manually (if something else, such as a boot loader,
+sets up those clocks).
@xref{Target Events}.
+When the initial low JTAG speed is a chip characteristic, perhaps
+because of a required oscillator speed, provide such a handler
+in the target config file.
+When that speed is a function of a board-specific characteristic
+such as which speed oscillator is used, it belongs in the board
+config file instead.
+In both cases it's safest to also set the initial JTAG clock rate
+to that same slow speed, so that OpenOCD never starts up using a
+clock speed that's faster than the scan chain can support.
+
+@example
+jtag_rclk 3000
+$_TARGET.cpu configure -event reset-start @{ jtag_rclk 3000 @}
+@end example
If your system supports adaptive clocking (RTCK), configuring
JTAG to use that is probably the most robust approach.
speeds. The speed actually used won't be faster
than the speed specified.
-As a rule of thumb, if you specify a clock rate make
-sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
-This is especially true for synthesized cores (ARMxxx-S).
+Chip data sheets generally include a top JTAG clock rate.
+The actual rate is often a function of a CPU core clock,
+and is normally less than that peak rate.
+For example, most ARM cores accept at most one sixth of the CPU clock.
Speed 0 (khz) selects RTCK method.
@xref{FAQ RTCK}.
@end deffn
@defun jtag_rclk fallback_speed_kHz
+@cindex adaptive clocking
@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{combined} implies both @option{srst_pulls_trst} and
@option{trst_pulls_srst}.
+@option{srst_gates_jtag} indicates that asserting SRST gates the
+JTAG clock. This means that no communication can happen on JTAG
+while SRST is asserted.
+
The optional @var{trst_type} and @var{srst_type} parameters allow the
driver mode of each reset line to be specified. These values only affect
JTAG interfaces with support for different driver modes, like the Amontec
@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
Every TAP requires at least the following @var{configparams}:
@itemize @bullet
-@item @code{-ircapture} @var{NUMBER}
-@*The IDCODE capture command, such as 0x01.
@item @code{-irlen} @var{NUMBER}
@*The length in bits of the
instruction register, such as 4 or 5 bits.
-@item @code{-irmask} @var{NUMBER}
-@*A mask for the IR register.
-For some devices, there are bits in the IR that aren't used.
-This lets OpenOCD mask them off when doing IDCODE comparisons.
-In general, this should just be all ones for the size of the IR.
@end itemize
A TAP may also provide optional @var{configparams}:
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@item @code{-expected-id} @var{number}
-@*A non-zero value represents the expected 32-bit IDCODE
-found when the JTAG chain is examined.
+@*A non-zero @var{number} represents a 32-bit IDCODE
+which you expect to find when the scan chain is examined.
These codes are not required by all JTAG devices.
@emph{Repeat the option} as many times as required if more than one
ID code could appear (for example, multiple versions).
+Specify @var{number} as zero to suppress warnings about IDCODE
+values that were found but not included in the list.
+@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.
+JTAG requires the two LSBs of this value to be 01.
+By default, @code{-ircapture} and @code{-irmask} are set
+up to verify that two-bit value; but you may provide
+additional bits, if you know them.
+@item @code{-irmask} @var{NUMBER}
+@*A mask used with @code{-ircapture}
+to verify that instruction scans work correctly.
+Such scans are not used by OpenOCD except to verify that
+there seems to be no problems with JTAG scan chain operations.
@end itemize
@end deffn
+@section Other TAP commands
+
@c @deffn Command {jtag arp_init-reset}
-@c ... more or less "init" ?
+@c ... more or less "toggle TRST ... and SRST too, what the heck"
+
+@deffn Command {jtag cget} dotted.name @option{-event} name
+@deffnx Command {jtag configure} dotted.name @option{-event} name string
+At this writing this TAP attribute
+mechanism is used only for event handling.
+(It is not a direct analogue of the @code{cget}/@code{configure}
+mechanism for debugger targets.)
+See the next section for information about the available events.
+
+The @code{configure} subcommand assigns an event handler,
+a TCL string which is evaluated when the event is triggered.
+The @code{cget} subcommand returns that handler.
+@end deffn
+
+@anchor{TAP Events}
+@section TAP Events
+@cindex events
+@cindex TAP events
+
+OpenOCD includes two event mechanisms.
+The one presented here applies to all JTAG TAPs.
+The other applies to debugger targets,
+which are associated with certain TAPs.
+
+The TAP events currently defined are:
+
+@itemize @bullet
+@item @b{post-reset}
+@* The TAP has just completed a JTAG reset.
+The tap may still be in the JTAG @sc{reset} state.
+Handlers for these events might perform initialization sequences
+such as issuing TCK cycles, TMS sequences to ensure
+exit from the ARM SWD mode, and more.
+
+Because the scan chain has not yet been verified, handlers for these events
+@emph{should not issue commands which scan the JTAG IR or DR registers}
+of any particular target.
+@b{NOTE:} As this is written (September 2009), nothing prevents such access.
+@item @b{setup}
+@* The scan chain has been reset and verified.
+This handler may enable TAPs as needed.
+@item @b{tap-disable}
+@* The TAP needs to be disabled. This handler should
+implement @command{jtag tapdisable}
+by issuing the relevant JTAG commands.
+@item @b{tap-enable}
+@* The TAP needs to be enabled. This handler should
+implement @command{jtag tapenable}
+by issuing the relevant JTAG commands.
+@end itemize
+
+If you need some action after each JTAG reset, which isn't actually
+specific to any TAP (since you can't yet trust the scan chain's
+contents to be accurate), you might:
+
+@example
+jtag configure CHIP.jrc -event post-reset @{
+ echo "JTAG Reset done"
+ ... non-scan jtag operations to be done after reset
+@}
+@end example
+
@anchor{Enabling and Disabling TAPs}
@section Enabling and Disabling TAPs
-@cindex TAP events
@cindex JTAG Route Controller
@cindex jrc
@c (a) currently the event handlers don't seem to be able to
@c fail in a way that could lead to no-change-of-state.
-@c (b) eventually non-event configuration should be possible,
-@c in which case some this documentation must move.
-
-@deffn Command {jtag cget} dotted.name @option{-event} name
-@deffnx Command {jtag configure} dotted.name @option{-event} name string
-At this writing this mechanism is used only for event handling,
-and the only two events relate to TAP enabling and disabling.
-
-The @code{configure} subcommand assigns an event handler,
-a TCL string which is evaluated when the event is triggered.
-The @code{cget} subcommand returns that handler.
-The two possible values for an event @var{name}
-are @option{tap-disable} and @option{tap-enable}.
+In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
+shown below, and is implemented using TAP event handlers.
So for example, when defining a TAP for a CPU connected to
-a JTAG router, you should define TAP event handlers using
+a JTAG router, your @file{target.cfg} file
+should define TAP event handlers using
code that looks something like this:
@example
jtag configure CHIP.cpu -event tap-enable @{
- echo "Enabling CPU TAP"
... jtag operations using CHIP.jrc
@}
jtag configure CHIP.cpu -event tap-disable @{
- echo "Disabling CPU TAP"
... jtag operations using CHIP.jrc
@}
@end example
-@end deffn
+
+Then you might want that CPU's TAP enabled almost all the time:
+
+@example
+jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
+@end example
+
+Note how that particular setup event handler declaration
+uses quotes to evaluate @code{$CHIP} when the event is configured.
+Using brackets @{ @} would cause it to be evaluated later,
+at runtime, when it might have a different value.
@deffn Command {jtag tapdisable} dotted.name
-@deffnx Command {jtag tapenable} dotted.name
-@deffnx Command {jtag tapisenabled} dotted.name
-These three commands all return the string "1" if the tap
+If necessary, disables the tap
+by sending it a @option{tap-disable} event.
+Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
-and "0" if it is disbabled.
-The @command{tapenable} variant first enables the tap
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapenable} dotted.name
+If necessary, enables the tap
by sending it a @option{tap-enable} event.
-The @command{tapdisable} variant first disables the tap
-by sending it a @option{tap-disable} event.
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapisenabled} dotted.name
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
@quotation Note
Humans will find the @command{scan_chain} command more helpful
-than the script-oriented @command{tapisenabled}
for querying the state of the JTAG taps.
@end quotation
@end deffn
Several commands let you examine the list of targets:
@deffn Command {target count}
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.
+Iterate target using @command{target names}, not by counting.}
+
Returns the number of targets, @math{N}.
The highest numbered target is @math{N - 1}.
@example
@end deffn
@deffn Command {target number} number
+@emph{Note: target numbers are deprecated; don't use them.
+They will be removed shortly after August 2010, including this command.}
+
The list of targets is numbered starting at zero.
This command returns the name of the target at index @var{number}.
@example
which OpenOCD needs to know about.
@item @code{-work-area-backup} (@option{0}|@option{1}) -- says
-whether the work area gets backed up; by default, it doesn't.
+whether the work area gets backed up; by default,
+@emph{it is not backed up.}
When possible, use a working_area that doesn't need to be backed up,
since performing a backup slows down operations.
+For example, the beginning of an SRAM block is likely to
+be used by most build systems, but the end is often unused.
@item @code{-work-area-size} @var{size} -- specify/set the work area
all the targets you might use something like this:
@example
-for @{ set x 0 @} @{ $x < [target count] @} @{ incr x @} @{
- set name [target number $x]
+foreach name [target names] @{
set y [$name cget -endian]
set z [$name cget -type]
puts [format "Chip %d is %s, Endian: %s, type: %s" \
@anchor{Target Events}
@section Target Events
+@cindex target events
@cindex events
At various times, certain things can happen, or you want them to happen.
For example:
@item @b{reset-assert-pre}
@* Issued as part of @command{reset} processing
after SRST and/or TRST were activated and deactivated,
-but before reset is asserted on the tap.
+but before SRST alone is re-asserted on the tap.
@item @b{reset-assert-post}
@* Issued as part of @command{reset} processing
-when reset is asserted on the tap.
+when SRST is asserted on the tap.
@item @b{reset-deassert-pre}
@* Issued as part of @command{reset} processing
-when reset is about to be released on the tap.
-
-For some chips, this may be a good place to make sure
-the JTAG clock is slow enough to work before the PLL
-has been set up to allow faster JTAG speeds.
+when SRST is about to be released on the tap.
@item @b{reset-deassert-post}
@* Issued as part of @command{reset} processing
-when reset has been released on the tap.
+when SRST has been released on the tap.
@item @b{reset-end}
@* Issued as the final step in @command{reset} processing.
@ignore
This is where you would configure PLLs and clocking, set up DRAM so
you can download programs that don't fit in on-chip SRAM, set up pin
multiplexing, and so on.
+(You may be able to switch to a fast JTAG clock rate here, after
+the target clocks are fully set up.)
@item @b{reset-start}
@* Issued as part of @command{reset} processing
before either SRST or TRST are activated.
+
+This is the most robust place to switch to a low JTAG clock rate, if
+SRST disables PLLs needed to use a fast clock.
@ignore
@item @b{reset-wait-pos}
@* Currently not used
@anchor{flash erase_sector}
@deffn Command {flash erase_sector} num first last
-Erase sectors in bank @var{num}, starting at sector @var{first} up to and including
-@var{last}. Sector numbering starts at 0.
+Erase sectors in bank @var{num}, starting at sector @var{first}
+up to and including @var{last}.
+Sector numbering starts at 0.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
The @var{num} parameter is a value shown by @command{flash banks}.
This is the only operation that
updates the erase state information displayed by @option{flash info}. That means you have
-to issue an @command{flash erase_check} command after erasing or programming the device
+to issue a @command{flash erase_check} command after erasing or programming the device
to get updated information.
(Code execution may have invalidated any state records kept by OpenOCD.)
@end deffn
@end deffn
@anchor{flash protect}
-@deffn Command {flash protect} num first last (on|off)
-Enable (@var{on}) or disable (@var{off}) protection of flash sectors
-@var{first} to @var{last} of flash bank @var{num}.
+@deffn Command {flash protect} num first last (@option{on}|@option{off})
+Enable (@option{on}) or disable (@option{off}) protection of flash sectors
+in flash bank @var{num}, starting at sector @var{first}
+and continuing up to and including @var{last}.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@subsection Internal Flash (Microcontrollers)
@deffn {Flash Driver} aduc702x
-The ADUC702x analog microcontrollers from ST Micro
+The ADUC702x analog microcontrollers from Analog Devices
include internal flash and use ARM7TDMI cores.
The aduc702x flash driver works with models ADUC7019 through ADUC7028.
The setup command only requires the @var{target} argument
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 AT91SAM3U4[E/C] (256K) chips have two flash banks; most other chips
+have one flash bank. In all cases the flash banks are at
the following fixed locations:
@example
@end deffn
@deffn {Flash Driver} lpc2000
-Most members of the LPC2000 microcontroller family from NXP
-include internal flash and use ARM7TDMI cores.
+Most members of the LPC1700 and LPC2000 microcontroller families from NXP
+include internal flash and use Cortex-M3 (LPC1700) or ARM7TDMI (LPC2000) cores.
+
+@quotation Note
+There are LPC2000 devices which are not supported by the @var{lpc2000}
+driver:
+The LPC2888 is supported by the @var{lpc288x} driver.
+The LPC29xx family is supported by the @var{lpc2900} driver.
+@end quotation
+
The @var{lpc2000} driver defines two mandatory and one optional parameters,
which must appear in the following order:
@itemize
@item @var{variant} ... required, may be
@var{lpc2000_v1} (older LPC21xx and LPC22xx)
-or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+or @var{lpc1700} (LPC175x and LPC176x)
@item @var{clock_kHz} ... the frequency, in kiloHertz,
at which the core is running
@item @var{calc_checksum} ... optional (but you probably want to provide this!),
@end example
@end deffn
+@deffn {Flash Driver} lpc2900
+This driver supports the LPC29xx ARM968E based microcontroller family
+from NXP.
+
+The predefined parameters @var{base}, @var{size}, @var{chip_width} and
+@var{bus_width} of the @code{flash bank} command are ignored. Flash size and
+sector layout are auto-configured by the driver.
+The driver has one additional mandatory parameter: The CPU clock rate
+(in kHz) at the time the flash operations will take place. Most of the time this
+will not be the crystal frequency, but a higher PLL frequency. The
+@code{reset-init} event handler in the board script is usually the place where
+you start the PLL.
+
+The driver rejects flashless devices (currently the LPC2930).
+
+The EEPROM in LPC2900 devices is not mapped directly into the address space.
+It must be handled much more like NAND flash memory, and will therefore be
+handled by a separate @code{lpc2900_eeprom} driver (not yet available).
+
+Sector protection in terms of the LPC2900 is handled transparently. Every time a
+sector needs to be erased or programmed, it is automatically unprotected.
+What is shown as protection status in the @code{flash info} command, is
+actually the LPC2900 @emph{sector security}. This is a mechanism to prevent a
+sector from ever being erased or programmed again. As this is an irreversible
+mechanism, it is handled by a special command (@code{lpc2900 secure_sector}),
+and not by the standard @code{flash protect} command.
+
+Example for a 125 MHz clock frequency:
+@example
+flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000
+@end example
+
+Some @code{lpc2900}-specific commands are defined. In the following command list,
+the @var{bank} parameter is the bank number as obtained by the
+@code{flash banks} command.
+
+@deffn Command {lpc2900 signature} bank
+Calculates a 128-bit hash value, the @emph{signature}, from the whole flash
+content. This is a hardware feature of the flash block, hence the calculation is
+very fast. You may use this to verify the content of a programmed device against
+a known signature.
+Example:
+@example
+lpc2900 signature 0
+ signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
+@end example
+@end deffn
+
+@deffn Command {lpc2900 read_custom} bank filename
+Reads the 912 bytes of customer information from the flash index sector, and
+saves it to a file in binary format.
+Example:
+@example
+lpc2900 read_custom 0 /path_to/customer_info.bin
+@end example
+@end deffn
+
+The index sector of the flash is a @emph{write-only} sector. It cannot be
+erased! In order to guard against unintentional write access, all following
+commands need to be preceeded by a successful call to the @code{password}
+command:
+
+@deffn Command {lpc2900 password} bank password
+You need to use this command right before each of the following commands:
+@code{lpc2900 write_custom}, @code{lpc2900 secure_sector},
+@code{lpc2900 secure_jtag}.
+
+The password string is fixed to "I_know_what_I_am_doing".
+Example:
+@example
+lpc2900 password 0 I_know_what_I_am_doing
+ Potentially dangerous operation allowed in next command!
+@end example
+@end deffn
+
+@deffn Command {lpc2900 write_custom} bank filename type
+Writes the content of the file into the customer info space of the flash index
+sector. The filetype can be specified with the @var{type} field. Possible values
+for @var{type} are: @var{bin} (binary), @var{ihex} (Intel hex format),
+@var{elf} (ELF binary) or @var{s19} (Motorola S-records). The file must
+contain a single section, and the contained data length must be exactly
+912 bytes.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Example:
+@example
+lpc2900 write_custom 0 /path_to/customer_info.bin bin
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_sector} bank first last
+Secures the sector range from @var{first} to @var{last} (including) against
+further program and erase operations. The sector security will be effective
+after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Secured sectors appear as @emph{protected} in the @code{flash info} command.
+Example:
+@example
+lpc2900 secure_sector 0 1 1
+flash info 0
+ #0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
+ # 0: 0x00000000 (0x2000 8kB) not protected
+ # 1: 0x00002000 (0x2000 8kB) protected
+ # 2: 0x00004000 (0x2000 8kB) not protected
+@end example
+@end deffn
+
+@deffn Command {lpc2900 secure_jtag} bank
+Irreversibly disable the JTAG port. The new JTAG security setting will be
+effective after the next power cycle.
+@quotation Attention
+This cannot be reverted! Be careful!
+@end quotation
+Examples:
+@example
+lpc2900 secure_jtag 0
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} ocl
@emph{No idea what this is, other than using some arm7/arm9 core.}
@end deffn
@deffn Command {nand list}
-Prints a one-line summary of each device declared
+Prints a summary of each device declared
using @command{nand device}, numbered from zero.
Note that un-probed devices show no details.
+@example
+> nand list
+#0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+#1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
+ blocksize: 131072, blocks: 8192
+>
+@end example
@end deffn
@deffn Command {nand probe} num
@end itemize
@end deffn
-@deffn Command {nand erase} num offset length
+@deffn Command {nand erase} num [offset length]
@cindex NAND erasing
@cindex NAND programming
Erases blocks on the specified NAND device, starting at the
specified @var{offset} and continuing for @var{length} bytes.
Both of those values must be exact multiples of the device's
block size, and the region they specify must fit entirely in the chip.
+If those parameters are not specified,
+the whole NAND chip will be erased.
The @var{num} parameter is the value shown by @command{nand list}.
@b{NOTE:} This command will try to erase bad blocks, when told
chips from Texas Instruments.
It takes three extra parameters:
address of the NAND chip;
-hardware ECC mode to use (hwecc1, hwecc4, hwecc4_infix);
+hardware ECC mode to use (@option{hwecc1},
+@option{hwecc4}, @option{hwecc4_infix});
address of the AEMIF controller on this processor.
@example
nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
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.
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.
+and robustness with a minimum of configuration.
Typically the "fast enable" is specified first on the command line:
or 5 seconds if there is no parameter, for the target to halt
(and enter debug mode).
Using 0 as the @var{ms} parameter prevents OpenOCD from waiting.
+
+@quotation Warning
+On ARM cores, software using the @emph{wait for interrupt} operation
+often blocks the JTAG access needed by a @command{halt} command.
+This is because that operation also puts the core into a low
+power mode by gating the core clock;
+but the core clock is needed to detect JTAG clock transitions.
+
+One partial workaround uses adaptive clocking: when the core is
+interrupted the operation completes, then JTAG clocks are accepted
+at least until the interrupt handler completes.
+However, this workaround is often unusable since the processor, board,
+and JTAG adapter must all support adaptive JTAG clocking.
+Also, it can't work until an interrupt is issued.
+
+A more complete workaround is to not use that operation while you
+work with a JTAG debugger.
+Tasking environments generaly have idle loops where the body is the
+@emph{wait for interrupt} operation.
+(On older cores, it is a coprocessor action;
+newer cores have a @option{wfi} instruction.)
+Such loops can just remove that operation, at the cost of higher
+power consumption (because the CPU is needlessly clocked).
+@end quotation
+
@end deffn
@deffn Command resume [address]
It's unclear how much of a common interface is shared
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
+At this writing (September 2009) only ARM7 and ARM9 support
+for ETM modules is available. The code should be able to
+work with some newer cores; but not all of them support
+this original style of JTAG access.
@end quotation
@subsection ETM Configuration
The @var{clocking} must be @option{half} or @option{full}.
@quotation Note
-You can see the ETM registers using the @command{reg} command, although
-not all of those possible registers are present in every ETM.
+You can see the ETM registers using the @command{reg} command.
+Not all possible registers are present in every ETM.
+Most of the registers are write-only, and are used to configure
+what CPU activities are traced.
@end quotation
@end deffn
@end deffn
@deffn Command {etm status}
-Displays status of the current target's ETM:
+Displays status of the current target's ETM and trace port driver:
is the ETM idle, or is it collecting data?
Did trace data overflow?
Was it triggered?
and any buffered trace data is invalidated.
@itemize
-@item @var{type} ... one of
+@item @var{type} ... describing how data accesses are traced,
+when they pass any ViewData filtering that that was set up.
+The value is one of
@option{none} (save nothing),
@option{data} (save data),
@option{address} (save addresses),
@option{all} (save data and addresses)
@item @var{context_id_bits} ... 0, 8, 16, or 32
@item @var{cycle_accurate} ... @option{enable} or @option{disable}
-@item @var{branch_output} ... @option{enable} or @option{disable}
+cycle-accurate instruction tracing.
+Before ETMv3, enabling this causes much extra data to be recorded.
+@item @var{branch_output} ... @option{enable} or @option{disable}.
+Disable this unless you need to try reconstructing the instruction
+trace stream without an image of the code.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} percent
-@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@deffn Command {etm trigger_percent} [percent]
+This displays, or optionally changes, the trace port driver's
+behavior after the ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
@end deffn
@subsection ETM Trace Operation
That data can be exported to files for later analysis.
It can also be parsed with OpenOCD, for basic sanity checking.
+To configure what is being traced, you will need to write
+various trace registers using @command{reg ETM_*} commands.
+For the definitions of these registers, read ARM publication
+@emph{IHI 0014, ``Embedded Trace Macrocell, Architecture Specification''}.
+Be aware that most of the relevant registers are write-only,
+and that ETM resources are limited. There are only a handful
+of address comparators, data comparators, counters, and so on.
+
+Examples of scenarios you might arrange to trace include:
+
+@itemize
+@item Code flow within a function, @emph{excluding} subroutines
+it calls. Use address range comparators to enable tracing
+for instruction access within that function's body.
+@item Code flow within a function, @emph{including} subroutines
+it calls. Use the sequencer and address comparators to activate
+tracing on an ``entered function'' state, then deactivate it by
+exiting that state when the function's exit code is invoked.
+@item Code flow starting at the fifth invocation of a function,
+combining one of the above models with a counter.
+@item CPU data accesses to the registers for a particular device,
+using address range comparators and the ViewData logic.
+@item Such data accesses only during IRQ handling, combining the above
+model with sequencer triggers which on entry and exit to the IRQ handler.
+@item @emph{... more}
+@end itemize
+
+At this writing, September 2009, there are no Tcl utility
+procedures to help set up any common tracing scenarios.
+
@deffn Command {etm analyze}
Reads trace data into memory, if it wasn't already present.
Decodes and prints the data that was collected.
that is not currently supported in OpenOCD.)
@end deffn
-@deffn Command {armv4_5 disassemble} address count [thumb]
+@deffn Command {armv4_5 disassemble} address [count [@option{thumb}]]
@cindex disassemble
Disassembles @var{count} instructions starting at @var{address}.
-If @option{thumb} is specified, Thumb (16-bit) instructions are used;
+If @var{count} is not specified, a single instruction is disassembled.
+If @option{thumb} is specified, or the low bit of the address is set,
+Thumb (16-bit) instructions are used;
else ARM (32-bit) instructions are used.
(Processors may also support the Jazelle state, but
those instructions are not currently understood by OpenOCD.)
@deffn Command {armv4_5 reg}
Display a table of all banked core registers, fetching the current value from every
core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
-register value.
+register value.
@end deffn
@subsection ARM7 and ARM9 specific commands
@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+safe for all but ARM7TDMI--S cores (like Philips LPC).
+This feature is enabled by default on most ARM9 cores,
+including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
@deffn Command {arm7_9 dcc_downloads} (@option{enable}|@option{disable})
Enable or disable memory writes and reads that don't check completion of
the operation. This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
-speeds, like the 32kHz startup clock of an AT91RM9200.
+speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
and display the result.
@end deffn
-@subsection ARM9TDMI specific commands
-@cindex ARM9TDMI
+@subsection ARM9 specific commands
+@cindex ARM9
-Many ARM9-family CPUs are built around ARM9TDMI integer cores,
-or processors resembling ARM9TDMI, and can use these commands.
+ARM9-family cores are built around ARM9TDMI or ARM9E (including ARM9EJS)
+integer processors.
Such cores include the ARM920T, ARM926EJ-S, and ARM966.
+For historical reasons, one command shared by these cores starts
+with the @command{arm9tdmi} prefix.
+This is true even for ARM9E based processors, which implement the
+ARMv5TE architecture instead of ARMv4T.
+
@c 9-june-2009: tried this on arm920t, it didn't work.
@c no-params always lists nothing caught, and that's how it acts.
@anchor{arm9tdmi vector_catch}
@deffn Command {arm9tdmi vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
Vector Catch hardware provides a sort of dedicated breakpoint
for hardware events such as reset, interrupt, and abort.
You can use this to conserve normal breakpoint resources,
@subsection XScale specific commands
@cindex XScale
+Some notes about the debug implementation on the XScale CPUs:
+
+The XScale CPU provides a special debug-only mini-instruction cache
+(mini-IC) in which exception vectors and target-resident debug handler
+code are placed by OpenOCD. In order to get access to the CPU, OpenOCD
+must point vector 0 (the reset vector) to the entry of the debug
+handler. However, this means that the complete first cacheline in the
+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.
+
+It is recommended to place a pc-relative indirect branch in the vector
+table, and put the branch destination somewhere in memory. Doing so
+makes sure the code in the vector table stays constant regardless of
+code layout in memory:
+@example
+_vectors:
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ ldr pc,[pc,#0x100-8]
+ .org 0x100
+ .long real_reset_vector
+ .long real_ui_handler
+ .long real_swi_handler
+ .long real_pf_abort
+ .long real_data_abort
+ .long 0 /* unused */
+ .long real_irq_handler
+ .long real_fiq_handler
+@end example
+
+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.
+
+
These commands are available to XScale based CPUs,
which are implementations of the ARMv5TE architecture.
@anchor{xscale vector_catch}
@deffn Command {xscale vector_catch} [mask]
+@cindex vector_catch
Display a bitmask showing the hardware vectors to catch.
If the optional parameter is provided, first set the bitmask to that value.
+
+The mask bits correspond with bit 16..23 in the DCSR:
+@example
+0x01 Trap Reset
+0x02 Trap Undefined Instructions
+0x04 Trap Software Interrupt
+0x08 Trap Prefetch Abort
+0x10 Trap Data Abort
+0x20 reserved
+0x40 Trap IRQ
+0x80 Trap FIQ
+@end example
+@end deffn
+
+@anchor{xscale vector_table}
+@deffn Command {xscale vector_table} [<low|high> <index> <value>]
+@cindex vector_table
+
+Set an entry in the mini-IC vector table. There are two tables: one for
+low vectors (at 0x00000000), and one for high vectors (0xFFFF0000), each
+holding the 8 exception vectors. @var{index} can be 1-7, because vector 0
+points to the debug handler entry and can not be overwritten.
+@var{value} holds the 32-bit opcode that is placed in the mini-IC.
+
+Without arguments, the current settings are displayed.
+
@end deffn
@section ARMv6 Architecture
@subsection ARM11 specific commands
@cindex ARM11
-@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
-Read coprocessor register
+@deffn Command {arm11 mcr} pX opc1 CRn CRm opc2 value
+Write @var{value} to a coprocessor @var{pX} register
+passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MCR instruction.
+(The difference beween this and the MCR2 instruction is
+one bit in the encoding, effecively a fifth parameter.)
@end deffn
@deffn Command {arm11 memwrite burst} [value]
If @var{value} is defined, first assigns that.
@end deffn
-@deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
-Write coprocessor register
+@deffn Command {arm11 mrc} pX opc1 CRn CRm opc2
+Read a coprocessor @var{pX} register passing parameters @var{CRn},
+@var{CRm}, opcodes @var{opc1} and @var{opc2},
+and the MRC instruction.
+(The difference beween this and the MRC2 instruction is
+one bit in the encoding, effecively a fifth parameter.)
+Displays the result.
@end deffn
@deffn Command {arm11 no_increment} [value]
@deffn Command {arm11 step_irq_enable} [value]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
-they is disabled by default.
+they are disabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 vcr} [value]
+@cindex vector_catch
+Displays the value of the @emph{Vector Catch Register (VCR)},
+coprocessor 14 register 7.
If @var{value} is defined, first assigns that.
+
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+The specific bit values are core-specific (as in fact is using
+coprocessor 14 register 7 itself) but all current ARM11
+cores @emph{except the ARM1176} use the same six bits.
@end deffn
@section ARMv7 Architecture
If @var{value} is defined, first assigns that.
@end deffn
+@subsection ARMv7-A specific commands
+@cindex ARMv7-A
+
+@deffn Command {armv7a disassemble} address [count [@option{thumb}]]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+If @option{thumb} is specified, or the low bit of the address is set,
+Thumb2 (mixed 16/32-bit) instructions are used;
+else ARM (32-bit) instructions are used.
+With a handful of exceptions, ThumbEE instructions are the same as Thumb2;
+ThumbEE disassembly currently has no explicit support.
+(Processors may also support the Jazelle state, but
+those instructions are not currently understood by OpenOCD.)
+@end deffn
+
+
@subsection Cortex-M3 specific commands
@cindex Cortex-M3
+@deffn Command {cortex_m3 disassemble} address [count]
+@cindex disassemble
+Disassembles @var{count} Thumb2 instructions starting at @var{address}.
+If @var{count} is not specified, a single instruction is disassembled.
+@end deffn
+
@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
@end deffn
+@deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list]
+@cindex vector_catch
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+
+Parameters request interception of
+@option{all} of these hardware event vectors,
+@option{none} of them,
+or one or more of the following:
+@option{hard_err} for a HardFault exception;
+@option{mm_err} for a MemManage exception;
+@option{bus_err} for a BusFault exception;
+@option{irq_err},
+@option{state_err},
+@option{chk_err}, or
+@option{nocp_err} for various UsageFault exceptions; or
+@option{reset}.
+If NVIC setup code does not enable them,
+MemManage, BusFault, and UsageFault exceptions
+are mapped to HardFault.
+UsageFault checks for
+divide-by-zero and unaligned access
+must also be explicitly enabled.
+
+This finishes by listing the current vector catch configuration.
+@end deffn
+
@anchor{Software Debug Messages and Tracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
otherwise the libdcc format is used.
@end deffn
-@deffn Command {trace history} (@option{clear}|count)
+@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.
history records.
@end deffn
-@deffn Command {trace point} (@option{clear}|identifier)
+@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.
gdb_memory_map disable
@end example
For this to function correctly a valid flash configuration must also be set
-in OpenOCD. For faster performance you should also configure a valid
+in OpenOCD. For faster performance you should also configure a valid
working area.
Informing GDB of the memory map of the target will enable GDB to protect any
information as an argument to each proc.
There are three main types of return values: single value, name value
-pair list and lists.
+pair list and lists.
Name value pair. The proc 'foo' below returns a name/value pair
-list.
+list.
@verbatim
puts "Name: $name, Value: $value"
}
@end verbatim
-
+
Lists returned must be relatively small. Otherwise a range
should be passed in to the proc in question.
@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
variables. JimTCL, as implemented in OpenOCD creates $HostOS which
holds one of the following values:
-@itemize @bullet
+@itemize @bullet
@item @b{winxx} Built using Microsoft Visual Studio
@item @b{linux} Linux is the underlying operating sytem
@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
that ``deep sleeps'' at 32kHz between every keystroke. It can be
painful.
-@b{Solution #1 - A special circuit}
+@b{Solution #1 - A special circuit}
In order to make use of this, your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
time. One can set a break point or halt the system in the deep power
down code, slow step out until the system speeds up.
+Note that adaptive clocking may also need to work at the board level,
+when a board-level scan chain has multiple chips.
+Parallel clock voting schemes are good way to implement this,
+both within and between chips, and can easily be implemented
+with a CPLD.
+It's not difficult to have logic fan a module's input TCK signal out
+to each TAP in the scan chain, and then wait until each TAP's RTCK comes
+back with the right polarity before changing the output RTCK signal.
+Texas Instruments makes some clock voting logic available
+for free (with no support) in VHDL form; see
+@url{http://tiexpressdsp.com/index.php/Adaptive_Clocking}
+
@b{Solution #2 - Always works - but may be slower}
Often this is a perfectly acceptable solution.
In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
the target clock speed. But what that ``magic division'' is varies
-depending on the chips on your board. @b{ARM rule of thumb} Most ARM
-based systems require an 8:1 division. @b{Xilinx rule of thumb} is
-1/12 the clock speed.
+depending on the chips on your board.
+@b{ARM rule of thumb} Most ARM based systems require an 6:1 division;
+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.
sleep''. If you are careful - 98% of your problems can be debugged
this way.
+Note that on ARM you may need to avoid using the @emph{wait for interrupt}
+operation in your idle loops even if you don't otherwise change the CPU
+clock rate.
+That operation gates the CPU clock, and thus the JTAG clock; which
+prevents JTAG access. One consequence is not being able to @command{halt}
+cores which are executing that @emph{wait for interrupt} operation.
+
To set the JTAG frequency use the command:
@example
- # Example: 1.234MHz
- jtag_khz 1234
+# Example: 1.234MHz
+jtag_khz 1234
@end example
@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
-around Windows filenames.
+around Windows filenames.
@example
> echo \a
@item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
-memory read caused data abort".
+memory read caused data abort".
The errors are non-fatal, and are the result of GDB trying to trace stack frames
beyond the last valid frame. It might be possible to prevent this by setting up
@b{Also note:} If you have a multi-threaded operating system, they
often do not @b{in the intrest of saving memory} waste these few
-bytes. Painful...
+bytes. Painful...
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
@node Tcl Crash Course
@chapter Tcl Crash Course
-@cindex Tcl
+@cindex Tcl
Not everyone knows Tcl - this is not intended to be a replacement for
learning Tcl, the intent of this chapter is to give you some idea of
Commands are executed like this:
-@enumerate
+@enumerate
@item Parse the next line into (argc) and (argv[]).
@item Look up (argv[0]) in a table and call its function.
@item Repeat until End Of File.
@enumerate
@item The SET command creates 2 variables, X and Y.
@item The double [nested] EXPR command performs math
-@* The EXPR command produces numerical result as a string.
+@* The EXPR command produces numerical result as a string.
@* Refer to Rule #1
@item The format command is executed, producing a single string
@* Refer to Rule #1.
#4 DANGER DANGER DANGER
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
@end example
-@enumerate
+@enumerate
@item The $_TARGETNAME is an OpenOCD variable convention.
@*@b{$_TARGETNAME} represents the last target created, the value changes
each time a new target is created. Remember the parsing rules. When
OpenOCD comes with a target configuration script library. These scripts can be
used as-is or serve as a starting point.
-The target library is published together with the OpenOCD executable and
+The target library is published together with the OpenOCD executable and
the path to the target library is in the OpenOCD script search path.
-Similarly there are example scripts for configuring the JTAG interface.
+Similarly there are example scripts for configuring the JTAG interface.
The command line below uses the example parport configuration script
that ship with OpenOCD, then configures the str710.cfg target and
Code Review / openocd.git / blobdiff