1491 lines
58 KiB
Plaintext
1491 lines
58 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
||
@c %**start of header
|
||
@setfilename openocd.info
|
||
@settitle Open On-Chip Debugger (OpenOCD)
|
||
@dircategory Development
|
||
@direntry
|
||
* OpenOCD: (openocd). Open On-Chip Debugger.
|
||
@end direntry
|
||
@c %**end of header
|
||
|
||
@include version.texi
|
||
|
||
@copying
|
||
Copyright @copyright{} 2007-2008 Spen @email{spen@@spen-soft.co.uk}
|
||
@quotation
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.2 or
|
||
any later version published by the Free Software Foundation; with no
|
||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
||
Texts. A copy of the license is included in the section entitled ``GNU
|
||
Free Documentation License''.
|
||
@end quotation
|
||
@end copying
|
||
|
||
@titlepage
|
||
@title Open On-Chip Debugger (OpenOCD)
|
||
@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
|
||
@subtitle @value{UPDATED}
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
@insertcopying
|
||
@end titlepage
|
||
|
||
@contents
|
||
|
||
@node Top, About, , (dir)
|
||
@top OpenOCD
|
||
|
||
This manual documents edition @value{EDITION} of the Open On-Chip Debugger
|
||
(OpenOCD) version @value{VERSION}, @value{UPDATED}.
|
||
|
||
@insertcopying
|
||
|
||
@menu
|
||
* About:: About OpenOCD.
|
||
* Developers:: OpenOCD developers
|
||
* Building:: Building OpenOCD
|
||
* Running:: Running OpenOCD
|
||
* Configuration:: OpenOCD Configuration.
|
||
* Target library:: Target library
|
||
* Commands:: OpenOCD Commands
|
||
* Sample Scripts:: Sample Target Scripts
|
||
* GDB and OpenOCD:: Using GDB and OpenOCD
|
||
* Upgrading:: Deprecated/Removed Commands
|
||
* FAQ:: Frequently Asked Questions
|
||
* License:: GNU Free Documentation License
|
||
* Index:: Main index.
|
||
@end menu
|
||
|
||
@node About
|
||
@unnumbered About
|
||
@cindex about
|
||
|
||
The Open On-Chip Debugger (OpenOCD) aims to provide debugging, in-system programming
|
||
and boundary-scan testing for embedded target devices. The targets are interfaced
|
||
using JTAG (IEEE 1149.1) compliant hardware, but this may be extended to other
|
||
connection types in the future.
|
||
|
||
OpenOCD currently supports Wiggler (clones), FTDI FT2232 based JTAG interfaces, the
|
||
Amontec JTAG Accelerator, and the Gateworks GW1602. It allows ARM7 (ARM7TDMI and ARM720t),
|
||
ARM9 (ARM920t, ARM922t, ARM926ej--s, ARM966e--s), XScale (PXA25x, IXP42x) and
|
||
Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be debugged.
|
||
|
||
Flash writing is supported for external CFI compatible flashes (Intel and AMD/Spansion
|
||
command set) and several internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3
|
||
and STM32x). Preliminary support for using the LPC3180's NAND flash controller is included.
|
||
|
||
@node Developers
|
||
@chapter Developers
|
||
@cindex developers
|
||
|
||
OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
|
||
University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
|
||
Others interested in improving the state of free and open debug and testing technology
|
||
are welcome to participate.
|
||
|
||
Other developers have contributed support for additional targets and flashes as well
|
||
as numerous bugfixes and enhancements. See the AUTHORS file for regular contributors.
|
||
|
||
The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}
|
||
|
||
@node Building
|
||
@chapter Building
|
||
@cindex building OpenOCD
|
||
|
||
You can download the current SVN version with 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):
|
||
|
||
@smallexample
|
||
svn checkout svn://svn.berlios.de/openocd/trunk openocd
|
||
@end smallexample
|
||
|
||
Building OpenOCD requires a recent version of the GNU autotools.
|
||
On my build system, I'm using autoconf 2.13 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})
|
||
@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
|
||
homepage (@uref{www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
|
||
@end itemize
|
||
|
||
libftdi is supported under windows. Versions earlier than 0.13 will require patching.
|
||
see contrib/libftdi for more details.
|
||
|
||
In general, the D2XX driver provides superior performance (several times as fast),
|
||
but has the draw-back of being binary-only - though that isn't that bad, as it isn't
|
||
a kernel module, only a user space library.
|
||
|
||
To build OpenOCD (on both Linux and Cygwin), use the following commands:
|
||
@smallexample
|
||
./bootstrap
|
||
@end smallexample
|
||
Bootstrap generates the configure script, and prepares building on your system.
|
||
@smallexample
|
||
./configure
|
||
@end smallexample
|
||
Configure generates the Makefiles used to build OpenOCD.
|
||
@smallexample
|
||
make
|
||
@end smallexample
|
||
Make builds OpenOCD, and places the final executable in ./src/.
|
||
|
||
The configure script takes several options, specifying which JTAG interfaces
|
||
should be included:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@option{--enable-parport}
|
||
@item
|
||
@option{--enable-parport_ppdev}
|
||
@item
|
||
@option{--enable-parport_giveio}
|
||
@item
|
||
@option{--enable-amtjtagaccel}
|
||
@item
|
||
@option{--enable-ft2232_ftd2xx}
|
||
@footnote{Using the latest D2XX drivers from FTDI and following their installation
|
||
instructions, I had to use @option{--enable-ft2232_libftd2xx} for OpenOCD to
|
||
build properly.}
|
||
@item
|
||
@option{--enable-ft2232_libftdi}
|
||
@item
|
||
@option{--with-ftd2xx=/path/to/d2xx/}
|
||
@item
|
||
@option{--enable-gw16012}
|
||
@item
|
||
@option{--enable-usbprog}
|
||
@item
|
||
@option{--enable-presto_libftdi}
|
||
@item
|
||
@option{--enable-presto_ftd2xx}
|
||
@end itemize
|
||
|
||
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).
|
||
|
||
Cygwin users have to specify the location of the FTDI D2XX package. This should be an
|
||
absolute path containing no spaces.
|
||
|
||
Linux users should copy the various parts of the D2XX package to the appropriate
|
||
locations, i.e. /usr/include, /usr/lib.
|
||
|
||
@node Running
|
||
@chapter Running
|
||
@cindex running OpenOCD
|
||
@cindex --configfile
|
||
@cindex --debug_level
|
||
@cindex --logfile
|
||
@cindex --search
|
||
OpenOCD runs as a daemon, waiting for connections from clients (Telnet or GDB).
|
||
Run with @option{--help} or @option{-h} to view the available command line switches.
|
||
|
||
It reads its configuration by default from the file openocd.cfg located in the current
|
||
working directory. This may be overwritten with the @option{-f <configfile>} command line
|
||
switch. The @option{-f} command line switch can be specified multiple times, in which case the config files
|
||
are executed in order.
|
||
|
||
Also it is possible to interleave commands w/config scripts using the @option{-c} command line switch.
|
||
|
||
To enable debug output (when reporting problems or working on OpenOCD itself), use
|
||
the @option{-d} command line switch. This sets the debug_level to "3", outputting
|
||
the most information, including debug messages. The default setting is "2", outputting
|
||
only informational messages, warnings and errors. You can also change this setting
|
||
from within a telnet or gdb session (@option{debug_level <n>}).
|
||
|
||
You can redirect all output from the daemon to a file using the @option{-l <logfile>} switch.
|
||
|
||
Search paths for config/script files can be added to OpenOCD by using
|
||
the @option{-s <search>} switch. The current directory and the OpenOCD target library
|
||
is in the search path by default.
|
||
|
||
Note! OpenOCD will launch the GDB & telnet server even if it can not establish a connection
|
||
with the target. In general, it is possible for the JTAG controller to be unresponsive until
|
||
the target is set up correctly via e.g. GDB monitor commands in a GDB init script.
|
||
|
||
@node Configuration
|
||
@chapter Configuration
|
||
@cindex configuration
|
||
OpenOCD runs as a daemon, and reads it current configuration
|
||
by default from the file openocd.cfg in the current directory. A different configuration
|
||
file can be specified with the @option{-f <conf.file>} command line switch specified when starting OpenOCD.
|
||
|
||
The configuration file is used to specify on which ports the daemon listens for new
|
||
connections, the JTAG interface used to connect to the target, the layout of the JTAG
|
||
chain, the targets that should be debugged, and connected flashes.
|
||
|
||
@section Daemon configuration
|
||
|
||
@itemize @bullet
|
||
@item @b{init} This command terminates the configuration stage and enters the normal
|
||
command mode. This can be useful to add commands to the startup scripts and commands
|
||
such as resetting the target, programming flash, etc. To reset the CPU upon startup,
|
||
add "init" and "reset" at the end of the config script or at the end of the
|
||
OpenOCD command line using the @option{-c} command line switch.
|
||
@cindex init
|
||
@item @b{telnet_port} <@var{number}>
|
||
@cindex telnet_port
|
||
Port on which to listen for incoming telnet connections
|
||
@item @b{gdb_port} <@var{number}>
|
||
@cindex gdb_port
|
||
First port on which to listen for incoming GDB connections. The GDB port for the
|
||
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
|
||
@item @b{gdb_detach} <@var{resume|reset|halt|nothing}>
|
||
@cindex gdb_detach
|
||
Configures what OpenOCD will do when gdb detaches from the daeman.
|
||
Default behaviour is <@var{resume}>
|
||
@item @b{gdb_memory_map} <@var{enable|disable}>
|
||
@cindex gdb_memory_map
|
||
Set to <@var{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. @option{gdb_flash_program enable} will also need enabling
|
||
for flash programming to work.
|
||
Default behaviour is <@var{disable}>
|
||
@item @b{gdb_flash_program} <@var{enable|disable}>
|
||
@cindex gdb_flash_program
|
||
Set to <@var{enable}> to cause OpenOCD to program the flash memory when a
|
||
vFlash packet is received.
|
||
Default behaviour is <@var{enable}>
|
||
@item @b{daemon_startup} <@var{mode}>
|
||
@cindex daemon_startup
|
||
@option{mode} can either @option{attach} or @option{reset}
|
||
This is equivalent to adding "init" and "reset" to the end of the config script.
|
||
|
||
It is available as a command mainly for backwards compatibility.
|
||
@end itemize
|
||
|
||
@section JTAG interface configuration
|
||
|
||
@itemize @bullet
|
||
@item @b{interface} <@var{name}>
|
||
@cindex interface
|
||
Use the interface driver <@var{name}> to connect to the target. Currently supported
|
||
interfaces are
|
||
@itemize @minus
|
||
@item @b{parport}
|
||
PC parallel port bit-banging (Wigglers, PLD download cable, ...)
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{amt_jtagaccel}
|
||
Amontec Chameleon in its JTAG Accelerator configuration connected to a PC's EPP
|
||
mode parallel port
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{ft2232}
|
||
FTDI FT2232 based devices using either the open-source libftdi or the binary only
|
||
FTD2XX driver. The FTD2XX is superior in performance, but not available on every
|
||
platform. The libftdi uses libusb, and should be portable to all systems that provide
|
||
libusb.
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{ep93xx}
|
||
Cirrus Logic EP93xx based single-board computer bit-banging (in development)
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{presto}
|
||
ASIX PRESTO USB JTAG programmer.
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{usbprog}
|
||
usbprog is a freely programmable USB adapter.
|
||
@end itemize
|
||
@itemize @minus
|
||
@item @b{gw16012}
|
||
Gateworks GW16012 JTAG programmer.
|
||
@end itemize
|
||
@end itemize
|
||
|
||
@itemize @bullet
|
||
@item @b{jtag_speed} <@var{reset speed}> <@var{post reset speed}>
|
||
@cindex jtag_speed
|
||
Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum
|
||
speed. The actual effect of this option depends on the JTAG interface used. Reset
|
||
speed is used during reset and post reset speed after reset. post reset speed
|
||
is optional, in which case the reset speed is used.
|
||
@itemize @minus
|
||
|
||
@item wiggler: maximum speed / @var{number}
|
||
@item ft2232: 6MHz / (@var{number}+1)
|
||
@item amt jtagaccel: 8 / 2**@var{number}
|
||
@end itemize
|
||
|
||
Note: Make sure the jtag clock is no more than @math{1/6th <20> CPU-Clock}. This is
|
||
especially true for synthesized cores (-S).
|
||
|
||
@item @b{jtag_khz} <@var{reset speed kHz}> <@var{post reset speed kHz}>
|
||
@cindex jtag_khz
|
||
Same as jtag_speed, except that the speed is specified in maximum kHz. If
|
||
the device can not support the rate asked for, or can not translate from
|
||
kHz to jtag_speed, then an error is returned. 0 means RTCK. If RTCK
|
||
is not supported, then an error is reported.
|
||
|
||
@item @b{reset_config} <@var{signals}> [@var{combination}] [@var{trst_type}] [@var{srst_type}]
|
||
@cindex reset_config
|
||
The configuration of the reset signals available on the JTAG interface AND the target.
|
||
If the JTAG interface provides SRST, but the target doesn't connect that signal properly,
|
||
then OpenOCD can't use it. <@var{signals}> can be @option{none}, @option{trst_only},
|
||
@option{srst_only} or @option{trst_and_srst}.
|
||
|
||
[@var{combination}] is an optional value specifying broken reset signal implementations.
|
||
@option{srst_pulls_trst} states that the testlogic is reset together with the reset of
|
||
the system (e.g. Philips LPC2000, "broken" board layout), @option{trst_pulls_srst} says
|
||
that the system is reset together with the test logic (only hypothetical, I haven't
|
||
seen hardware with such a bug, and can be worked around).
|
||
@option{combined} imples both @option{srst_pulls_trst} and @option{trst_pulls_srst}.
|
||
The default behaviour if no option given is @option{separate}.
|
||
|
||
The [@var{trst_type}] and [@var{srst_type}] parameters allow the driver type of the
|
||
reset lines to be specified. Possible values are @option{trst_push_pull} (default)
|
||
and @option{trst_open_drain} for the test reset signal, and @option{srst_open_drain}
|
||
(default) and @option{srst_push_pull} for the system reset. These values only affect
|
||
JTAG interfaces with support for different drivers, like the Amontec JTAGkey and JTAGAccelerator.
|
||
|
||
@item @b{jtag_device} <@var{IR length}> <@var{IR capture}> <@var{IR mask}> <@var{IDCODE instruction}>
|
||
@cindex jtag_device
|
||
Describes the devices that form the JTAG daisy chain, with the first device being
|
||
the one closest to TDO. The parameters are the length of the instruction register
|
||
(4 for all ARM7/9s), the value captured during Capture-IR (0x1 for ARM7/9), and a mask
|
||
of bits that should be validated when doing IR scans (all four bits (0xf) for ARM7/9).
|
||
The IDCODE instruction will in future be used to query devices for their JTAG
|
||
identification code. This line is the same for all ARM7 and ARM9 devices.
|
||
Other devices, like CPLDs, require different parameters. An example configuration
|
||
line for a Xilinx XC9500 CPLD would look like this:
|
||
@smallexample
|
||
jtag_device 8 0x01 0x0e3 0xfe
|
||
@end smallexample
|
||
The instruction register (IR) is 8 bits long, during Capture-IR 0x01 is loaded into
|
||
the IR, but only bits 0-1 and 5-7 should be checked, the others (2-4) might vary.
|
||
The IDCODE instruction is 0xfe.
|
||
|
||
@item @b{jtag_nsrst_delay} <@var{ms}>
|
||
@cindex jtag_nsrst_delay
|
||
How long (in milliseconds) OpenOCD should wait after deasserting nSRST before
|
||
starting new JTAG operations.
|
||
@item @b{jtag_ntrst_delay} <@var{ms}>
|
||
@cindex jtag_ntrst_delay
|
||
How long (in milliseconds) OpenOCD should wait after deasserting nTRST before
|
||
starting new JTAG operations.
|
||
|
||
The jtag_n[st]rst_delay options are useful if reset circuitry (like a reset supervisor,
|
||
or on-chip features) keep a reset line asserted for some time after the external reset
|
||
got deasserted.
|
||
@end itemize
|
||
|
||
@section parport options
|
||
|
||
@itemize @bullet
|
||
@item @b{parport_port} <@var{number}>
|
||
@cindex parport_port
|
||
Either the address of the I/O port (default: 0x378 for LPT1) or the number of
|
||
the @file{/dev/parport} device
|
||
|
||
When using PPDEV to access the parallel port, use the number of the parallel port:
|
||
@option{parport_port 0} (the default). If @option{parport_port 0x378} is specified
|
||
you may encounter a problem.
|
||
@item @b{parport_cable} <@var{name}>
|
||
@cindex parport_cable
|
||
The layout of the parallel port cable used to connect to the target.
|
||
Currently supported cables are
|
||
@itemize @minus
|
||
@item @b{wiggler}
|
||
@cindex wiggler
|
||
The original Wiggler layout, also supported by several clones, such
|
||
as the Olimex ARM-JTAG
|
||
@item @b{old_amt_wiggler}
|
||
@cindex old_amt_wiggler
|
||
The Wiggler configuration that comes with Amontec's Chameleon Programmer. The new
|
||
version available from the website uses the original Wiggler layout ('@var{wiggler}')
|
||
@item @b{chameleon}
|
||
@cindex chameleon
|
||
The Amontec Chameleon's CPLD when operated in configuration mode. This is only used to program the Chameleon itself, not a connected target.
|
||
@item @b{dlc5}
|
||
@cindex dlc5
|
||
The Xilinx Parallel cable III.
|
||
@item @b{triton}
|
||
@cindex triton
|
||
The parallel port adapter found on the 'Karo Triton 1 Development Board'.
|
||
This is also the layout used by the HollyGates design
|
||
(see @uref{http://www.lartmaker.nl/projects/jtag/}).
|
||
@item @b{flashlink}
|
||
@cindex flashlink
|
||
The ST Parallel cable.
|
||
@end itemize
|
||
@item @b{parport_write_on_exit} <@var{on|off}>
|
||
@cindex parport_write_on_exit
|
||
This will configure the parallel driver to write a known value to the parallel
|
||
interface on exiting OpenOCD
|
||
@end itemize
|
||
|
||
@section amt_jtagaccel options
|
||
@itemize @bullet
|
||
@item @b{parport_port} <@var{number}>
|
||
@cindex parport_port
|
||
Either the address of the I/O port (default: 0x378 for LPT1) or the number of the
|
||
@file{/dev/parport} device
|
||
@end itemize
|
||
@section ft2232 options
|
||
|
||
@itemize @bullet
|
||
@item @b{ft2232_device_desc} <@var{description}>
|
||
@cindex ft2232_device_desc
|
||
The USB device description of the FTDI FT2232 device. If not specified, the FTDI
|
||
default value is used. This setting is only valid if compiled with FTD2XX support.
|
||
@item @b{ft2232_layout} <@var{name}>
|
||
@cindex ft2232_layout
|
||
The layout of the FT2232 GPIO signals used to control output-enables and reset
|
||
signals. Valid layouts are
|
||
@itemize @minus
|
||
@item @b{usbjtag}
|
||
"USBJTAG-1" layout described in the original OpenOCD diploma thesis
|
||
@item @b{jtagkey}
|
||
Amontec JTAGkey and JTAGkey-tiny
|
||
@item @b{signalyzer}
|
||
Signalyzer
|
||
@item @b{olimex-jtag}
|
||
Olimex ARM-USB-OCD
|
||
@item @b{m5960}
|
||
American Microsystems M5960
|
||
@item @b{evb_lm3s811}
|
||
Luminary Micro EVB_LM3S811 as a JTAG interface (not onboard processor), no TRST or
|
||
SRST signals on external connector
|
||
@item @b{comstick}
|
||
Hitex STR9 comstick
|
||
@item @b{stm32stick}
|
||
Hitex STM32 Performance Stick
|
||
@item @b{flyswatter}
|
||
Tin Can Tools Flyswatter
|
||
@item @b{turtelizer2}
|
||
egnite Software turtelizer2
|
||
@item @b{oocdlink}
|
||
OOCDLink
|
||
@end itemize
|
||
|
||
@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
|
||
The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI
|
||
default values are used. Multiple <@var{vid}>, <@var{pid}> pairs may be given, eg.
|
||
@smallexample
|
||
ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003
|
||
@end smallexample
|
||
@item @b{ft2232_latency} <@var{ms}>
|
||
On some systems using ft2232 based JTAG interfaces the FT_Read function call in
|
||
ft2232_read() fails to return the expected number of bytes. This can be caused by
|
||
USB communication delays and has proved hard to reproduce and debug. Setting the
|
||
FT2232 latency timer to a larger value increases delays for short USB packages but it
|
||
also reduces the risk of timeouts before receiving the expected number of bytes.
|
||
The OpenOCD default value is 2 and for some systems a value of 10 has proved useful.
|
||
@end itemize
|
||
|
||
@section ep93xx options
|
||
@cindex ep93xx options
|
||
Currently, there are no options available for the ep93xx interface.
|
||
|
||
@page
|
||
@section Target configuration
|
||
|
||
@itemize @bullet
|
||
@item @b{target} <@var{type}> <@var{endianess}> <@var{reset_mode}> <@var{JTAG pos}>
|
||
<@var{variant}>
|
||
@cindex target
|
||
Defines a target that should be debugged. Currently supported types are:
|
||
@itemize @minus
|
||
@item @b{arm7tdmi}
|
||
@item @b{arm720t}
|
||
@item @b{arm9tdmi}
|
||
@item @b{arm920t}
|
||
@item @b{arm922t}
|
||
@item @b{arm926ejs}
|
||
@item @b{arm966e}
|
||
@item @b{cortex_m3}
|
||
@item @b{feroceon}
|
||
@item @b{xscale}
|
||
@end itemize
|
||
|
||
If you want to use a target board that is not on this list, see Adding a new
|
||
target board
|
||
|
||
Endianess may be @option{little} or @option{big}.
|
||
|
||
The reset_mode specifies what should happen to the target when a reset occurs:
|
||
@itemize @minus
|
||
@item @b{reset_halt}
|
||
@cindex reset_halt
|
||
Immediately request a target halt after reset. This allows targets to be debugged
|
||
from the very first instruction. This is only possible with targets and JTAG
|
||
interfaces that correctly implement the reset signals.
|
||
@item @b{reset_init}
|
||
@cindex reset_init
|
||
Similar to @option{reset_halt}, but executes the script file defined to handle the
|
||
'reset' event for the target. Like @option{reset_halt} this only works with
|
||
correct reset implementations.
|
||
@item @b{reset_run}
|
||
@cindex reset_run
|
||
Simply let the target run after a reset.
|
||
@item @b{run_and_halt}
|
||
@cindex run_and_halt
|
||
Let the target run for some time (default: 1s), and then request halt.
|
||
@item @b{run_and_init}
|
||
@cindex run_and_init
|
||
A combination of @option{reset_init} and @option{run_and_halt}. The target is allowed
|
||
to run for some time, then halted, and the @option{reset} event script is executed.
|
||
@end itemize
|
||
|
||
On JTAG interfaces / targets where system reset and test-logic reset can't be driven
|
||
completely independent (like the LPC2000 series), or where the JTAG interface is
|
||
unavailable for some time during startup (like the STR7 series), you can't use
|
||
@option{reset_halt} or @option{reset_init}.
|
||
|
||
@item @b{target_script} <@var{target#}> <@var{event}> <@var{script_file}>
|
||
@cindex target_script
|
||
Event is either @option{reset}, @option{post_halt}, @option{pre_resume} or @option{gdb_program_config}
|
||
|
||
TODO: describe exact semantic of events
|
||
@item @b{run_and_halt_time} <@var{target#}> <@var{time_in_ms}>
|
||
@cindex run_and_halt_time
|
||
The amount of time the debugger should wait after releasing reset before it asserts
|
||
a debug request. This is used by the @option{run_and_halt} and @option{run_and_init}
|
||
reset modes.
|
||
@item @b{working_area} <@var{target#}> <@var{address}> <@var{size}>
|
||
<@var{backup}|@var{nobackup}>
|
||
@cindex working_area
|
||
Specifies a working area for the debugger to use. This may be used to speed-up
|
||
downloads to target memory and flash operations, or to perform otherwise unavailable
|
||
operations (some coprocessor operations on ARM7/9 systems, for example). The last
|
||
parameter decides whether the memory should be preserved (<@var{backup}>) or can simply be overwritten (<@var{nobackup}>). If possible, use
|
||
a working_area that doesn't need to be backed up, as performing a backup slows down operation.
|
||
@end itemize
|
||
|
||
@subsection arm7tdmi options
|
||
@cindex arm7tdmi options
|
||
target arm7tdmi <@var{endianess}> <@var{reset_mode}> <@var{jtag#}>
|
||
The arm7tdmi target definition requires at least one additional argument, specifying
|
||
the position of the target in the JTAG daisy-chain. The first JTAG device is number 0.
|
||
The optional [@var{variant}] parameter has been removed in recent versions.
|
||
The correct feature set is determined at runtime.
|
||
|
||
@subsection arm720t options
|
||
@cindex arm720t options
|
||
ARM720t options are similar to ARM7TDMI options.
|
||
|
||
@subsection arm9tdmi options
|
||
@cindex arm9tdmi options
|
||
ARM9TDMI options are similar to ARM7TDMI options. Supported variants are
|
||
@option{arm920t}, @option{arm922t} and @option{arm940t}.
|
||
This enables the hardware single-stepping support found on these cores.
|
||
|
||
@subsection arm920t options
|
||
@cindex arm920t options
|
||
ARM920t options are similar to ARM9TDMI options.
|
||
|
||
@subsection arm966e options
|
||
@cindex arm966e options
|
||
ARM966e options are similar to ARM9TDMI options.
|
||
|
||
@subsection cortex_m3 options
|
||
@cindex cortex_m3 options
|
||
use variant <@var{variant}> @option{lm3s} when debugging luminary lm3s targets. This will cause
|
||
openocd to use a software reset rather than asserting SRST to avoid a issue with clearing
|
||
the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest, these revisions will
|
||
be detected and the normal reset behaviour used.
|
||
|
||
@subsection xscale options
|
||
@cindex xscale options
|
||
Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},
|
||
@option{pxa250}, @option{pxa255}, @option{pxa26x}.
|
||
|
||
@section Flash configuration
|
||
@cindex Flash configuration
|
||
|
||
@itemize @bullet
|
||
@item @b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
|
||
<@var{bus_width}> <@var{target#}> [@var{driver_options ...}]
|
||
@cindex flash bank
|
||
Configures a flash bank at <@var{base}> of <@var{size}> bytes and <@var{chip_width}>
|
||
and <@var{bus_width}> bytes using the selected flash <driver>.
|
||
@end itemize
|
||
|
||
@subsection lpc2000 options
|
||
@cindex lpc2000 options
|
||
|
||
@b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
|
||
<@var{clock}> [@var{calc_checksum}]
|
||
LPC flashes don't require the chip and bus width to be specified. Additional
|
||
parameters are the <@var{variant}>, which may be @var{lpc2000_v1} (older LPC21xx and LPC22xx)
|
||
or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx), the number
|
||
of the target this flash belongs to (first is 0), the frequency at which the core
|
||
is currently running (in kHz - must be an integral number), and the optional keyword
|
||
@var{calc_checksum}, telling the driver to calculate a valid checksum for the exception
|
||
vector table.
|
||
|
||
@subsection cfi options
|
||
@cindex cfi options
|
||
|
||
@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
|
||
<@var{target#}>
|
||
CFI flashes require the number of the target they're connected to as an additional
|
||
argument. The CFI driver makes use of a working area (specified for the target)
|
||
to significantly speed up operation.
|
||
|
||
@var{chip_width} and @var{bus_width} are specified in bytes.
|
||
|
||
@subsection at91sam7 options
|
||
@cindex at91sam7 options
|
||
|
||
@b{flash bank at91sam7} 0 0 0 0 <@var{target#}>
|
||
AT91SAM7 flashes only require the @var{target#}, all other values are looked up after
|
||
reading the chip-id and type.
|
||
|
||
@subsection str7 options
|
||
@cindex str7 options
|
||
|
||
@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
|
||
variant can be either STR71x, STR73x or STR75x.
|
||
|
||
@subsection str9 options
|
||
@cindex str9 options
|
||
|
||
@b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
|
||
The str9 needs the flash controller to be configured prior to Flash programming, eg.
|
||
@smallexample
|
||
str9x flash_config 0 4 2 0 0x80000
|
||
@end smallexample
|
||
This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively.
|
||
|
||
@subsection str9 options (str9xpec driver)
|
||
|
||
@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target#}>
|
||
Before using the flash commands the turbo mode will need enabling using str9xpec
|
||
@option{enable_turbo} <@var{num>.}
|
||
|
||
Only use this driver for locking/unlocking the device or configuring the option bytes.
|
||
Use the standard str9 driver for programming.
|
||
|
||
@subsection stellaris (LM3Sxxx) options
|
||
@cindex stellaris (LM3Sxxx) options
|
||
|
||
@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target#}>
|
||
stellaris flash plugin only require the @var{target#}.
|
||
|
||
@subsection stm32x options
|
||
@cindex stm32x options
|
||
|
||
@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
|
||
stm32x flash plugin only require the @var{target#}.
|
||
|
||
@node Target library
|
||
@chapter Target library
|
||
@cindex Target library
|
||
|
||
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 path to the target library is in the OpenOCD script search path.
|
||
Similarly there are example scripts for configuring the JTAG interface.
|
||
|
||
The command line below uses the example parport configuration scripts
|
||
that ship with OpenOCD, then configures the str710.cfg target and
|
||
finally issues the init and reset command. The communication speed
|
||
is set to 10kHz for reset and 8MHz for post reset.
|
||
|
||
|
||
@smallexample
|
||
openocd -f interface/parport.cfg -c "jtag_khz 10 8000" -f target/str710.cfg -c "init" -c "reset"
|
||
@end smallexample
|
||
|
||
|
||
To list the target scripts available:
|
||
|
||
@smallexample
|
||
$ ls /usr/local/lib/openocd/target
|
||
|
||
arm7_fast.cfg lm3s6965.cfg pxa255.cfg stm32.cfg xba_revA3.cfg
|
||
at91eb40a.cfg lpc2148.cfg pxa255_sst.cfg str710.cfg zy1000.cfg
|
||
at91r40008.cfg lpc2294.cfg sam7s256.cfg str912.cfg
|
||
at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg
|
||
@end smallexample
|
||
|
||
|
||
@node Commands
|
||
@chapter Commands
|
||
@cindex commands
|
||
|
||
OpenOCD allows user interaction through a telnet interface
|
||
(default: port 4444) and a GDB server (default: port 3333). The command line interpreter
|
||
is available from both the telnet interface and a GDB session. To issue commands to the
|
||
interpreter from within a GDB session, use the @option{monitor} command, e.g. use
|
||
@option{monitor poll} to issue the @option{poll} command. All output is relayed through the
|
||
GDB session.
|
||
|
||
@section Daemon
|
||
|
||
@itemize @bullet
|
||
@item @b{sleep} <@var{msec}>
|
||
@cindex sleep
|
||
Wait for n milliseconds before resuming. Useful in connection with script files
|
||
(@var{script} command and @var{target_script} configuration).
|
||
|
||
@item @b{shutdown}
|
||
@cindex shutdown
|
||
Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet).
|
||
|
||
@item @b{debug_level} [@var{n}]
|
||
@cindex debug_level
|
||
Display or adjust debug level to n<0-3>
|
||
|
||
@item @b{fast} [@var{enable/disable}]
|
||
@cindex fast
|
||
Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory
|
||
downloads and fast memory access will work if the JTAG interface isn't too fast and
|
||
the core doesn't run at a too low frequency. Note that this option only changes the default
|
||
and that the indvidual options, like DCC memory downloads, can be enabled and disabled
|
||
individually.
|
||
|
||
The target specific "dangerous" optimisation tweaking options may come and go
|
||
as more robust and user friendly ways are found to ensure maximum throughput
|
||
and robustness with a minimum of configuration.
|
||
|
||
Typically the "fast enable" is specified first on the command line:
|
||
|
||
@smallexample
|
||
openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
|
||
@end smallexample
|
||
|
||
@item @b{log_output} <@var{file}>
|
||
@cindex log_output
|
||
Redirect logging to <file> (default: stderr)
|
||
|
||
@item @b{script} <@var{file}>
|
||
@cindex script
|
||
Execute commands from <file>
|
||
|
||
@end itemize
|
||
|
||
@subsection Target state handling
|
||
@itemize @bullet
|
||
@item @b{poll} [@option{on}|@option{off}]
|
||
@cindex poll
|
||
Poll the target for its current state. If the target is in debug mode, architecture
|
||
specific information about the current state is printed. An optional parameter
|
||
allows continuous polling to be enabled and disabled.
|
||
|
||
@item @b{halt} [@option{ms}]
|
||
@cindex halt
|
||
Send a halt request to the target and wait for it to halt for up to [@option{ms}] milliseconds.
|
||
Default [@option{ms}] is 5 seconds if no arg given.
|
||
Optional arg @option{ms} is a timeout in milliseconds. Using 0 as the [@option{ms}]
|
||
will stop OpenOCD from waiting.
|
||
|
||
@item @b{wait_halt} [@option{ms}]
|
||
@cindex wait_halt
|
||
Wait for the target to enter debug mode. Optional [@option{ms}] is
|
||
a timeout in milliseconds. Default [@option{ms}] is 5 seconds if no
|
||
arg given.
|
||
|
||
@item @b{resume} [@var{address}]
|
||
@cindex resume
|
||
Resume the target at its current code position, or at an optional address.
|
||
OpenOCD will wait 5 seconds for the target to resume.
|
||
|
||
@item @b{step} [@var{address}]
|
||
@cindex step
|
||
Single-step the target at its current code position, or at an optional address.
|
||
|
||
@item @b{reset} [@option{run}|@option{halt}|@option{init}|@option{run_and_halt}
|
||
|@option{run_and_init}]
|
||
@cindex reset
|
||
Perform a hard-reset. The optional parameter specifies what should happen after the reset.
|
||
This optional parameter overrides the setting specified in the configuration file,
|
||
making the new behaviour the default for the @option{reset} command.
|
||
@itemize @minus
|
||
@item @b{run}
|
||
@cindex reset run
|
||
Let the target run.
|
||
@item @b{halt}
|
||
@cindex reset halt
|
||
Immediately halt the target (works only with certain configurations).
|
||
@item @b{init}
|
||
@cindex reset init
|
||
Immediately halt the target, and execute the reset script (works only with certain
|
||
configurations)
|
||
@item @b{run_and_halt}
|
||
@cindex reset run_and_halt
|
||
Let the target run for a certain amount of time, then request a halt.
|
||
@item @b{run_and_init}
|
||
@cindex reset run_and_init
|
||
Let the target run for a certain amount of time, then request a halt. Execute the
|
||
reset script once the target enters debug mode.
|
||
@end itemize
|
||
@end itemize
|
||
|
||
@subsection Memory access commands
|
||
These commands allow accesses of a specific size to the memory system:
|
||
@itemize @bullet
|
||
@item @b{mdw} <@var{addr}> [@var{count}]
|
||
@cindex mdw
|
||
display memory words
|
||
@item @b{mdh} <@var{addr}> [@var{count}]
|
||
@cindex mdh
|
||
display memory half-words
|
||
@item @b{mdb} <@var{addr}> [@var{count}]
|
||
@cindex mdb
|
||
display memory bytes
|
||
@item @b{mww} <@var{addr}> <@var{value}>
|
||
@cindex mww
|
||
write memory word
|
||
@item @b{mwh} <@var{addr}> <@var{value}>
|
||
@cindex mwh
|
||
write memory half-word
|
||
@item @b{mwb} <@var{addr}> <@var{value}>
|
||
@cindex mwb
|
||
write memory byte
|
||
|
||
@item @b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
|
||
@cindex load_image
|
||
Load image <@var{file}> to target memory at <@var{address}>
|
||
@item @b{dump_image} <@var{file}> <@var{address}> <@var{size}>
|
||
@cindex dump_image
|
||
Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
|
||
(binary) <@var{file}>.
|
||
@item @b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
|
||
@cindex verify_image
|
||
Verify <@var{file}> against target memory starting at <@var{address}>.
|
||
This will first attempt comparison using a crc checksum, if this fails it will try a binary compare.
|
||
@end itemize
|
||
|
||
@subsection Flash commands
|
||
@cindex Flash commands
|
||
@itemize @bullet
|
||
@item @b{flash banks}
|
||
@cindex flash banks
|
||
List configured flash banks
|
||
@item @b{flash info} <@var{num}>
|
||
@cindex flash info
|
||
Print info about flash bank <@option{num}>
|
||
@item @b{flash probe} <@var{num}>
|
||
@cindex flash probe
|
||
Identify the flash, or validate the parameters of the configured flash. Operation
|
||
depends on the flash type.
|
||
@item @b{flash erase_check} <@var{num}>
|
||
@cindex flash erase_check
|
||
Check erase state of sectors in flash bank <@var{num}>. This is the only operation that
|
||
updates the erase state information displayed by @option{flash info}. That means you have
|
||
to issue an @option{erase_check} command after erasing or programming the device to get
|
||
updated information.
|
||
@item @b{flash protect_check} <@var{num}>
|
||
@cindex flash protect_check
|
||
Check protection state of sectors in flash bank <num>.
|
||
@option{flash erase_sector} using the same syntax.
|
||
@item @b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
|
||
@cindex flash erase_sector
|
||
Erase sectors at bank <@var{num}>, starting at sector <@var{first}> up to and including
|
||
<@var{last}>. Sector numbering starts at 0. Depending on the flash type, erasing may
|
||
require the protection to be disabled first (e.g. Intel Advanced Bootblock flash using
|
||
the CFI driver).
|
||
@item @b{flash erase_address} <@var{address}> <@var{length}>
|
||
@cindex flash erase_address
|
||
Erase sectors starting at <@var{address}> for <@var{length}> bytes
|
||
@item @b{flash write_bank} <@var{num}> <@var{file}> <@var{offset}>
|
||
@cindex flash write_bank
|
||
Write the binary <@var{file}> to flash bank <@var{num}>, starting at
|
||
<@option{offset}> bytes from the beginning of the bank.
|
||
@item @b{flash write_image} [@var{erase}] <@var{file}> [@var{offset}] [@var{type}]
|
||
@cindex flash write_image
|
||
Write the image <@var{file}> to the current target's flash bank(s). A relocation
|
||
[@var{offset}] can be specified and the file [@var{type}] can be specified
|
||
explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf}
|
||
(ELF file) or @option{s19} (Motorola s19). Flash memory will be erased prior to programming
|
||
if the @option{erase} parameter is given.
|
||
@item @b{flash protect} <@var{num}> <@var{first}> <@var{last}> <@option{on}|@option{off}>
|
||
@cindex flash protect
|
||
Enable (@var{on}) or disable (@var{off}) protection of flash sectors <@var{first}> to
|
||
<@var{last}> of @option{flash bank} <@var{num}>.
|
||
@end itemize
|
||
|
||
@page
|
||
@section Target Specific Commands
|
||
@cindex Target Specific Commands
|
||
|
||
@subsection AT91SAM7 specific commands
|
||
@cindex AT91SAM7 specific commands
|
||
The flash configuration is deduced from the chip identification register. The flash
|
||
controller handles erases automatically on a page (128/265 byte) basis so erase is
|
||
not necessary for flash programming. AT91SAM7 processors with less than 512K flash
|
||
only have a single flash bank embedded on chip. AT91SAM7xx512 have two flash planes
|
||
that can be erased separatly. Only an EraseAll command is supported by the controller
|
||
for each flash plane and this is called with
|
||
@itemize @bullet
|
||
@item @b{flash erase} <@var{num}> @var{first_plane} @var{last_plane}
|
||
bulk erase flash planes first_plane to last_plane.
|
||
@item @b{at91sam7 gpnvm} <@var{num}> <@var{bit}> <@option{set}|@option{clear}>
|
||
@cindex at91sam7 gpnvm
|
||
set or clear a gpnvm bit for the processor
|
||
@end itemize
|
||
|
||
@subsection STR9 specific commands
|
||
@cindex STR9 specific commands
|
||
These are flash specific commands when using the str9xpec driver.
|
||
@itemize @bullet
|
||
@item @b{str9xpec enable_turbo} <@var{num}>
|
||
@cindex str9xpec enable_turbo
|
||
enable turbo mode, simply this will remove the str9 from the chain and talk
|
||
directly to the embedded flash controller.
|
||
@item @b{str9xpec disable_turbo} <@var{num}>
|
||
@cindex str9xpec disable_turbo
|
||
restore the str9 into jtag chain.
|
||
@item @b{str9xpec lock} <@var{num}>
|
||
@cindex str9xpec lock
|
||
lock str9 device. The str9 will only respond to an unlock command that will
|
||
erase the device.
|
||
@item @b{str9xpec unlock} <@var{num}>
|
||
@cindex str9xpec unlock
|
||
unlock str9 device.
|
||
@item @b{str9xpec options_read} <@var{num}>
|
||
@cindex str9xpec options_read
|
||
read str9 option bytes.
|
||
@item @b{str9xpec options_write} <@var{num}>
|
||
@cindex str9xpec options_write
|
||
write str9 option bytes.
|
||
@end itemize
|
||
|
||
@subsection STR9 configuration
|
||
@cindex STR9 configuration
|
||
@itemize @bullet
|
||
@item @b{str9x flash_config} <@var{bank}> <@var{BBSR}> <@var{NBBSR}>
|
||
<@var{BBADR}> <@var{NBBADR}>
|
||
@cindex str9x flash_config
|
||
Configure str9 flash controller.
|
||
@smallexample
|
||
eg. str9x flash_config 0 4 2 0 0x80000
|
||
This will setup
|
||
BBSR - Boot Bank Size register
|
||
NBBSR - Non Boot Bank Size register
|
||
BBADR - Boot Bank Start Address register
|
||
NBBADR - Boot Bank Start Address register
|
||
@end smallexample
|
||
@end itemize
|
||
|
||
@subsection STR9 option byte configuration
|
||
@cindex STR9 option byte configuration
|
||
@itemize @bullet
|
||
@item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
|
||
@cindex str9xpec options_cmap
|
||
configure str9 boot bank.
|
||
@item @b{str9xpec options_lvdthd} <@var{num}> <@option{2.4v}|@option{2.7v}>
|
||
@cindex str9xpec options_lvdthd
|
||
configure str9 lvd threshold.
|
||
@item @b{str9xpec options_lvdsel} <@var{num}> <@option{vdd}|@option{vdd_vddq}>
|
||
@cindex str9xpec options_lvdsel
|
||
configure str9 lvd source.
|
||
@item @b{str9xpec options_lvdwarn} <@var{bank}> <@option{vdd}|@option{vdd_vddq}>
|
||
@cindex str9xpec options_lvdwarn
|
||
configure str9 lvd reset warning source.
|
||
@end itemize
|
||
|
||
@subsection STM32x specific commands
|
||
@cindex STM32x specific commands
|
||
|
||
These are flash specific commands when using the stm32x driver.
|
||
@itemize @bullet
|
||
@item @b{stm32x lock} <@var{num}>
|
||
@cindex stm32x lock
|
||
lock stm32 device.
|
||
@item @b{stm32x unlock} <@var{num}>
|
||
@cindex stm32x unlock
|
||
unlock stm32 device.
|
||
@item @b{stm32x options_read} <@var{num}>
|
||
@cindex stm32x options_read
|
||
read stm32 option bytes.
|
||
@item @b{stm32x options_write} <@var{num}> <@option{SWWDG}|@option{HWWDG}>
|
||
<@option{RSTSTNDBY}|@option{NORSTSTNDBY}> <@option{RSTSTOP}|@option{NORSTSTOP}>
|
||
@cindex stm32x options_write
|
||
write stm32 option bytes.
|
||
@item @b{stm32x mass_erase} <@var{num}>
|
||
@cindex stm32x mass_erase
|
||
mass erase flash memory.
|
||
@end itemize
|
||
|
||
@page
|
||
@section Architecture Specific Commands
|
||
@cindex Architecture Specific Commands
|
||
|
||
@subsection ARMV4/5 specific commands
|
||
@cindex ARMV4/5 specific commands
|
||
|
||
These commands are specific to ARM architecture v4 and v5, like all ARM7/9 systems
|
||
or Intel XScale (XScale isn't supported yet).
|
||
@itemize @bullet
|
||
@item @b{armv4_5 reg}
|
||
@cindex armv4_5 reg
|
||
Display a list 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.
|
||
@item @b{armv4_5 core_mode} [@var{arm}|@var{thumb}]
|
||
@cindex armv4_5 core_mode
|
||
Displays the core_mode, optionally changing it to either ARM or Thumb mode.
|
||
The target is resumed in the currently set @option{core_mode}.
|
||
@end itemize
|
||
|
||
@subsection ARM7/9 specific commands
|
||
@cindex ARM7/9 specific commands
|
||
|
||
These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t,
|
||
ARM920t or ARM926EJ-S.
|
||
@itemize @bullet
|
||
@item @b{arm7_9 sw_bkpts} <@var{enable}|@var{disable}>
|
||
@cindex arm7_9 sw_bkpts
|
||
Enable/disable use of software breakpoints. On ARMv4 systems, this reserves
|
||
one of the watchpoint registers to implement software breakpoints. Disabling
|
||
SW Bkpts frees that register again.
|
||
@item @b{arm7_9 force_hw_bkpts} <@var{enable}|@var{disable}>
|
||
@cindex arm7_9 force_hw_bkpts
|
||
When @option{force_hw_bkpts} is enabled, the @option{sw_bkpts} support is disabled, and all
|
||
breakpoints are turned into hardware breakpoints.
|
||
@item @b{arm7_9 dbgrq} <@var{enable}|@var{disable}>
|
||
@cindex arm7_9 dbgrq
|
||
Enable use of the DBGRQ bit to force entry into debug mode. This should be
|
||
safe for all but ARM7TDMI--S cores (like Philips LPC).
|
||
@item @b{arm7_9 fast_memory_access} <@var{enable}|@var{disable}>
|
||
@cindex arm7_9 fast_memory_access
|
||
Allow OpenOCD to read and write memory without checking 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 a very low
|
||
speed, like the 32kHz startup clock of an AT91RM9200.
|
||
@item @b{arm7_9 dcc_downloads} <@var{enable}|@var{disable}>
|
||
@cindex arm7_9 dcc_downloads
|
||
Enable the use of the debug communications channel (DCC) to write larger (>128 byte)
|
||
amounts of memory. DCC downloads offer a huge speed increase, but might be potentially
|
||
unsafe, especially with targets running at a very low speed. This command was introduced
|
||
with OpenOCD rev. 60.
|
||
@end itemize
|
||
|
||
@subsection ARM720T specific commands
|
||
@cindex ARM720T specific commands
|
||
|
||
@itemize @bullet
|
||
@item @b{arm720t cp15} <@var{num}> [@var{value}]
|
||
@cindex arm720t cp15
|
||
display/modify cp15 register <@option{num}> [@option{value}].
|
||
@item @b{arm720t md<bhw>_phys} <@var{addr}> [@var{count}]
|
||
@cindex arm720t md<bhw>_phys
|
||
Display memory at physical address addr.
|
||
@item @b{arm720t mw<bhw>_phys} <@var{addr}> <@var{value}>
|
||
@cindex arm720t mw<bhw>_phys
|
||
Write memory at physical address addr.
|
||
@item @b{arm720t virt2phys} <@var{va}>
|
||
@cindex arm720t virt2phys
|
||
Translate a virtual address to a physical address.
|
||
@end itemize
|
||
|
||
@subsection ARM9TDMI specific commands
|
||
@cindex ARM9TDMI specific commands
|
||
|
||
@itemize @bullet
|
||
@item @b{arm9tdmi vector_catch} <@var{all}|@var{none}>
|
||
@cindex arm9tdmi vector_catch
|
||
Catch arm9 interrupt vectors, can be @option{all} @option{none} or any of the following:
|
||
@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
|
||
@option{irq} @option{fiq}.
|
||
|
||
Can also be used on other arm9 based cores, arm966, arm920t and arm926ejs.
|
||
@end itemize
|
||
|
||
@subsection ARM966E specific commands
|
||
@cindex ARM966E specific commands
|
||
|
||
@itemize @bullet
|
||
@item @b{arm966e cp15} <@var{num}> [@var{value}]
|
||
@cindex arm966e cp15
|
||
display/modify cp15 register <@option{num}> [@option{value}].
|
||
@end itemize
|
||
|
||
@subsection ARM920T specific commands
|
||
@cindex ARM920T specific commands
|
||
|
||
@itemize @bullet
|
||
@item @b{arm920t cp15} <@var{num}> [@var{value}]
|
||
@cindex arm920t cp15
|
||
display/modify cp15 register <@option{num}> [@option{value}].
|
||
@item @b{arm920t cp15i} <@var{num}> [@var{value}] [@var{address}]
|
||
@cindex arm920t cp15i
|
||
display/modify cp15 (interpreted access) <@option{opcode}> [@option{value}] [@option{address}]
|
||
@item @b{arm920t cache_info}
|
||
@cindex arm920t cache_info
|
||
Print information about the caches found. This allows you to see if your target
|
||
is a ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
|
||
@item @b{arm920t md<bhw>_phys} <@var{addr}> [@var{count}]
|
||
@cindex arm920t md<bhw>_phys
|
||
Display memory at physical address addr.
|
||
@item @b{arm920t mw<bhw>_phys} <@var{addr}> <@var{value}>
|
||
@cindex arm920t mw<bhw>_phys
|
||
Write memory at physical address addr.
|
||
@item @b{arm920t read_cache} <@var{filename}>
|
||
@cindex arm920t read_cache
|
||
Dump the content of ICache and DCache to a file.
|
||
@item @b{arm920t read_mmu} <@var{filename}>
|
||
@cindex arm920t read_mmu
|
||
Dump the content of the ITLB and DTLB to a file.
|
||
@item @b{arm920t virt2phys} <@var{va}>
|
||
@cindex arm920t virt2phys
|
||
Translate a virtual address to a physical address.
|
||
@end itemize
|
||
|
||
@subsection ARM926EJS specific commands
|
||
@cindex ARM926EJS specific commands
|
||
|
||
@itemize @bullet
|
||
@item @b{arm926ejs cp15} <@var{num}> [@var{value}]
|
||
@cindex arm926ejs cp15
|
||
display/modify cp15 register <@option{num}> [@option{value}].
|
||
@item @b{arm926ejs cache_info}
|
||
@cindex arm926ejs cache_info
|
||
Print information about the caches found.
|
||
@item @b{arm926ejs md<bhw>_phys} <@var{addr}> [@var{count}]
|
||
@cindex arm926ejs md<bhw>_phys
|
||
Display memory at physical address addr.
|
||
@item @b{arm926ejs mw<bhw>_phys} <@var{addr}> <@var{value}>
|
||
@cindex arm926ejs mw<bhw>_phys
|
||
Write memory at physical address addr.
|
||
@item @b{arm926ejs virt2phys} <@var{va}>
|
||
@cindex arm926ejs virt2phys
|
||
Translate a virtual address to a physical address.
|
||
@end itemize
|
||
|
||
@page
|
||
@section Debug commands
|
||
@cindex Debug commands
|
||
The following commands give direct access to the core, and are most likely
|
||
only useful while debugging OpenOCD.
|
||
@itemize @bullet
|
||
@item @b{arm7_9 write_xpsr} <@var{32-bit value}> <@option{0=cpsr}, @option{1=spsr}>
|
||
@cindex arm7_9 write_xpsr
|
||
Immediately write either the current program status register (CPSR) or the saved
|
||
program status register (SPSR), without changing the register cache (as displayed
|
||
by the @option{reg} and @option{armv4_5 reg} commands).
|
||
@item @b{arm7_9 write_xpsr_im8} <@var{8-bit value}> <@var{rotate 4-bit}>
|
||
<@var{0=cpsr},@var{1=spsr}>
|
||
@cindex arm7_9 write_xpsr_im8
|
||
Write the 8-bit value rotated right by 2*rotate bits, using an immediate write
|
||
operation (similar to @option{write_xpsr}).
|
||
@item @b{arm7_9 write_core_reg} <@var{num}> <@var{mode}> <@var{value}>
|
||
@cindex arm7_9 write_core_reg
|
||
Write a core register, without changing the register cache (as displayed by the
|
||
@option{reg} and @option{armv4_5 reg} commands). The <@var{mode}> argument takes the
|
||
encoding of the [M4:M0] bits of the PSR.
|
||
@end itemize
|
||
|
||
@page
|
||
@section JTAG commands
|
||
@cindex JTAG commands
|
||
@itemize @bullet
|
||
@item @b{scan_chain}
|
||
@cindex scan_chain
|
||
Print current scan chain configuration.
|
||
@item @b{jtag_reset} <@var{trst}> <@var{srst}>
|
||
@cindex jtag_reset
|
||
Toggle reset lines.
|
||
@item @b{endstate} <@var{tap_state}>
|
||
@cindex endstate
|
||
Finish JTAG operations in <@var{tap_state}>.
|
||
@item @b{runtest} <@var{num_cycles}>
|
||
@cindex runtest
|
||
Move to Run-Test/Idle, and execute <@var{num_cycles}>
|
||
@item @b{statemove} [@var{tap_state}]
|
||
@cindex statemove
|
||
Move to current endstate or [@var{tap_state}]
|
||
@item @b{irscan} <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
|
||
@cindex irscan
|
||
Execute IR scan <@var{device}> <@var{instr}> [@var{dev2}] [@var{instr2}] ...
|
||
@item @b{drscan} <@var{device}> [@var{dev2}] [@var{var2}] ...
|
||
@cindex drscan
|
||
Execute DR scan <@var{device}> [@var{dev2}] [@var{var2}] ...
|
||
@item @b{verify_ircapture} <@option{enable}|@option{disable}>
|
||
@cindex verify_ircapture
|
||
Verify value captured during Capture-IR. Default is enabled.
|
||
@item @b{var} <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
|
||
@cindex var
|
||
Allocate, display or delete variable <@var{name}> [@var{num_fields}|@var{del}] [@var{size1}] ...
|
||
@item @b{field} <@var{var}> <@var{field}> [@var{value}|@var{flip}]
|
||
@cindex field
|
||
Display/modify variable field <@var{var}> <@var{field}> [@var{value}|@var{flip}].
|
||
@end itemize
|
||
|
||
@page
|
||
@section Target Requests
|
||
@cindex Target Requests
|
||
OpenOCD can handle certain target requests, currently debugmsg are only supported for arm7_9 and cortex_m3.
|
||
See libdcc in the contrib dir for more details.
|
||
@itemize @bullet
|
||
@item @b{target_request debugmsgs} <@var{enable}|@var{disable}>
|
||
@cindex target_request debugmsgs
|
||
Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running.
|
||
@end itemize
|
||
|
||
@node Sample Scripts
|
||
@chapter Sample Scripts
|
||
@cindex scripts
|
||
|
||
This page shows how to use the target library.
|
||
|
||
The configuration script can be divided in the following section:
|
||
@itemize @bullet
|
||
@item daemon configuration
|
||
@item interface
|
||
@item jtag scan chain
|
||
@item target configuration
|
||
@item flash configuration
|
||
@end itemize
|
||
|
||
Detailed information about each section can be found at OpenOCD configuration.
|
||
|
||
@section AT91R40008 example
|
||
@cindex AT91R40008 example
|
||
To start OpenOCD with a target script for the AT91R40008 CPU and reset
|
||
the CPU upon startup of the OpenOCD daemon.
|
||
@smallexample
|
||
openocd -f interface/parport.cfg -f target/at91r40008.cfg -c init -c reset
|
||
@end smallexample
|
||
|
||
|
||
@node GDB and OpenOCD
|
||
@chapter GDB and OpenOCD
|
||
@cindex GDB and OpenOCD
|
||
OpenOCD complies with the remote gdbserver protocol, and as such can be used
|
||
to debug remote targets.
|
||
|
||
@section Connecting to gdb
|
||
@cindex Connecting to gdb
|
||
A connection is typically started as follows:
|
||
@smallexample
|
||
target remote localhost:3333
|
||
@end smallexample
|
||
This would cause gdb to connect to the gdbserver on the local pc using port 3333.
|
||
|
||
To see a list of available OpenOCD commands type @option{monitor help} on the
|
||
gdb commandline.
|
||
|
||
OpenOCD supports the gdb @option{qSupported} packet, this enables information
|
||
to be sent by the gdb server (openocd) to gdb. Typical information includes
|
||
packet size and device memory map.
|
||
|
||
Previous versions of OpenOCD required the following gdb options to increase
|
||
the packet size and speed up gdb communication.
|
||
@smallexample
|
||
set remote memory-write-packet-size 1024
|
||
set remote memory-write-packet-size fixed
|
||
set remote memory-read-packet-size 1024
|
||
set remote memory-read-packet-size fixed
|
||
@end smallexample
|
||
This is now handled in the @option{qSupported} PacketSize.
|
||
|
||
@section Programming using gdb
|
||
@cindex Programming using gdb
|
||
|
||
By default the target memory map is sent to gdb, this can be disabled by
|
||
the following OpenOCD config option:
|
||
@smallexample
|
||
gdb_memory_map disable
|
||
@end smallexample
|
||
For this to function correctly a valid flash config must also be configured
|
||
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
|
||
flash area of the target and use hardware breakpoints by default. This means
|
||
that the OpenOCD option @option{arm7_9 force_hw_bkpts} is not required when
|
||
using a memory map.
|
||
|
||
To view the configured memory map in gdb, use the gdb command @option{info mem}
|
||
All other unasigned addresses within gdb are treated as RAM.
|
||
|
||
GDB 6.8 and higher set any memory area not in the memory map as inaccessible,
|
||
this can be changed to the old behaviour by using the following gdb command.
|
||
@smallexample
|
||
set mem inaccessible-by-default off
|
||
@end smallexample
|
||
|
||
If @option{gdb_flash_program enable} is also used, gdb will be able to
|
||
program any flash memory using the vFlash interface.
|
||
|
||
gdb will look at the target memory map when a load command is given, if any
|
||
areas to be programmed lie within the target flash area the vFlash packets
|
||
will be used.
|
||
|
||
If the target needs configuring before gdb programming, a script can be executed.
|
||
@smallexample
|
||
target_script 0 gdb_program_config config.script
|
||
@end smallexample
|
||
|
||
To verify any flash programming the gdb command @option{compare-sections}
|
||
can be used.
|
||
|
||
@node Upgrading
|
||
@chapter Deprecated/Removed Commands
|
||
@cindex Deprecated/Removed Commands
|
||
Certain OpenOCD commands have been deprecated/removed during the various revisions.
|
||
|
||
@itemize @bullet
|
||
@item @b{load_binary}
|
||
@cindex load_binary
|
||
use @option{load_image} command with same args
|
||
@item @b{dump_binary}
|
||
@cindex dump_binary
|
||
use @option{dump_image} command with same args
|
||
@item @b{flash erase}
|
||
@cindex flash erase
|
||
use @option{flash erase_sector} command with same args
|
||
@item @b{flash write}
|
||
@cindex flash write
|
||
use @option{flash write_bank} command with same args
|
||
@item @b{flash write_binary}
|
||
@cindex flash write_binary
|
||
use @option{flash write_bank} command with same args
|
||
@item @b{arm7_9 fast_writes}
|
||
@cindex arm7_9 fast_writes
|
||
use @option{arm7_9 fast_memory_access} command with same args
|
||
@item @b{flash auto_erase}
|
||
@cindex flash auto_erase
|
||
use @option{flash write_image} command passing @option{erase} as the first parameter.
|
||
@end itemize
|
||
|
||
@node FAQ
|
||
@chapter FAQ
|
||
@cindex faq
|
||
@enumerate
|
||
@item OpenOCD complains about a missing cygwin1.dll.
|
||
|
||
Make sure you have Cygwin installed, or at least a version of OpenOCD that
|
||
claims to come with all the necessary dlls. When using Cygwin, try launching
|
||
OpenOCD from the Cygwin shell.
|
||
|
||
@item I'm trying to set a breakpoint using GDB (or a frontend like Insight or
|
||
Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
|
||
arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
|
||
|
||
GDB issues software breakpoints when a normal breakpoint is requested, or to implement
|
||
source-line single-stepping. On ARMv4T systems, like ARM7TDMI, ARM720t or ARM920t,
|
||
software breakpoints consume one of the two available hardware breakpoints,
|
||
and are therefore disabled by default. If your code is running from RAM, you
|
||
can enable software breakpoints with the @option{arm7_9 sw_bkpts enable} command. If
|
||
your code resides in Flash, you can't use software breakpoints, but you can force
|
||
OpenOCD to use hardware breakpoints instead: @option{arm7_9 force_hw_bkpts enable}.
|
||
|
||
@item When erasing or writing LPC2000 on-chip flash, the operation fails sometimes
|
||
and works sometimes fine.
|
||
|
||
Make sure the core frequency specified in the @option{flash lpc2000} line matches the
|
||
clock at the time you're programming the flash. If you've specified the crystal's
|
||
frequency, make sure the PLL is disabled, if you've specified the full core speed
|
||
(e.g. 60MHz), make sure the PLL is enabled.
|
||
|
||
@item When debugging using an Amontec Chameleon in its JTAG Accelerator configuration,
|
||
I keep getting "Error: amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel timed
|
||
out while waiting for end of scan, rtck was disabled".
|
||
|
||
Make sure your PC's parallel port operates in EPP mode. You might have to try several
|
||
settings in your PC BIOS (ECP, EPP, and different versions of those).
|
||
|
||
@item 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".
|
||
|
||
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
|
||
a proper "initial" stack frame, if you happen to know what exactly has to
|
||
be done, feel free to add this here.
|
||
|
||
@item I get the following message in the OpenOCD console (or log file):
|
||
"Warning: arm7_9_common.c:679 arm7_9_assert_reset(): srst resets test logic, too".
|
||
|
||
This warning doesn't indicate any serious problem, as long as you don't want to
|
||
debug your core right out of reset. Your .cfg file specified @option{jtag_reset
|
||
trst_and_srst srst_pulls_trst} to tell OpenOCD that either your board,
|
||
your debugger or your target uC (e.g. LPC2000) can't assert the two reset signals
|
||
independently. With this setup, it's not possible to halt the core right out of
|
||
reset, everything else should work fine.
|
||
|
||
@item When using OpenOCD in conjunction with Amontec JTAGkey and the Yagarto
|
||
Toolchain (Eclipse, arm-elf-gcc, arm-elf-gdb), the debugging seems to be
|
||
unstable. When single-stepping over large blocks of code, GDB and OpenOCD
|
||
quit with an error message. Is there a stability issue with OpenOCD?
|
||
|
||
No, this is not a stability issue concerning OpenOCD. Most users have solved
|
||
this issue by simply using a self-powered USB hub, which they connect their
|
||
Amontec JTAGkey to. Apparently, some computers do not provide a USB power
|
||
supply stable enough for the Amontec JTAGkey to be operated.
|
||
|
||
@item When using the Amontec JTAGkey, sometimes OpenOCD crashes with the
|
||
following error messages: "Error: ft2232.c:201 ft2232_read(): FT_Read returned:
|
||
4" and "Error: ft2232.c:365 ft2232_send_and_recv(): couldn't read from FT2232".
|
||
What does that mean and what might be the reason for this?
|
||
|
||
First of all, the reason might be the USB power supply. Try using a self-powered
|
||
hub instead of a direct connection to your computer. Secondly, the error code 4
|
||
corresponds to an FT_IO_ERROR, which means that the driver for the FTDI USB
|
||
chip ran into some sort of error - this points us to a USB problem.
|
||
|
||
@item When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following
|
||
error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054".
|
||
What does that mean and what might be the reason for this?
|
||
|
||
Error code 10054 corresponds to WSAECONNRESET, which means that the debugger (GDB)
|
||
has closed the connection to OpenOCD. This might be a GDB issue.
|
||
|
||
@item In the configuration file in the section where flash device configurations
|
||
are described, there is a parameter for specifying the clock frequency for
|
||
LPC2000 internal flash devices (e.g.
|
||
@option{flash bank lpc2000 0x0 0x40000 0 0 0 lpc2000_v1 14746 calc_checksum}),
|
||
which must be specified in kilohertz. However, I do have a quartz crystal of a
|
||
frequency that contains fractions of kilohertz (e.g. 14,745,600 Hz, i.e. 14,745.600 kHz).
|
||
Is it possible to specify real numbers for the clock frequency?
|
||
|
||
No. The clock frequency specified here must be given as an integral number.
|
||
However, this clock frequency is used by the In-Application-Programming (IAP)
|
||
routines of the LPC2000 family only, which seems to be very tolerant concerning
|
||
the given clock frequency, so a slight difference between the specified clock
|
||
frequency and the actual clock frequency will not cause any trouble.
|
||
|
||
@item Do I have to keep a specific order for the commands in the configuration file?
|
||
|
||
Well, yes and no. Commands can be given in arbitrary order, yet the devices
|
||
listed for the JTAG scan chain must be given in the right order (jtag_device),
|
||
with the device closest to the TDO-Pin being listed first. In general,
|
||
whenever objects of the same type exist which require an index number, then
|
||
these objects must be given in the right order (jtag_devices, targets and flash
|
||
banks - a target references a jtag_device and a flash bank references a target).
|
||
|
||
@item Sometimes my debugging session terminates with an error. When I look into the
|
||
log file, I can see these error messages: Error: arm7_9_common.c:561
|
||
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
|
||
|
||
TODO.
|
||
|
||
@end enumerate
|
||
|
||
@include fdl.texi
|
||
|
||
@node Index
|
||
@unnumbered Index
|
||
|
||
@printindex cp
|
||
|
||
@bye
|