-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename openocd.info
-@settitle Open On-Chip Debugger (OpenOCD)
+@settitle OpenOCD User's Guide
@dircategory Development
@direntry
-@paragraphindent 0
-* OpenOCD: (openocd). Open On-Chip Debugger.
+* OpenOCD: (openocd). OpenOCD User's Guide
@end direntry
+@paragraphindent 0
@c %**end of header
@include version.texi
@copying
+This User's Guide documents
+release @value{VERSION},
+dated @value{UPDATED},
+of the Open On-Chip Debugger (OpenOCD).
+
@itemize @bullet
@item Copyright @copyright{} 2008 The OpenOCD Project
@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@end copying
@titlepage
-@title Open On-Chip Debugger (OpenOCD)
-@subtitle Edition @value{EDITION} for OpenOCD version @value{VERSION}
+@titlefont{@emph{Open On-Chip Debugger:}}
+@sp 1
+@title OpenOCD User's Guide
+@subtitle for release @value{VERSION}
@subtitle @value{UPDATED}
+
@page
@vskip 0pt plus 1filll
@insertcopying
@summarycontents
@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}.
+@ifnottex
+@node Top
+@top OpenOCD User's Guide
@insertcopying
+@end ifnottex
@menu
* About:: About OpenOCD
* Reset Configuration:: Reset Configuration
* Tap Creation:: Tap Creation
* Target Configuration:: Target Configuration
-* Flash Configuration:: Flash Configuration
+* Flash Commands:: Flash Commands
* NAND Flash Commands:: NAND Flash Commands
* General Commands:: General Commands
* JTAG Commands:: JTAG Commands
* FAQ:: Frequently Asked Questions
* Tcl Crash Course:: Tcl Crash Course
* License:: GNU Free Documentation License
+
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
* OpenOCD Concept Index:: Concept Index
-* OpenOCD Command Index:: Command Index
+* Command and Driver Index:: Command and Driver Index
@end menu
@node About
@b{GDB Debug:} 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
+Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
@uref{http://openocd.berlios.de/web/}
+@section Latest User's Guide:
+
+The user's guide you are now reading may not be the latest one
+available. A version for more recent code may be available.
+Its HTML form is published irregularly at:
+
+@uref{http://openocd.berlios.de/doc/}
+
+PDF form is likewise published at:
+
+@uref{http://openocd.berlios.de/doc/pdf/}
+
+@section OpenOCD User's Forum
+
+There is an OpenOCD forum (phpBB) hosted by SparkFun:
+
+@uref{http://forum.sparkfun.com/viewforum.php?f=18}
+
@node Developers
@chapter OpenOCD Developer Resources
The OpenOCD Developer Mailing List provides the primary means of
communication between developers:
- @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
All drivers developers are enouraged to also subscribe to the list of
SVN commits to keep pace with the ongoing changes:
- @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+@uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+
@node Building OpenOCD
@chapter Building OpenOCD
svn checkout svn://svn.berlios.de/openocd/trunk openocd
@end example
-Building OpenOCD requires a recent version of the GNU autotools (autoconf >= 2.59 and automake >= 1.9).
+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
@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{http://www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
+homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
@end itemize
libftdi is supported under Windows. Do not use versions earlier than 0.14.
@item
@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
@item
-@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
+@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} - Linux only. Equivalent of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
+@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 (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@item
Below is an example build process:
-1) Check out the latest version of ``openocd'' from SVN.
+@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.
-2) Download & unpack either the Windows or Linux FTD2xx drivers
- (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
+@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
- /home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents.
- /home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents.
+./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
@end example
-3) Configure with these options:
+@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
-Cygwin FTDICHIP solution:
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
-
-Linux FTDICHIP solution:
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
-
-Cygwin/Linux LIBFTDI solution:
- Assumes:
- 1a) For Windows: The Windows port of LIBUSB is in place.
- 1b) For Linux: libusb has been built/installed and is in place.
-
- 2) And libftdi has been built and installed
- Note: libftdi - relies upon libusb.
-
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_libftdi
-
+./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_libftdi
@end example
+@end enumerate
-4) Then just type ``make'', and perhaps ``make install''.
+@item Then just type ``make'', and perhaps ``make install''.
+@end enumerate
@section Miscellaneous Configure Options
There are many USB JTAG dongles on the market, many of them are based
on a chip from ``Future Technology Devices International'' (FTDI)
-known as the FTDI FT2232.
-
-See: @url{http://www.ftdichip.com} or @url{http://www.ftdichip.com/Products/FT2232H.htm}
+known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
+See: @url{http://www.ftdichip.com} for more information.
+In summer 2009, USB high speed (480 Mbps) versions of these FTDI
+chips are starting to become available in JTAG adapters.
As of 28/Nov/2008, the following are supported:
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
-@* See: @url{http://www.luminarymicro.com} - The Luminary Micro Stellaris LM3S811 eval board has an FTD2232C chip built in.
+@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
-@* See: @url{http://www.ethernut.de}, or @url{http://www.ethernut.de/en/hardware/turtelizer/index.html}
+@* See:
+@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
+@url{http://www.ethernut.de}
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
@* Link @url{http://www.hitex.com/stm32-stick}
@item @b{axm0432_jtag}
@* Axiom AXM-0432 Link @url{http://www.axman.com}
+@item @b{cortino}
+@* Link @url{http://www.hitex.com/index.php?id=cortino}
@end itemize
@section USB JLINK based
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
@item @b{Wiggler2}
-@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
+@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
+Improved parallel-port wiggler-style JTAG adapter}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@* Unknown.
@item @b{Lattice}
-@* ispDownload from Lattice Semiconductor @url{http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf}
+@* ispDownload from Lattice Semiconductor
+@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
@item @b{flashlink}
-@* From ST Microsystems, link:
-@url{http://www.st.com/stonline/products/literature/um/7889.pdf}
-Title: FlashLINK JTAG programing cable for PSD and uPSD
+@* From ST Microsystems;
+@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
+FlashLINK JTAG programing cable for PSD and uPSD}
@end itemize
OpenOCD will read each filename in sequence, for example:
@example
- openocd -f file1.cfg -f file2.cfg -f file2.cfg
+openocd -f file1.cfg -f file2.cfg -f file2.cfg
@end example
You can also intermix various commands with the ``-c'' command line
today, that said, perhaps some interfaces have only been used by the
sole developer who created it.
-@b{FIXME/NOTE:} We need to add support for a variable like Tcl variable
-tcl_platform(platform), it should be called jim_platform (because it
-is jim, not real tcl) and it should contain 1 of 3 words: ``linux'',
-``cygwin'' or ``mingw''
-
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@section Board Config Files
problems in OpenOCD configurations.
@example
-Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
-Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
+Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
+ (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
+Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678,
+ Got: 0x3f0f0f0f
Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
@end example
# variable: _TARGETNAME = network.cpu
# other commands can refer to the "network.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
set ENDIAN little
set CHIPNAME video
source [find target/pxa270.cfg]
# variable: _TARGETNAME = video.cpu
# other commands can refer to the "video.cpu" tap.
$_TARGETNAME configure .... params for this CPU..
-
+
unset ENDIAN
set CHIPNAME xilinx
source [find target/spartan3.cfg]
@example
# SIMPLE example
-if @{ [info exists CHIPNAME] @} @{
- set _CHIPNAME $CHIPNAME
-@} else @{
+if @{ [info exists CHIPNAME] @} @{
+ set _CHIPNAME $CHIPNAME
+@} else @{
set _CHIPNAME sam7x256
@}
-if @{ [info exists ENDIAN] @} @{
- set _ENDIAN $ENDIAN
-@} else @{
+if @{ [info exists ENDIAN] @} @{
+ set _ENDIAN $ENDIAN
+@} else @{
set _ENDIAN little
@}
@example
# for an ARM7TDMI.
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
+ -expected-id $_CPUTAPID
@end example
@b{COMPLEX example:}
@} else @{
set _FLASHTAPID 0x25966041
@}
-jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 -expected-id $_FLASHTAPID
+jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 \
+ -expected-id $_FLASHTAPID
if @{ [info exists CPUTAPID ] @} @{
set _CPUTAPID $CPUTAPID
@} else @{
set _CPUTAPID 0x25966041
@}
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe -expected-id $_CPUTAPID
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe \
+ -expected-id $_CPUTAPID
if @{ [info exists BSTAPID ] @} @{
@} else @{
set _BSTAPID 0x1457f041
@}
-jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 -expected-id $_BSTAPID
+jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 \
+ -expected-id $_BSTAPID
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
@end example
@subsection Work Areas
Work areas are small RAM areas used by OpenOCD to speed up downloads,
-and to download small snippets of code to program flash chips.
+and to download small snippets of code to program flash chips.
If the chip includes a form of ``on-chip-ram'' - and many do - define
a reasonable work area and use the ``backup'' option.
examination of the instruction and data bus activity. Trace
activity is controlled through an ``Embedded Trace Module'' (ETM)
on one of the core's scan chains. The ETM emits voluminous data
-through a ``trace port''. The trace port is accessed in one
-of two ways. When its signals are pinned out from the chip,
-boards may provide a special high speed debugging connector;
-software support for this is not configured by default, use
-the ``--enable-oocd_trace'' option. Alternatively, trace data
-may be stored an on-chip SRAM which is packaged as an ``Embedded
-Trace Buffer'' (ETB). An ETB has its own TAP, usually right after
-its associated ARM core. OpenOCD supports the ETM, and your
-target configuration should set it up with the relevant trace
-port: ``etb'' for chips which use that, else the board-specific
-option will be either ``oocd_trace'' or ``dummy''.
+through a ``trace port''. (@xref{ARM Tracing}.)
+If you are using an external trace port,
+configure it in your board config file.
+If you are using an on-chip ``Embedded Trace Buffer'' (ETB),
+configure it in your target config file.
@example
etm config $_TARGETNAME 16 normal full etb
@* JIM-Tcl was introduced to OpenOCD in spring 2008.
@item @b{Need a crash course in Tcl?}
-@* See: @xref{Tcl Crash Course}.
+@*@xref{Tcl Crash Course}.
@end itemize
-
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
the port @var{number} defaults to 4444.
@end deffn
-@section GDB Configuration
@anchor{GDB Configuration}
+@section GDB Configuration
@cindex GDB
@cindex GDB configuration
You can reconfigure some GDB behaviors if needed.
@xref{Target Create}, about declaring individual targets.
@xref{Target Events}, about configuring target-specific event handling.
-@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
@anchor{gdb_breakpoint_override}
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
Force breakpoint type for gdb @command{break} commands.
The raison d'etre for this option is to support GDB GUI's which don't
distinguish hard versus soft breakpoints, if the default OpenOCD and
Default behaviour is @var{resume}.
@end deffn
-@deffn {Config command} gdb_flash_program <enable|disable>
@anchor{gdb_flash_program}
+@deffn {Config command} gdb_flash_program <enable|disable>
Set to @var{enable} to cause OpenOCD to program the flash memory when a
vFlash packet is received.
The default behaviour is @var{enable}.
OOCDLink
@item @b{axm0432_jtag}
Axiom AXM-0432
+@item @b{cortino}
+Hitex Cortino JTAG interface
@end itemize
@item @b{ft2232_vid_pid} <@var{vid}> <@var{pid}>
@cindex ep93xx options
Currently, there are no options available for the ep93xx interface.
+@anchor{JTAG Speed}
@section JTAG Speed
-@itemize @bullet
-@item @b{jtag_khz} <@var{reset speed kHz}>
-@cindex jtag_khz
+JTAG clock setup is part of system setup.
+It @emph{does not belong with interface setup} since any interface
+only knows a few of the constraints for the JTAG clock speed.
+Sometimes the JTAG speed is
+changed during the target initialization process: (1) slow at
+reset, (2) program the CPU clocks, (3) run fast.
+Both the "slow" and "fast" clock rates are functions of the
+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.
+@xref{Target Events}.
+
+If your system supports adaptive clocking (RTCK), configuring
+JTAG to use that is probably the most robust approach.
+However, it introduces delays to synchronize clocks; so it
+may not be the fastest solution.
+
+@b{NOTE:} Script writers should consider using @command{jtag_rclk}
+instead of @command{jtag_khz}.
+
+@deffn {Command} jtag_khz max_speed_kHz
+A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+JTAG interfaces usually support a limited number of
+speeds. The speed actually used won't be faster
+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).
+
+Speed 0 (khz) selects RTCK method.
+@xref{FAQ RTCK}.
+If your system uses RTCK, you won't need to change the
+JTAG clocking after setup.
+Not all interfaces, boards, or targets support ``rtck''.
+If the interface device can not
+support it, an error is returned when you try to use RTCK.
+@end deffn
-It is debatable if this command belongs here - or in a board
-configuration file. In fact, in some situations the JTAG speed is
-changed during the target initialisation process (i.e.: (1) slow at
-reset, (2) program the CPU clocks, (3) run fast)
+@defun jtag_rclk fallback_speed_kHz
+@cindex RTCK
+This Tcl proc (defined in 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
+# Fall back to 3mhz if RTCK is not supported
+jtag_rclk 3000
+@end example
+@end defun
-Speed 0 (khz) selects RTCK method. A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+@node Reset Configuration
+@chapter Reset Configuration
+@cindex Reset Configuration
-Not all interfaces support ``rtck''. If the interface device can not
-support the rate asked for, or can not translate from kHz to
-jtag_speed, then an error is returned.
+Every system configuration may require a different reset
+configuration. This can also be quite confusing.
+Resets also interact with @var{reset-init} event handlers,
+which do things like setting up clocks and DRAM, and
+JTAG clock rates. (@xref{JTAG Speed}.)
+Please see the various board files for examples.
+
+@quotation Note
+To maintainers and integrators:
+Reset configuration touches several things at once.
+Normally the board configuration file
+should define it and assume that the JTAG adapter supports
+everything that's wired up to the board's JTAG connector.
+However, the target configuration file could also make note
+of something the silicon vendor has done inside the chip,
+which will be true for most (or all) boards using that chip.
+And when the JTAG adapter doesn't support everything, the
+system configuration file will need to override parts of
+the reset configuration provided by other files.
+@end quotation
-Make sure the JTAG clock is no more than @math{1/6th CPU-Clock}. This is
-especially true for synthesized cores (-S). Also see RTCK.
+@section Types of Reset
-@b{NOTE: Script writers} If the target chip requires/uses RTCK -
-please use the command: 'jtag_rclk FREQ'. This Tcl proc (in
-startup.tcl) attempts to enable RTCK, if that fails it falls back to
-the specified frequency.
+There are many kinds of reset possible through JTAG, but
+they may not all work with a given board and adapter.
+That's part of why reset configuration can be error prone.
-@example
- # Fall back to 3mhz if RCLK is not supported
- jtag_rclk 3000
-@end example
+@itemize @bullet
+@item
+@emph{System Reset} ... the @emph{SRST} hardware signal
+resets all chips connected to the JTAG adapter, such as processors,
+power management chips, and I/O controllers. Normally resets triggered
+with this signal behave exactly like pressing a RESET button.
+@item
+@emph{JTAG TAP Reset} ... the @emph{TRST} hardware signal resets
+just the TAP controllers connected to the JTAG adapter.
+Such resets should not be visible to the rest of the system; resetting a
+device's the TAP controller just puts that controller into a known state.
+@item
+@emph{Emulation Reset} ... many devices can be reset through JTAG
+commands. These resets are often distinguishable from system
+resets, either explicitly (a "reset reason" register says so)
+or implicitly (not all parts of the chip get reset).
+@item
+@emph{Other Resets} ... system-on-chip devices often support
+several other types of reset.
+You may need to arrange that a watchdog timer stops
+while debugging, preventing a watchdog reset.
+There may be individual module resets.
+@end itemize
-@item @b{DEPRECATED} @b{jtag_speed} - please use jtag_khz above.
-@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.
+In the best case, OpenOCD can hold SRST, then reset
+the TAPs via TRST and send commands through JTAG to halt the
+CPU at the reset vector before the 1st instruction is executed.
+Then when it finally releases the SRST signal, the system is
+halted under debugger control before any code has executed.
+This is the behavior required to support the @command{reset halt}
+and @command{reset init} commands; after @command{reset init} a
+board-specific script might do things like setting up DRAM.
+(@xref{Reset Command}.)
-The speed used during reset can be adjusted using setting jtag_speed during
-pre_reset and post_reset events.
-@itemize @minus
+@section SRST and TRST Signal Issues
-@item wiggler: maximum speed / @var{number}
-@item ft2232: 6MHz / (@var{number}+1)
-@item amt jtagaccel: 8 / 2**@var{number}
-@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
-@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
-@comment end speed list.
-@end itemize
+Because SRST and TRST are hardware signals, they can have a
+variety of system-specific constraints. Some of the most
+common issues are:
+
+@itemize @bullet
-@comment END command list
+@item @emph{Signal not available} ... Some boards don't wire
+SRST or TRST to the JTAG connector. Some JTAG adapters don't
+support such signals even if they are wired up.
+Use the @command{reset_config} @var{signals} options to say
+when one of those signals is not connected.
+When SRST is not available, your code might not be able to rely
+on controllers having been fully reset during code startup.
+
+@item @emph{Signals shorted} ... Sometimes a chip, board, or
+adapter will connect SRST to TRST, instead of keeping them separate.
+Use the @command{reset_config} @var{combination} options to say
+when those signals aren't properly independent.
+
+@item @emph{Timing} ... Reset circuitry like a resistor/capacitor
+delay circuit, reset supervisor, or on-chip features can extend
+the effect of a JTAG adapter's reset for some time after the adapter
+stops issuing the reset. For example, there may be chip or board
+requirements that all reset pulses last for at least a
+certain amount of time; and reset buttons commonly have
+hardware debouncing.
+Use the @command{jtag_nsrst_delay} and @command{jtag_ntrst_delay}
+commands to say when extra delays are needed.
+
+@item @emph{Drive type} ... Reset lines often have a pullup
+resistor, letting the JTAG interface treat them as open-drain
+signals. But that's not a requirement, so the adapter may need
+to use push/pull output drivers.
+Also, with weak pullups it may be advisable to drive
+signals to both levels (push/pull) to minimize rise times.
+Use the @command{reset_config} @var{trst_type} and
+@var{srst_type} parameters to say how to drive reset signals.
@end itemize
-@node Reset Configuration
-@chapter Reset Configuration
-@cindex Reset Configuration
+There can also be other issues.
+Some devices don't fully conform to the JTAG specifications.
+Trivial system-specific differences are common, such as
+SRST and TRST using slightly different names.
+There are also vendors who distribute key JTAG documentation for
+their chips only to developers who have signed a Non-Disclosure
+Agreement (NDA).
-Every system configuration may require a different reset
-configuration. This can also be quite confusing. Please see the
-various board files for example.
-
-@section jtag_nsrst_delay <@var{ms}>
-@cindex jtag_nsrst_delay
-@*How long (in milliseconds) OpenOCD should wait after deasserting
-nSRST before starting new JTAG operations.
-
-@section jtag_ntrst_delay <@var{ms}>
-@cindex jtag_ntrst_delay
-@*Same @b{jtag_nsrst_delay}, but for nTRST
-
-The jtag_n[st]rst_delay options are useful if reset circuitry (like a
-big resistor/capacitor, reset supervisor, or on-chip features). This
-keeps the signal asserted for some time after the external reset got
-deasserted.
-
-@section reset_config
-
-@b{Note:} To maintainers and integrators: Where exactly the
-``reset configuration'' goes is a good question. It touches several
-things at once. In the end, if you have a board file - the board file
-should define it and assume 100% that the DONGLE supports
-anything. However, that does not mean the target should not also make
-not of something the silicon vendor has done inside the
-chip. @i{Grr.... nothing is every pretty.}
-
-@* @b{Problems:}
-@enumerate
-@item Every JTAG Dongle is slightly different, some dongles implement reset differently.
-@item Every board is also slightly different; some boards tie TRST and SRST together.
-@item Every chip is slightly different; some chips internally tie the two signals together.
-@item Some may not implement all of the signals the same way.
-@item Some signals might be push-pull, others open-drain/collector.
-@end enumerate
-@b{Best Case:} OpenOCD can hold the SRST (push-button-reset), then
-reset the TAP via TRST and send commands through the JTAG tap to halt
-the CPU at the reset vector before the 1st instruction is executed,
-and finally release the SRST signal.
-@*Depending on your board vendor, chip vendor, etc., these
-signals may have slightly different names.
-
-OpenOCD defines these signals in these terms:
-@itemize @bullet
-@item @b{TRST} - is Tap Reset - and should reset only the TAP.
-@item @b{SRST} - is System Reset - typically equal to a reset push button.
-@end itemize
+Sometimes there are chip-specific extensions like a requirement to use
+the normally-optional TRST signal (precluding use of JTAG adapters which
+don't pass TRST through), or needing extra steps to complete a TAP reset.
-The Command:
+In short, SRST and especially TRST handling may be very finicky,
+needing to cope with both architecture and board specific constraints.
-@itemize @bullet
-@item @b{reset_config} <@var{signals}> [@var{combination}] [@var{trst_type}] [@var{srst_type}]
-@cindex reset_config
-@* The @t{reset_config} command tells OpenOCD the reset configuration
-of your combination of Dongle, Board, and Chips.
-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
+@section Commands for Handling Resets
+
+@deffn {Command} jtag_nsrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nSRST (active-low system reset) before starting new JTAG operations.
+When a board has a reset button connected to SRST line it will
+probably have hardware debouncing, implying you should use this.
+@end deffn
+
+@deffn {Command} jtag_ntrst_delay milliseconds
+How long (in milliseconds) OpenOCD should wait after deasserting
+nTRST (active-low JTAG TAP reset) before starting new JTAG operations.
+@end deffn
+
+@deffn {Command} reset_config mode_flag ...
+This command tells OpenOCD the reset configuration
+of your combination of JTAG board and target in target
+configuration scripts.
+
+If you have an interface that does not support SRST and
+TRST(unlikely), then you may be able to work around that
+problem by using a reset_config command to override any
+settings in the target configuration script.
+
+SRST and TRST has a fairly well understood definition and
+behaviour in the JTAG specification, but vendors take
+liberties to achieve various more or less clearly understood
+goals. Sometimes documentation is available, other times it
+is not. OpenOCD has the reset_config command to allow OpenOCD
+to deal with the various common cases.
+
+The @var{mode_flag} options can be specified in any order, but only one
+of each type -- @var{signals}, @var{combination}, @var{trst_type},
+and @var{srst_type} -- may be specified at a time.
+If you don't provide a new value for a given type, its previous
+value (perhaps the default) is unchanged.
+For example, this means that you don't need to say anything at all about
+TRST just to declare that if the JTAG adapter should want to drive SRST,
+it must explicitly be driven high (@option{srst_push_pull}).
+
+@var{signals} can specify which of the reset signals are connected.
+For example, If the JTAG interface provides SRST, but the board doesn't
+connect that signal properly, then OpenOCD can't use it.
+Possible values are @option{none} (the default), @option{trst_only},
+@option{srst_only} and @option{trst_and_srst}.
+
+@quotation Tip
+If your board provides SRST or TRST through the JTAG connector,
+you must declare that or else those signals will not be used.
+@end quotation
+
+The @var{combination} is an optional value specifying broken reset
+signal implementations.
+The default behaviour if no option given is @option{separate},
+indicating everything behaves normally.
+@option{srst_pulls_trst} states that the
test logic is reset together with the reset of the system (e.g. Philips
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} implies 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.
-
-@comment - end command
-@end itemize
-
+@option{trst_pulls_srst}.
+
+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
+JTAGkey and JTAGAccelerator. Also, they are necessarily ignored if the
+relevant signal (TRST or SRST) is not connected.
+
+Possible @var{trst_type} driver modes for the test reset signal (TRST)
+are @option{trst_push_pull} (default) and @option{trst_open_drain}.
+Most boards connect this signal to a pulldown, so the JTAG TAPs
+never leave reset unless they are hooked up to a JTAG adapter.
+
+Possible @var{srst_type} driver modes for the system reset signal (SRST)
+are the default @option{srst_open_drain}, and @option{srst_push_pull}.
+Most boards connect this signal to a pullup, and allow the
+signal to be pulled low by various events including system
+powerup and pressing a reset button.
+@end deffn
@node Tap Creation
creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
@section targets [NAME]
-@b{Note:} This command name is PLURAL - not singular.
+@b{Note:} This command name is PLURAL - not singular.
With NO parameter, this plural @b{targets} command lists all known
targets in a human friendly form.
Example:
@verbatim
(gdb) mon targets
- CmdName Type Endian ChainPos State
+ CmdName Type Endian ChainPos State
-- ---------- ---------- ---------- -------- ----------
0: target0 arm7tdmi little 0 halted
@end verbatim
@* Lists all supported target types (perhaps some are not yet in this document).
@item @b{names}
@* Lists all current debug target names, for example: 'str912.cpu' or 'pxa27.cpu' example usage:
-@verbatim
+@verbatim
foreach t [target names] {
puts [format "Target: %s\n" $t]
}
# Report
puts [format "The button is %s" $x]
@end example
-
+
In OpenOCD's terms, the ``target'' is an object just like a Tcl/Tk
button. Commands available as a ``target object'' are:
@* Invokes the specific event manually for the target
@end itemize
+@anchor{Target Events}
@section Target Events
@cindex events
-@anchor{Target Events}
At various times, certain things can happen, or you want them to happen.
Examples:
reset halt
@}
mychip.cpu configure -event gdb-attach my_attach_proc
- mychip.cpu configure -event gdb-attach @{ puts "Reset..." ; reset halt @}
+ mychip.cpu configure -event gdb-attach @{
+ puts "Reset..."
+ reset halt
+ @}
@end example
@section Current Events
@end example
@end itemize
-@section Target Create
@anchor{Target Create}
+@section Target Create
@cindex target
@cindex target creation
@section Target Variants
@itemize @bullet
-@item @b{arm7tdmi}
-@* Unknown (please write me)
-@item @b{arm720t}
-@* Unknown (please write me) (similar to arm7tdmi)
-@item @b{arm9tdmi}
-@* Variants: @option{arm920t}, @option{arm922t} and @option{arm940t}
-This enables the hardware single-stepping support found on these
-cores.
-@item @b{arm920t}
-@* None.
-@item @b{arm966e}
-@* None (this is also used as the ARM946)
@item @b{cortex_m3}
-@* use variant <@var{-variant 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
+@* Use variant @option{lm3s} when debugging older Stellaris LM3S targets.
+This will cause OpenOCD to use a software reset rather than asserting
+SRST, to avoid a issue with clearing the debug registers.
+This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
be detected and the normal reset behaviour used.
@item @b{xscale}
-@* Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},@option{pxa250}, @option{pxa255}, @option{pxa26x}.
-@item @b{arm11}
-@* Supported variants are @option{arm1136}, @option{arm1156}, @option{arm1176}
+@*Supported variants are
+@option{ixp42x}, @option{ixp45x}, @option{ixp46x},
+@option{pxa250}, @option{pxa255}, @option{pxa26x}.
@item @b{mips_m4k}
@* Use variant @option{ejtag_srst} when debugging targets that do not
provide a functional SRST line on the EJTAG connector. This causes
@end example
@* The target# is a the 0 based target numerical index.
-@node Flash Configuration
-@chapter Flash programming
-@cindex Flash Configuration
+@node Flash Commands
+@chapter Flash Commands
OpenOCD has different commands for NOR and NAND flash;
the ``flash'' command works with NOR flash, while
However, the documentation also uses ``flash'' as a generic term;
for example, ``Put flash configuration in board-specific files''.
-@b{Note:} As of 28/nov/2008 OpenOCD does not know how to program a SPI
+@quotation Note
+As of 28-nov-2008 OpenOCD does not know how to program a SPI
flash that a micro may boot from. Perhaps you, the reader, would like to
contribute support for this.
+@end quotation
Flash Steps:
@enumerate
-@item Configure via the command @b{flash bank}
-@* Normally this is done in a configuration file.
-@item Operate on the flash via @b{flash SOMECOMMAND}
+@item Configure via the command @command{flash bank}
+@* Do this in a board-specific configuration file,
+passing parameters as needed by the driver.
+@item Operate on the flash via @command{flash subcommand}
@* Often commands to manipulate the flash are typed by a human, or run
-via a script in some automated way. For example: To program the boot
-flash on your board.
+via a script in some automated way. Common tasks include writing a
+boot loader, operating system, or other data.
@item GDB Flashing
@* Flashing via GDB requires the flash be configured via ``flash
bank'', and the GDB flash features be enabled.
@xref{GDB Configuration}.
@end enumerate
-@section Flash commands
-@cindex Flash commands
-@subsection flash banks
-@b{flash banks}
-@cindex flash banks
-@*List configured flash banks
-@*@b{NOTE:} the singular form: 'flash bank' is used to configure the flash banks.
-@subsection flash info
-@b{flash info} <@var{num}>
-@cindex flash info
-@*Print info about flash bank <@option{num}>
-@subsection flash probe
-@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.
-@subsection flash erase_check
-@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.
-@subsection flash protect_check
-@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.
-@subsection flash erase_sector
-@b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
-@cindex flash erase_sector
+Many CPUs have the ablity to ``boot'' from the first flash bank.
+This means that misprograming that bank can ``brick'' a system,
+so that it can't boot.
+JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
+board by (re)installing working boot firmware.
+
+@section Flash Configuration Commands
+@cindex flash configuration
+
+@deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
+Configures a flash bank which provides persistent storage
+for addresses from @math{base} to @math{base + size - 1}.
+These banks will often be visible to GDB through the target's memory map.
+In some cases, configuring a flash bank will activate extra commands;
+see the driver-specific documentation.
+
+@itemize @bullet
+@item @var{driver} ... identifies the controller driver
+associated with the flash bank being declared.
+This is usually @code{cfi} for external flash, or else
+the name of a microcontroller with embedded flash memory.
+@xref{Flash Driver List}.
+@item @var{base} ... Base address of the flash chip.
+@item @var{size} ... Size of the chip, in bytes.
+For some drivers, this value is detected from the hardware.
+@item @var{chip_width} ... Width of the flash chip, in bytes;
+ignored for most microcontroller drivers.
+@item @var{bus_width} ... Width of the data bus used to access the
+chip, in bytes; ignored for most microcontroller drivers.
+@item @var{target} ... Names the target used to issue
+commands to the flash controller.
+@comment Actually, it's currently a controller-specific parameter...
+@item @var{driver_options} ... drivers may support, or require,
+additional parameters. See the driver-specific documentation
+for more information.
+@end itemize
+@quotation Note
+This command is not available after OpenOCD initialization has completed.
+Use it in board specific configuration files, not interactively.
+@end quotation
+@end deffn
+
+@comment the REAL name for this command is "ocd_flash_banks"
+@comment less confusing would be: "flash list" (like "nand list")
+@deffn Command {flash banks}
+Prints a one-line summary of each device declared
+using @command{flash bank}, numbered from zero.
+Note that this is the @emph{plural} form;
+the @emph{singular} form is a very different command.
+@end deffn
+
+@deffn Command {flash probe} num
+Identify the flash, or validate the parameters of the configured flash. Operation
+depends on the flash type.
+The @var{num} parameter is a value shown by @command{flash banks}.
+Most flash commands will implicitly @emph{autoprobe} the bank;
+flash drivers can distinguish between probing and autoprobing,
+but most don't bother.
+@end deffn
+
+@section Erasing, Reading, Writing to Flash
+@cindex flash erasing
+@cindex flash reading
+@cindex flash writing
+@cindex flash programming
+
+One feature distinguishing NOR flash from NAND or serial flash technologies
+is that for read access, it acts exactly like any other addressible memory.
+This means you can use normal memory read commands like @command{mdw} or
+@command{dump_image} with it, with no special @command{flash} subcommands.
+@xref{Memory access}, and @ref{Image access}.
+
+Write access works differently. Flash memory normally needs to be erased
+before it's written. Erasing a sector turns all of its bits to ones, and
+writing can turn ones into zeroes. This is why there are special commands
+for interactive erasing and writing, and why GDB needs to know which parts
+of the address space hold NOR flash memory.
+
+@quotation Note
+Most of these erase and write commands leverage the fact that NOR flash
+chips consume target address space. They implicitly refer to the current
+JTAG target, and map from an address in that target's address space
+back to a flash bank.
+@comment In May 2009, those mappings may fail if any bank associated
+@comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
+A few commands use abstract addressing based on bank and sector numbers,
+and don't depend on searching the current target and its address space.
+Avoid confusing the two command models.
+@end quotation
+
+Some flash chips implement software protection against accidental writes,
+since such buggy writes could in some cases ``brick'' a system.
+For such systems, erasing and writing may require sector protection to be
+disabled first.
+Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
+and AT91SAM7 on-chip flash.
+@xref{flash protect}.
+
@anchor{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).
-@subsection flash erase_address
-@b{flash erase_address} <@var{address}> <@var{length}>
-@cindex flash erase_address
-@*Erase sectors starting at <@var{address}> for <@var{length}> bytes
-@subsection flash write_bank
-@b{flash write_bank} <@var{num}> <@var{file}> <@var{offset}>
-@cindex flash write_bank
+@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.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash erase_address} address length
+Erase sectors starting at @var{address} for @var{length} bytes.
+The flash bank to use is inferred from the @var{address}, and
+the specified length must stay within that bank.
+As a special case, when @var{length} is zero and @var{address} is
+the start of the bank, the whole flash is erased.
+@end deffn
+
+@deffn Command {flash fillw} address word length
+@deffnx Command {flash fillh} address halfword length
+@deffnx Command {flash fillb} address byte length
+Fills flash memory with the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+starting at @var{address} and continuing
+for @var{length} units (word/halfword/byte).
+No erasure is done before writing; when needed, that must be done
+before issuing this command.
+Writes are done in blocks of up to 1024 bytes, and each write is
+verified by reading back the data and comparing it to what was written.
+The flash bank to use is inferred from the @var{address} of
+each block, and the specified length must stay within that bank.
+@end deffn
+@comment no current checks for errors if fill blocks touch multiple banks!
+
@anchor{flash write_bank}
-@*Write the binary <@var{file}> to flash bank <@var{num}>, starting at
-<@option{offset}> bytes from the beginning of the bank.
-@subsection flash write_image
-@b{flash write_image} [@var{erase}] <@var{file}> [@var{offset}] [@var{type}]
-@cindex flash write_image
+@deffn Command {flash write_bank} num filename offset
+Write the binary @file{filename} to flash bank @var{num},
+starting at @var{offset} bytes from the beginning of the bank.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
@anchor{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
+@deffn Command {flash write_image} [erase] filename [offset] [type]
+Write the image @file{filename} to the current target's flash bank(s).
+A relocation @var{offset} may be specified, in which case it is added
+to the base address for each section in the image.
+The file [@var{type}] can be specified
+explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19).
+@option{mem}, or @option{builder}.
+The relevant flash sectors will be erased prior to programming
if the @option{erase} parameter is given.
-@subsection flash protect
-@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}>.
+The flash bank to use is inferred from the @var{address} of
+each image segment.
+@end deffn
-@subsection mFlash commands
-@cindex mFlash commands
-@itemize @bullet
-@item @b{mflash probe}
-@cindex mflash probe
-Probe mflash.
-@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
-@cindex mflash write
-Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
-<@var{offset}> bytes from the beginning of the bank.
-@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
-@cindex mflash dump
-Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
-to a <@var{file}>.
-@end itemize
+@section Other Flash commands
+@cindex flash protection
+
+@deffn Command {flash erase_check} num
+Check erase state of sectors in flash bank @var{num},
+and display that status.
+The @var{num} parameter is a value shown by @command{flash banks}.
+This is the only operation that
+updates the erase state information displayed by @option{flash info}. That means you have
+to issue an @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
-@section flash bank command
-The @b{flash bank} command is used to configure one or more flash chips (or banks in OpenOCD terms)
+@deffn Command {flash info} num
+Print info about flash bank @var{num}
+The @var{num} parameter is a value shown by @command{flash banks}.
+The information includes per-sector protect status.
+@end deffn
-@example
-@b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
-<@var{bus_width}> <@var{target}> [@var{driver_options ...}]
-@end example
-@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>.
-
-@subsection External Flash - cfi options
-@cindex cfi options
-CFI flashes are external flash chips - often they are connected to a
-specific chip select on the CPU. By default, at hard reset, most
-CPUs have the ablity to ``boot'' from some flash chip - typically
-attached to the CPU's CS0 pin.
-
-For other chip selects: OpenOCD does not know how to configure, or
-access a specific chip select. Instead you, the human, might need to
-configure additional chip selects via other commands (like: mww) , or
+@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}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash protect_check} num
+Check protection state of sectors in flash bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@comment @option{flash erase_sector} using the same syntax.
+@end deffn
+
+@anchor{Flash Driver List}
+@section Flash Drivers, Options, and Commands
+As noted above, the @command{flash bank} command requires a driver name,
+and allows driver-specific options and behaviors.
+Some drivers also activate driver-specific commands.
+
+@subsection External Flash
+
+@deffn {Flash Driver} cfi
+@cindex Common Flash Interface
+@cindex CFI
+The ``Common Flash Interface'' (CFI) is the main standard for
+external NOR flash chips, each of which connects to a
+specific external chip select on the CPU.
+Frequently the first such chip is used to boot the system.
+Your board's @code{reset-init} handler might need to
+configure additional chip selects using other commands (like: @command{mww} to
+configure a bus and its timings) , or
perhaps configure a GPIO pin that controls the ``write protect'' pin
on the flash chip.
+The CFI driver can use a target-specific working area to significantly
+speed up operation.
-@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
-<@var{target}> [@var{jedec_probe}|@var{x16_as_x8}]
-@*CFI flashes require the name or 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.
+The CFI driver can accept the following optional parameters, in any order:
-@var{chip_width} and @var{bus_width} are specified in bytes.
+@itemize
+@item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
+like AM29LV010 and similar types.
+@item @var{x16_as_x8} ...
+@end itemize
-The @var{jedec_probe} option is used to detect certain non-CFI flash ROMs, like AM29LV010 and similar types.
+To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
+wide on a sixteen bit bus:
-@var{x16_as_x8} ???
+@example
+flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
+flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
+@end example
+@end deffn
@subsection Internal Flash (Microcontrollers)
-@subsubsection 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 name or 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.
+@deffn {Flash Driver} aduc702x
+The ADUC702x analog microcontrollers from ST Micro
+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
+since all devices in this family have the same memory layout.
+
+@example
+flash bank aduc702x 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} at91sam7
+All members of the AT91SAM7 microcontroller family from Atmel
+include internal flash and use ARM7TDMI cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+
+@example
+flash bank at91sam7 0 0 0 0 $_TARGETNAME
+@end example
+
+For chips which are not recognized by the controller driver, you must
+provide additional parameters in the following order:
+
+@itemize
+@item @var{chip_model} ... label used with @command{flash info}
+@item @var{banks}
+@item @var{sectors_per_bank}
+@item @var{pages_per_sector}
+@item @var{pages_size}
+@item @var{num_nvm_bits}
+@item @var{freq_khz} ... required if an external clock is provided,
+optional (but recommended) when the oscillator frequency is known
+@end itemize
+It is recommended that you provide zeroes for all of those values
+except the clock frequency, so that everything except that frequency
+will be autoconfigured.
+Knowing the frequency helps ensure correct timings for flash access.
+
+The flash controller handles erases automatically on a page (128/256 byte)
+basis, so explicit erase commands are not necessary for flash programming.
+However, there is an ``EraseAll`` command that can erase an entire flash
+plane (of up to 256KB), and it will be used automatically when you issue
+@command{flash erase_sector} or @command{flash erase_address} commands.
+
+@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+bit for the processor. Each processor has a number of such bits,
+used for controlling features such as brownout detection (so they
+are not truly general purpose).
+@quotation Note
+This assumes that the first flash bank (number 0) is associated with
+the appropriate at91sam7 target.
+@end quotation
+@end deffn
+@end deffn
-@subsubsection at91sam7 options
-@cindex at91sam7 options
+@deffn {Flash Driver} avr
+The AVR 8-bit microcontrollers from Atmel integrate flash memory.
+@emph{The current implementation is incomplete.}
+@comment - defines mass_erase ... pointless given flash_erase_address
+@end deffn
-@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.
+@deffn {Flash Driver} ecosflash
+@emph{No idea what this is...}
+The @var{ecosflash} driver defines one mandatory parameter,
+the name of a modules of target code which is downloaded
+and executed.
+@end deffn
-@subsubsection str7 options
-@cindex str7 options
+@deffn {Flash Driver} lpc2000
+Most members of the LPC2000 microcontroller family from NXP
+include internal flash and use ARM7TDMI cores.
+The @var{lpc2000} driver defines two mandatory and one optional parameters,
+which must appear in the following order:
-@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}>
-@*variant can be either STR71x, STR73x or STR75x.
+@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)
+@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!),
+telling the driver to calculate a valid checksum for the exception vector table.
+@end itemize
-@subsubsection str9 options
-@cindex str9 options
+LPC flashes don't require the chip and bus width to be specified.
-@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, e.g.
@example
-str9x flash_config 0 4 2 0 0x80000
+flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
+ lpc2000_v2 14765 calc_checksum
@end example
-This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively.
+@end deffn
-@subsubsection str9 options (str9xpec driver)
+@deffn {Flash Driver} lpc288x
+The LPC2888 microcontroller from NXP needs slightly different flash
+support from its lpc2000 siblings.
+The @var{lpc288x} driver defines one mandatory parameter,
+the programming clock rate in Hz.
+LPC flashes don't require the chip and bus width to be specified.
-@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Before using the flash commands the turbo mode must be enabled using str9xpec
-@option{enable_turbo} <@var{num>.}
+@example
+flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000
+@end example
+@end deffn
-Only use this driver for locking/unlocking the device or configuring the option bytes.
-Use the standard str9 driver for programming. @xref{STR9 specific commands}.
+@deffn {Flash Driver} ocl
+@emph{No idea what this is, other than using some arm7/arm9 core.}
+
+@example
+flash bank ocl 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} pic32mx
+The PIC32MX microcontrollers are based on the MIPS 4K cores,
+and integrate flash memory.
+@emph{The current implementation is incomplete.}
+
+@example
+flash bank pix32mx 0 0 0 0 $_TARGETNAME
+@end example
-@subsubsection Stellaris (LM3Sxxx) options
-@cindex Stellaris (LM3Sxxx) options
+@comment numerous *disabled* commands are defined:
+@comment - chip_erase ... pointless given flash_erase_address
+@comment - lock, unlock ... pointless given protect on/off (yes?)
+@comment - pgm_word ... shouldn't bank be deduced from address??
+Some pic32mx-specific commands are defined:
+@deffn Command {pic32mx pgm_word} address value bank
+Programs the specified 32-bit @var{value} at the given @var{address}
+in the specified chip @var{bank}.
+@end deffn
+@end deffn
-@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Stellaris flash plugin only require the @var{target}.
+@deffn {Flash Driver} stellaris
+All members of the Stellaris LM3Sxxx microcontroller family from
+Texas Instruments
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@footnote{Currently there is a @command{stellaris mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
-@subsubsection stm32x options
-@cindex stm32x options
+@example
+flash bank stellaris 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
-@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*stm32x flash plugin only require the @var{target}.
+@deffn {Flash Driver} stm32x
+All members of the STM32 microcontroller family from ST Microelectronics
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
-@subsubsection aduc702x options
-@cindex aduc702x options
+@example
+flash bank stm32x 0 0 0 0 $_TARGETNAME
+@end example
-@b{flash bank aduc702x} 0 0 0 0 <@var{target}>
-@*The aduc702x flash plugin works with Analog Devices model numbers ADUC7019 through ADUC7028. The setup command only requires the @var{target} argument (all devices in this family have the same memory layout).
+Some stm32x-specific commands
+@footnote{Currently there is a @command{stm32x mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
+are defined:
-@subsection mFlash Configuration
-@cindex mFlash Configuration
-@b{mflash bank} <@var{soc}> <@var{base}> <@var{chip_width}> <@var{bus_width}>
-<@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target}>
-@cindex mflash bank
-@*Configures a mflash for <@var{soc}> host bank at
-<@var{base}>. <@var{chip_width}> and <@var{bus_width}> are bytes
-order. Pin number format is dependent on host GPIO calling convention.
-If WP or DPD pin was not used, write -1. Currently, mflash bank
-support s3c2440 and pxa270.
+@deffn Command {stm32x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x options_read} num
+Read and display the stm32 option bytes written by
+the @command{stm32x options_write} command.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+Writes the stm32 option byte with the specified values.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} str7x
+All members of the STR7 microcontroller family from ST Microelectronics
+include internal flash and use ARM7TDMI cores.
+The @var{str7x} driver defines one mandatory parameter, @var{variant},
+which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
-(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1, <@var{WP pin}> and <@var{DPD pin}> are not used.
@example
-mflash bank s3c2440 0x10000000 2 2 1b -1 -1 0
+flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
-(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43, <@var{DPD pin}> is not used and <@var{DPD pin}> is GPIO 51.
+@end deffn
+
+@deffn {Flash Driver} str9x
+Most members of the STR9 microcontroller family from ST Microelectronics
+include internal flash and use ARM966E cores.
+The str9 needs the flash controller to be configured using
+the @command{str9x flash_config} command prior to Flash programming.
+
@example
-mflash bank pxa270 0x08000000 2 2 43 -1 51 0
+flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
+str9x flash_config 0 4 2 0 0x80000
@end example
-@section Microcontroller specific Flash Commands
+@deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
+Configures the str9 flash controller.
+The @var{num} parameter is a value shown by @command{flash banks}.
-@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
+@item @var{bbsr} - Boot Bank Size register
+@item @var{nbbsr} - Non Boot Bank Size register
+@item @var{bbadr} - Boot Bank Start Address register
+@item @var{nbbadr} - Boot Bank Start Address register
@end itemize
+@end deffn
-@subsection STR9 specific commands
-@cindex STR9 specific commands
-@anchor{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, will simply 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
+@end deffn
-Note: Before using the str9xpec driver here is some background info to help
-you better understand how the drivers works. OpenOCD has two flash drivers for
-the str9.
+@deffn {Flash Driver} tms470
+Most members of the TMS470 microcontroller family from Texas Instruments
+include internal flash and use ARM7TDMI cores.
+This driver doesn't require the chip and bus width to be specified.
+
+Some tms470-specific commands are defined:
+
+@deffn Command {tms470 flash_keyset} key0 key1 key2 key3
+Saves programming keys in a register, to enable flash erase and write commands.
+@end deffn
+
+@deffn Command {tms470 osc_mhz} clock_mhz
+Reports the clock speed, which is used to calculate timings.
+@end deffn
+
+@deffn Command {tms470 plldis} (0|1)
+Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
+the flash clock.
+@end deffn
+@end deffn
+
+@subsection str9xpec driver
+@cindex str9xpec
+
+Here is some background info to help
+you better understand how this driver works. OpenOCD has two flash drivers for
+the str9:
@enumerate
@item
Standard driver @option{str9x} programmed via the str9 core. Normally used for
has been locked. Halting the core is not required for the @option{str9xpec} driver
as mentioned above, just issue the commands above manually or from a telnet prompt.
-@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.
-@example
-e.g. 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 example
-@end itemize
+@subsubsection str9xpec driver options
-@subsection STR9 option byte configuration
-@cindex STR9 option byte configuration
-@itemize @bullet
+@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
+@*Before using the flash commands the turbo mode must be enabled 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.
+
+@subsubsection str9xpec specific commands
+@cindex str9xpec 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, will simply 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
+
+@subsubsection 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.
@*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
+@section mFlash
+
+@subsection mFlash Configuration
+@cindex mFlash Configuration
+@b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
+@cindex mflash bank
+@*Configures a mflash for <@var{soc}> host bank at
+<@var{base}>. Pin number format is dependent on host GPIO calling convention.
+Currently, mflash bank support s3c2440 and pxa270.
+
+(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
+
+@example
+mflash bank s3c2440 0x10000000 1b 0
+@end example
+
+(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
+
+@example
+mflash bank pxa270 0x08000000 43 0
+@end example
+
+@subsection mFlash commands
+@cindex mFlash commands
-@subsection Stellaris specific commands
-@cindex Stellaris specific commands
-
-These are flash specific commands when using the Stellaris driver.
@itemize @bullet
-@item @b{stellaris mass_erase} <@var{num}>
-@cindex stellaris mass_erase
-@*mass erase flash memory.
+@item @b{mflash probe}
+@cindex mflash probe
+@*Probe mflash.
+@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
+@cindex mflash write
+@*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
+<@var{offset}> bytes from the beginning of the bank.
+@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
+@cindex mflash dump
+@*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
+to a <@var{file}>.
+@item @b{mflash config pll} <@var{frequency}>
+@cindex mflash config pll
+@*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
+Issuing this command will erase mflash's whole internal nand and write new pll.
+After this command, mflash needs power-on-reset for normal operation.
+If pll was newly configured, storage and boot(optional) info also need to be update.
+@item @b{mflash config boot}
+@cindex mflash config boot
+@*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
+(4kB) for boot.
+@item @b{mflash config storage}
+@cindex mflash config storage
+@*Configure storage information. For the normal storage operation, this information must be
+written.
@end itemize
@node NAND Flash Commands
configuration files, not interactively.
@itemize @bullet
-@item @var{controller} ... identifies a the controller driver
+@item @var{controller} ... identifies the controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@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
@deffn Command {nand write} num filename offset [option...]
@cindex NAND writing
+@cindex NAND programming
Writes binary data from the file into the specified NAND device,
starting at the specified offset. Those pages should already
have been erased; you can't change zero bits to one bits.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
-@section NAND Drivers; Driver-specific Options and Commands
@anchor{NAND Driver List}
+@section NAND Drivers, Options, and Commands
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
@deffn {NAND Driver} lpc3180
These controllers require an extra @command{nand device}
parameter: the clock rate used by the controller.
-@deffn Command {nand lpc3180 select} num [mlc|slc]
+@deffn Command {lpc3180 select} num [mlc|slc]
Configures use of the MLC or SLC controller mode.
MLC implies use of hardware ECC.
The @var{num} parameter is the value shown by @command{nand list}.
change any behavior.
@end deffn
-@deffn {NAND Driver} {s3c2410, s3c2412, s3c2440, s3c2443}
+@deffn {NAND Driver} s3c2410
+@deffnx {NAND Driver} s3c2412
+@deffnx {NAND Driver} s3c2440
+@deffnx {NAND Driver} s3c2443
These S3C24xx family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
@cindex shutdown
@*Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
+@anchor{debug_level}
@subsection debug_level [@var{n}]
@cindex debug_level
-@anchor{debug_level}
@*Display or adjust debug level to n<0-3>
@subsection fast [@var{enable|disable}]
@cindex step
@*Single-step the target at its current code position, or at an optional address.
+@anchor{Reset Command}
@subsection reset [@option{run}|@option{halt}|@option{init}]
@cindex reset
-@*Perform a hard-reset. The optional parameter specifies what should happen after the reset.
-
-With no arguments a "reset run" is executed
+@*Perform a hard-reset. The optional parameter specifies what should
+happen after the reset.
+If there is no parameter, a @command{reset run} is executed.
+The other options will not work on all systems.
+@xref{Reset Configuration}.
@itemize @minus
@item @b{run}
@cindex reset run
state.
+@anchor{Memory access}
@section Memory access commands
@subsection meminfo
-display available RAM memory.
+display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts. Mainly
+useful on embedded targets, PC type hosts have complimentary tools like Valgrind to address
+resource tracking problems.
@subsection Memory peek/poke type commands
These commands allow accesses of a specific size to the memory
system. Often these are used to configure the current target in some
@*write memory byte (8bit)
@end itemize
+@anchor{Image access}
@section Image loading commands
+@anchor{load_image}
@subsection load_image
@b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex load_image
-@anchor{load_image}
@*Load image <@var{file}> to target memory at <@var{address}>
@subsection fast_load_image
@b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex fast_load_image
-@anchor{fast_load_image}
@*Normally you should be using @b{load_image} or GDB load. However, for
testing purposes or when I/O overhead is significant(OpenOCD running on an embedded
host), storing the image in memory and uploading the image to the target
@subsection fast_load
@b{fast_load}
@cindex fast_image
-@anchor{fast_image}
@*Loads an image stored in memory by @b{fast_load_image} to the current target. Must be preceeded by fast_load_image.
+@anchor{dump_image}
@subsection dump_image
@b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
-@anchor{dump_image}
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@subsection verify_image
@end itemize
-@section Target Specific Commands
-@cindex Target Specific Commands
+@section Architecture and Core Specific Commands
+@cindex Architecture Specific Commands
+@cindex Core Specific Commands
+Most CPUs have specialized JTAG operations to support debugging.
+OpenOCD packages most such operations in its standard command framework.
+Some of those operations don't fit well in that framework, so they are
+exposed here using architecture or implementation specific commands.
-@page
-@section Architecture Specific Commands
-@cindex Architecture Specific Commands
+@anchor{ARM Tracing}
+@subsection ARM Tracing
+@cindex ETM
+@cindex ETB
-@subsection ARMV4/5 specific commands
-@cindex ARMV4/5 specific commands
+CPUs based on ARM cores may include standard tracing interfaces,
+based on an ``Embedded Trace Module'' (ETM) which sends voluminous
+address and data bus trace records to a ``Trace Port''.
-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
+@itemize
+@item
+Development-oriented boards will sometimes provide a high speed
+trace connector for collecting that data, when the particular CPU
+supports such an interface.
+(The standard connector is a 38-pin Mictor, with both JTAG
+and trace port support.)
+Those trace connectors are supported by higher end JTAG adapters
+and some logic analyzer modules; frequently those modules can
+buffer several megabytes of trace data.
+Configuring an ETM coupled to such an external trace port belongs
+in the board-specific configuration file.
+@item
+If the CPU doesn't provide an external interface, it probably
+has an ``Embedded Trace Buffer'' (ETB) on the chip, which is a
+dedicated SRAM. 4KBytes is one common ETB size.
+Configuring an ETM coupled only to an ETB belongs in the CPU-specific
+(target) configuration file, since it works the same on all boards.
+@end itemize
+
+ETM support in OpenOCD doesn't seem to be widely used yet.
+
+@quotation Issues
+ETM support may be buggy, and at least some @command{etm config}
+parameters should be detected by asking the ETM for them.
+It seems like a GDB hookup should be possible,
+as well as triggering trace on specific events
+(perhaps @emph{handling IRQ 23} or @emph{calls foo()}).
+There should be GUI tools to manipulate saved trace data and help
+analyse it in conjunction with the source code.
+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.
+@end quotation
+
+@subsubsection ETM Configuration
+ETM setup is coupled with the trace port driver configuration.
+
+@deffn {Config Command} {etm config} target width mode clocking driver
+Declares the ETM associated with @var{target}, and associates it
+with a given trace port @var{driver}. @xref{Trace Port Drivers}.
+
+Several of the parameters must reflect the trace port configuration.
+The @var{width} must be either 4, 8, or 16.
+The @var{mode} must be @option{normal}, @option{multiplexted},
+or @option{demultiplexted}.
+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.
+@end quotation
+@end deffn
+
+@deffn Command {etm info}
+Displays information about the current target's ETM.
+@end deffn
+
+@deffn Command {etm status}
+Displays status of the current target's ETM:
+is the ETM idle, or is it collecting data?
+Did trace data overflow?
+Was it triggered?
+@end deffn
+
+@deffn Command {etm tracemode} [type context_id_bits cycle_accurate branch_output]
+Displays what data that ETM will collect.
+If arguments are provided, first configures that data.
+When the configuration changes, tracing is stopped
+and any buffered trace data is invalidated.
+
+@itemize
+@item @var{type} ... 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}
+@end itemize
+@end deffn
+
+@deffn Command {etm trigger_percent} percent
+@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@end deffn
+
+@subsubsection ETM Trace Operation
+
+After setting up the ETM, you can use it to collect data.
+That data can be exported to files for later analysis.
+It can also be parsed with OpenOCD, for basic sanity checking.
+
+@deffn Command {etm analyze}
+Reads trace data into memory, if it wasn't already present.
+Decodes and prints the data that was collected.
+@end deffn
+
+@deffn Command {etm dump} filename
+Stores the captured trace data in @file{filename}.
+@end deffn
+
+@deffn Command {etm image} filename [base_address] [type]
+Opens an image file.
+@end deffn
+
+@deffn Command {etm load} filename
+Loads captured trace data from @file{filename}.
+@end deffn
+
+@deffn Command {etm start}
+Starts trace data collection.
+@end deffn
+
+@deffn Command {etm stop}
+Stops trace data collection.
+@end deffn
+
+@anchor{Trace Port Drivers}
+@subsubsection Trace Port Drivers
+
+To use an ETM trace port it must be associated with a driver.
+
+@deffn {Trace Port Driver} dummy
+Use the @option{dummy} driver if you are configuring an ETM that's
+not connected to anything (on-chip ETB or off-chip trace connector).
+@emph{This driver lets OpenOCD talk to the ETM, but it does not expose
+any trace data collection.}
+@deffn {Config Command} {etm_dummy config} target
+Associates the ETM for @var{target} with a dummy driver.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} etb
+Use the @option{etb} driver if you are configuring an ETM
+to use on-chip ETB memory.
+@deffn {Config Command} {etb config} target etb_tap
+Associates the ETM for @var{target} with the ETB at @var{etb_tap}.
+You can see the ETB registers using the @command{reg} command.
+@end deffn
+@end deffn
+
+@deffn {Trace Port Driver} oocd_trace
+This driver isn't available unless OpenOCD was explicitly configured
+with the @option{--enable-oocd_trace} option. You probably don't want
+to configure it unless you've built the appropriate prototype hardware;
+it's @emph{proof-of-concept} software.
+
+Use the @option{oocd_trace} driver if you are configuring an ETM that's
+connected to an off-chip trace connector.
+
+@deffn {Config Command} {oocd_trace config} target tty
+Associates the ETM for @var{target} with a trace driver which
+collects data through the serial port @var{tty}.
+@end deffn
+
+@deffn Command {oocd_trace resync}
+Re-synchronizes with the capture clock.
+@end deffn
+
+@deffn Command {oocd_trace status}
+Reports whether the capture clock is locked or not.
+@end deffn
+@end deffn
+
+
+@subsection ARMv4 and ARMv5 Architecture
+@cindex ARMv4 specific commands
+@cindex ARMv5 specific commands
+
+These commands are specific to ARM architecture v4 and v5,
+including all ARM7 or ARM9 systems and Intel XScale.
+They are available in addition to other core-specific
+commands that may be available.
+
+@deffn Command {armv4_5 core_state} [arm|thumb]
+Displays the core_state, optionally changing it to process
+either @option{arm} or @option{thumb} instructions.
+The target may later be resumed in the currently set core_state.
+(Processors may also support the Jazelle state, but
+that is not currently supported in OpenOCD.)
+@end deffn
+
+@deffn Command {armv4_5 disassemble} address count [thumb]
+@cindex disassemble
+Disassembles @var{count} instructions starting at @var{address}.
+If @option{thumb} is specified, 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.)
+@end deffn
+
+@deffn Command {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
+@end deffn
-@subsection ARM7/9 specific commands
-@cindex ARM7/9 specific commands
+@subsubsection ARM7 and ARM9 specific commands
+@cindex ARM7 specific commands
+@cindex ARM9 specific commands
-These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t,
-ARM920T or ARM926EJ-S.
-@itemize @bullet
-@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
+These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI, ARM720T,
+ARM9TDMI, ARM920T or ARM926EJ-S.
+They are available in addition to the ARMv4/5 commands,
+and any other core-specific commands that may be available.
+
+@deffn Command {arm7_9 dbgrq} (enable|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).
-@item @b{arm7_9 fast_memory_access} <@var{enable}|@var{disable}>
-@cindex arm7_9 fast_memory_access
+@end deffn
+
+@deffn Command {arm7_9 dcc_downloads} (enable|disable)
+@cindex DCC
+Control the use of the debug communications channel (DCC) to write larger (>128 byte)
+amounts of memory. DCC downloads offer a huge speed increase, but might be
+unsafe, especially with targets running at very low speeds. This command was introduced
+with OpenOCD rev. 60, and requires a few bytes of working area.
+@end deffn
+
@anchor{arm7_9 fast_memory_access}
-@*Allow OpenOCD to read and write memory without checking completion of
+@deffn Command {arm7_9 fast_memory_access} (enable|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.
-@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 very low speeds. This command was introduced
-with OpenOCD rev. 60, and requires a few bytes of working area.
-@end itemize
+@end deffn
-@subsection ARM720T specific commands
+@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+Writes a 32-bit @var{word} to register @var{num} (from 0 to 16)
+as used in the specified @var{mode}
+(where e.g. mode 16 is "user" and mode 19 is "supervisor";
+the M4..M0 bits of the PSR).
+Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15).
+Register 16 is the mode-specific SPSR,
+unless the specified mode is 0xffffffff (32-bit all-ones)
+in which case register 16 is the CPSR.
+The write goes directly to the CPU, bypassing the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr} word (0|1)
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+If the second parameter is zero, writes @var{word} to the
+Current Program Status register (CPSR).
+Else writes @var{word} to the current mode's Saved PSR (SPSR).
+In both cases, this bypasses the register cache.
+@end deffn
+
+@deffn {Debug Command} {arm7_9 write_xpsr_im8} byte rotate (0|1)
+@emph{This is intended for use while debugging OpenOCD; you probably
+shouldn't use it.}
+
+Writes eight bits to the CPSR or SPSR,
+first rotating them by @math{2*rotate} bits,
+and bypassing the register cache.
+This has lower JTAG overhead than writing the entire CPSR or SPSR
+with @command{arm7_9 write_xpsr}.
+@end deffn
+
+@subsubsection 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
+These commands are available to ARM720T based CPUs,
+which are implementations of the ARMv4T architecture
+based on the ARM7TDMI-S integer core.
+They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.
+
+@deffn Command {arm720t cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
-@subsection ARM9TDMI specific commands
+@deffn Command {arm720t mdw_phys} addr [count]
+@deffnx Command {arm720t mdh_phys} addr [count]
+@deffnx Command {arm720t mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
+
+@deffn Command {arm720t mww_phys} addr word
+@deffnx Command {arm720t mwh_phys} addr halfword
+@deffnx Command {arm720t mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm720t virt2phys} va
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
+
+@subsubsection 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:
+Many ARM9-family CPUs are built around ARM9TDMI integer cores,
+or processors resembling ARM9TDMI, and can use these commands.
+Such cores include the ARM920T, ARM926EJ-S, and ARM966.
+
+@deffn Command {arm9tdmi vector_catch} (all|none|list)
+Catch arm9 interrupt vectors, can be @option{all}, @option{none},
+or a list with one or more of the following:
@option{reset} @option{undef} @option{swi} @option{pabt} @option{dabt} @option{reserved}
@option{irq} @option{fiq}.
+@end deffn
-Can also be used on other ARM9 based cores such as ARM966, ARM920T and ARM926EJ-S.
-@end itemize
+@subsubsection ARM920T specific commands
+@cindex ARM920T specific commands
-@subsection ARM966E specific commands
-@cindex ARM966E specific commands
+These commands are available to ARM920T based CPUs,
+which are implementations of the ARMv4T architecture
+built using the ARM9TDMI integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
-@itemize @bullet
-@item @b{arm966e cp15} <@var{num}> [@var{value}]
-@cindex arm966e cp15
-@*display/modify cp15 register <@option{num}> [@option{value}].
-@end itemize
+@deffn Command {arm920t cache_info}
+Print information about the caches found. This allows to see whether your target
+is an ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
+@end deffn
-@subsection ARM920T specific commands
-@cindex ARM920T specific commands
+@deffn Command {arm920t cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
-@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 to see whether your target
-is an 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
+@deffn Command {arm920t cp15i} opcode [value [address]]
+Interpreted access using cp15 @var{opcode}.
+If no @var{value} is provided, the result is displayed.
+Else if that value is written using the specified @var{address},
+or using zero if no other address is not provided.
+@end deffn
+
+@deffn Command {arm920t mdw_phys} addr [count]
+@deffnx Command {arm920t mdh_phys} addr [count]
+@deffnx Command {arm920t mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
+
+@deffn Command {arm920t mww_phys} addr word
+@deffnx Command {arm920t mwh_phys} addr halfword
+@deffnx Command {arm920t mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm920t read_cache} filename
+Dump the content of ICache and DCache to a file named @file{filename}.
+@end deffn
-@subsection ARM926EJ-S specific commands
+@deffn Command {arm920t read_mmu} filename
+Dump the content of the ITLB and DTLB to a file named @file{filename}.
+@end deffn
+
+@deffn Command {arm920t virt2phys} @var{va}
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
+
+@subsubsection ARM926EJ-S specific commands
@cindex ARM926EJ-S 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
+These commands are available to ARM926EJ-S based CPUs,
+which are implementations of the ARMv5TEJ architecture
+based on the ARM9EJ-S integer core.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
-@subsection CORTEX_M3 specific commands
-@cindex CORTEX_M3 specific commands
+@deffn Command {arm926ejs cache_info}
+Print information about the caches found.
+@end deffn
-@itemize @bullet
-@item @b{cortex_m3 maskisr} <@var{on}|@var{off}>
-@cindex cortex_m3 maskisr
-@*Enable masking (disabling) interrupts during target step/resume.
-@end itemize
+@deffn Command {arm926ejs cp15} opcode1 opcode2 CRn CRm regnum [value]
+Accesses cp15 register @var{regnum} using
+@var{opcode1}, @var{opcode2}, @var{CRn}, and @var{CRm}.
+If a @var{value} is provided, that value is written to that register.
+Else that register is read and displayed.
+@end deffn
-@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
+@deffn Command {arm926ejs mdw_phys} addr [count]
+@deffnx Command {arm926ejs mdh_phys} addr [count]
+@deffnx Command {arm926ejs mdb_phys} addr [count]
+Display contents of physical address @var{addr}, as
+32-bit words (@command{mdw_phys}), 16-bit halfwords (@command{mdh_phys}),
+or 8-bit bytes (@command{mdb_phys}).
+If @var{count} is specified, displays that many units.
+@end deffn
+
+@deffn Command {arm926ejs mww_phys} addr word
+@deffnx Command {arm926ejs mwh_phys} addr halfword
+@deffnx Command {arm926ejs mwb_phys} addr byte
+Writes the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+at the specified physical address @var{addr}.
+@end deffn
+
+@deffn Command {arm926ejs virt2phys} @var{va}
+Translate a virtual address @var{va} to a physical address
+and display the result.
+@end deffn
+
+@subsubsection ARM966E specific commands
+@cindex ARM966E specific commands
+
+These commands are available to ARM966 based CPUs,
+which are implementations of the ARMv5TE architecture.
+They are available in addition to the ARMv4/5, ARM7/ARM9,
+and ARM9TDMI commands.
+
+@deffn Command {arm966e cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@subsubsection XScale specific commands
+@cindex XScale specific commands
+
+These commands are available to XScale based CPUs,
+which are implementations of the ARMv5TE architecture.
+
+@deffn Command {xscale analyze_trace}
+Displays the contents of the trace buffer.
+@end deffn
+
+@deffn Command {xscale cache_clean_address} address
+Changes the address used when cleaning the data cache.
+@end deffn
+
+@deffn Command {xscale cache_info}
+Displays information about the CPU caches.
+@end deffn
+
+@deffn Command {xscale cp15} regnum [value]
+Display cp15 register @var{regnum};
+else if a @var{value} is provided, that value is written to that register.
+@end deffn
+
+@deffn Command {xscale debug_handler} target address
+Changes the address used for the specified target's debug handler.
+@end deffn
+
+@deffn Command {xscale dcache} (enable|disable)
+Enables or disable the CPU's data cache.
+@end deffn
+
+@deffn Command {xscale dump_trace} filename
+Dumps the raw contents of the trace buffer to @file{filename}.
+@end deffn
+
+@deffn Command {xscale icache} (enable|disable)
+Enables or disable the CPU's instruction cache.
+@end deffn
+
+@deffn Command {xscale mmu} (enable|disable)
+Enables or disable the CPU's memory management unit.
+@end deffn
+
+@deffn Command {xscale trace_buffer} (enable|disable) [fill [n] | wrap]
+Enables or disables the trace buffer,
+and controls how it is emptied.
+@end deffn
+
+@deffn Command {xscale trace_image} filename [offset [type]]
+Opens a trace image from @file{filename}, optionally rebasing
+its segment addresses by @var{offset}.
+The image @var{type} may be one of
+@option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19),
+@option{mem}, or @option{builder}.
+@end deffn
+
+@deffn Command {xscale vector_catch} mask
+Provide a bitmask showing the vectors to catch.
+@end deffn
+
+@subsection ARMv6 Architecture
+
+@subsubsection ARM11 specific commands
+@cindex ARM11 specific commands
+
+@deffn Command {arm11 mcr} p1 p2 p3 p4 p5
+Read coprocessor register
+@end deffn
+
+@deffn Command {arm11 memwrite burst} [value]
+Displays the value of the memwrite burst-enable flag,
+which is enabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 memwrite error_fatal} [value]
+Displays the value of the memwrite error_fatal flag,
+which is enabled by default.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@deffn Command {arm11 mrc} p1 p2 p3 p4 p5 value
+Write coprocessor register
+@end deffn
+
+@deffn Command {arm11 no_increment} [value]
+Displays the value of the flag controlling whether
+some read or write operations increment the pointer
+(the default behavior) or not (acting like a FIFO).
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@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.
+If @var{value} is defined, first assigns that.
+@end deffn
+
+@subsection ARMv7 Architecture
+
+@subsubsection Cortex-M3 specific commands
+@cindex Cortex-M3 specific commands
+
+@deffn Command {cortex_m3 maskisr} (on|off)
+Control masking (disabling) interrupts during target step/resume.
+@end deffn
+
+@section Target DCC Requests
+@cindex Linux-ARM DCC support
+@cindex libdcc
+@cindex DCC
+OpenOCD can handle certain target requests; currently debugmsgs
+@command{target_request debugmsgs}
+are only supported for arm7_9 and cortex_m3.
-@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}|@var{charmsg}>
-@cindex target_request debugmsgs
-@*Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running. @var{charmsg} receives messages if Linux kernel ``Kernel low-level debugging via EmbeddedICE DCC channel'' option is enabled.
-@end itemize
+Linux-ARM kernels have a ``Kernel low-level debugging
+via EmbeddedICE DCC channel'' option (CONFIG_DEBUG_ICEDCC,
+depends on CONFIG_DEBUG_LL) which uses this mechanism to
+deliver messages before a serial console can be activated.
+
+@deffn Command {target_request debugmsgs} [enable|disable|charmsg]
+Displays current handling of target DCC message requests.
+These messages may be sent to the debugger while the target is running.
+The optional @option{enable} and @option{charmsg} parameters
+both enable the messages, while @option{disable} disables them.
+With @option{charmsg} the DCC words each contain one character,
+as used by Linux with CONFIG_DEBUG_ICEDCC;
+otherwise the libdcc format is used.
+@end deffn
@node JTAG Commands
@chapter JTAG Commands
The way this works on the ZY1000 is to prefix a filename by
"/tftp/ip/" and append the TFTP path on the TFTP
-server (tftpd). E.g. "load_image /tftp/10.0.0.96/c:\temp\abc.elf" will
-load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
+server (tftpd). For example,
+
+@example
+load_image /tftp/10.0.0.96/c:\temp\abc.elf
+@end example
+
+will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
if the file was hosted on the embedded host.
In order to achieve decent performance, you must choose a TFTP server
To start OpenOCD with a target script for the AT91R40008 CPU and reset
the CPU upon startup of the OpenOCD daemon.
@example
-openocd -f interface/parport.cfg -f target/at91r40008.cfg -c init -c reset
+openocd -f interface/parport.cfg -f target/at91r40008.cfg \
+ -c "init" -c "reset"
@end example
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
+@anchor{Connecting to GDB}
@section Connecting to GDB
@cindex Connecting to GDB
-@anchor{Connecting to GDB}
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For
instance GDB 6.3 has a known bug that produces bogus memory access
errors, which has since been fixed: look up 1836 in
@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
-@*OpenOCD can communicate with GDB in two ways:
+OpenOCD can communicate with GDB in two ways:
+
@enumerate
@item
A socket (TCP/IP) connection is typically started as follows:
session.
@end enumerate
-@*To see a list of available OpenOCD commands type @option{monitor help} on the
+To list the available OpenOCD commands type @command{monitor help} on the
GDB command line.
OpenOCD supports the gdb @option{qSupported} packet, this enables information
By low-level, the intent is a human would not directly use these commands.
-Low-level commands are (should be) prefixed with "openocd_", e.g. openocd_flash_banks
-is the low level API upon which "flash banks" is implemented.
+Low-level commands are (should be) prefixed with "ocd_", e.g.
+@command{ocd_flash_banks}
+is the low level API upon which @command{flash banks} is implemented.
@itemize @bullet
@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
+@quotation Note
+We should add support for a variable like Tcl variable
+@code{tcl_platform(platform)}, it should be called
+@code{jim_platform} (because it
+is jim, not real tcl).
+@end quotation
+
@node Upgrading
@chapter Deprecated/Removed Commands
@cindex Deprecated/Removed Commands
@itemize @bullet
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
-@*use @option{arm7_9 fast_memory_access} command with same args. @xref{arm7_9 fast_memory_access}.
+@*Use @command{arm7_9 fast_memory_access} instead.
+@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@cindex arm7_9 force_hw_bkpts
@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
@item @b{flash auto_erase}
@cindex flash auto_erase
@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
+
+@item @b{jtag_speed} value
+@*@xref{JTAG Speed}.
+Usually, a value of zero means maximum
+speed. The actual effect of this option depends on the JTAG interface used.
+@itemize @minus
+@item wiggler: maximum speed / @var{number}
+@item ft2232: 6MHz / (@var{number}+1)
+@item amt jtagaccel: 8 / 2**@var{number}
+@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
+@comment end speed list.
+@end itemize
+
@item @b{load_binary}
@cindex load_binary
@*use @option{load_image} command with same args. @xref{load_image}.
@chapter FAQ
@cindex faq
@enumerate
+@anchor{FAQ RTCK}
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
@cindex RTCK
@cindex adaptive clocking
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.
+software breakpoints consume one of the two available hardware breakpoints.
@item @b{LPC2000 Flash} When erasing or writing LPC2000 on-chip flash, the operation fails at random.
arm7_9_execute_sys_speed(): timeout waiting for SYSCOMP
TODO.
-
+
@end enumerate
@node Tcl Crash Course
SetResult( interp, "WRONG number of parameters");
return ERROR;
@}
-
+
// argv[0] = the ascii string just like C
// Execute the start statement.
SetResult( interp, "" );
return SUCCESS;
@}
-@end example
+@end example
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works
in the same basic way.
@* SOURCE reads a file and executes as a script.
@end enumerate
@subsection format command
-@b{Where:} Generally occurs in numerous places.
+@b{Where:} Generally occurs in numerous places.
@* Tcl has no command like @b{printf()}, instead it has @b{format}, which is really more like
@b{sprintf()}.
@b{Example}
is set to 10kHz for reset and 8MHz for post reset.
@example
-openocd -f interface/parport.cfg -f target/str710.cfg -c "init" -c "reset"
+openocd -f interface/parport.cfg -f target/str710.cfg \
+ -c "init" -c "reset"
@end example
To list the target scripts available:
@printindex cp
-@node OpenOCD Command Index
-@unnumbered OpenOCD Command Index
+@node Command and Driver Index
+@unnumbered Command and Driver Index
@printindex fn
@bye
Code Review / openocd.git / blobdiff