X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=21552589bdb5e8a57ebade489bc378addae71f95;hb=f37a8136fea415a91d732e9e81d4583a3a4ccf29;hp=261c41d1d1d2793307b41fb888adf68f3a35c188;hpb=ad8f1b42956bdf463ce85ed741e1f62ba91ae62f;p=openocd.git

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 261c41d1d1..21552589bd 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -82,7 +82,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger
 @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
@@ -110,7 +110,7 @@ OpenOCD internally. @xref{JTAG Hardware Dongles}.
 
 @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
@@ -261,7 +261,7 @@ a FTDI FT2232 based interface:
 @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.
@@ -320,9 +320,11 @@ should be included (among other things):
 @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
@@ -369,43 +371,54 @@ files ``in an appropriate place'' As a result, there are two
 
 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
@@ -467,9 +480,10 @@ and has a built in relay to power cycle targets remotely.
 
 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:
 
@@ -483,19 +497,23 @@ 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
@@ -561,7 +579,8 @@ produced, PDF schematics are easily found and it is easy to make.
 @* 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
@@ -579,12 +598,13 @@ produced, PDF schematics are easily found and it is easy to make.
 @* 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
 
@@ -715,7 +735,7 @@ You can use a series of ``-f filename'' options on the command line,
 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
@@ -804,11 +824,6 @@ A preconfigured interface file should exist for every interface in use
 today, that said, perhaps some interfaces have only been used by the
 sole developer who created it.
 
-@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
@@ -879,8 +894,10 @@ error or warning like this. The hope is that this will help to pinpoint
 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
@@ -987,7 +1004,8 @@ After the ``defaults'' are choosen [see above] the taps are created.
 @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:}
@@ -1005,14 +1023,16 @@ if @{ [info exists FLASHTAPID ] @} @{
 @} 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 ] @} @{
@@ -1020,7 +1040,8 @@ 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
@@ -1143,7 +1164,6 @@ can type a Tcl for() loop, set variables, etc.
 @* See: @xref{Tcl Crash Course}.
 @end itemize
 
-
 @node Daemon Configuration
 @chapter Daemon Configuration
 @cindex initialization
@@ -1471,6 +1491,8 @@ egnite Software turtelizer2
 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}>
@@ -1551,67 +1573,133 @@ jtag_rclk 3000
 @cindex Reset Configuration
 
 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:
+configuration. This can also be quite confusing.
+Please see the various board files for examples.
+
+@b{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.
+
+@section Types of Reset
+
+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.
+
 @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.
+@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
 
-The Command:
+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}.)
+
+@section SRST and TRST Signal Issues
+
+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
-@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
+
+@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
+
+There can also be other issues.
+Some devices don't fully conform to the JTAG specifications.
+Others have chip-specific extensions like extra steps needed
+during TAP reset, or a requirement to use the normally-optional TRST
+signal.
+Trivial system-specific differences are common, such as
+SRST and TRST using slightly different names.
+
+@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 signals [combination [trst_type [srst_type]]]
+This command tells OpenOCD the reset configuration
+of your combination of JTAG interface, board, and target.
+If the JTAG interface provides SRST, but the board 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
+The @var{combination} is an optional value specifying broken reset
 signal implementations.  @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
@@ -1621,17 +1709,14 @@ haven't seen hardware with such a bug, and can be worked around).
 @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
+The optional @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
-
+@end deffn
 
 
 @node Tap Creation
@@ -2020,7 +2105,10 @@ creates and invokes small procedure. The second inlines the procedure.
        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
@@ -2189,27 +2277,16 @@ Example:
 
 @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
@@ -2321,193 +2398,265 @@ if the @option{erase} parameter is given.
 @*Enable (@var{on}) or disable (@var{off}) protection of flash sectors <@var{first}> to
 <@var{last}> of @option{flash bank} <@var{num}>.
 
-@subsection mFlash commands
-@cindex mFlash commands
+@section flash bank command
+The @command{flash bank} command is used to configure one or more flash
+chips (or @emph{banks} in OpenOCD terms).
+Most CPUs have the ablity to ``boot'' from the first flash bank.
+
+@quotation Note
+This command is not available after OpenOCD initialization has completed.
+Use it in board specific configuration files, not interactively.
+@end quotation
+
+@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 @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 @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
+@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)
-
-@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
+@section Flash Drivers, Options, and Commands
+@anchor{Flash Driver List}
+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
 
-@subsubsection at91sam7 options
-@cindex at91sam7 options
+@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.
 
-@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. 
+@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 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} 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.}
 
-@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 stellaris 0 0 0 0 $_TARGETNAME
+@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} 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 Stellaris (LM3Sxxx) options
-@cindex Stellaris (LM3Sxxx) options
+@example
+flash bank stm32x 0 0 0 0 $_TARGETNAME
+@end example
 
-@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Stellaris flash plugin only require the @var{target}.
+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:
 
-@subsubsection stm32x options
-@cindex stm32x options
+@deffn Command {stm32x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
 
-@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*stm32x flash plugin only require the @var{target}.
+@deffn Command {stm32x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
 
-@subsubsection aduc702x options
-@cindex aduc702x options
+@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
 
-@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).
+@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
 
-@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 {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
+
+@subsection str9xpec driver
+@cindex str9xpec
 
-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.
+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
@@ -2542,25 +2691,45 @@ When performing a unlock remember that you will not be able to halt the str9 - i
 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
+@subsubsection str9xpec driver options
+
+@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{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
+@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
 
-@subsection STR9 option byte configuration
+@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
@@ -2576,37 +2745,57 @@ NBBADR - Boot Bank Start Address register
 @*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
@@ -2694,7 +2883,7 @@ initialization has completed.  Use it in board specific
 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
@@ -2761,6 +2950,7 @@ spare areas associated with each data page.
 
 @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
@@ -2776,6 +2966,7 @@ will still report that the block ``is'' bad.
 
 @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.
@@ -2875,7 +3066,7 @@ bypassing hardware ECC logic.
 with the wrong ECC data can cause them to be marked as bad.
 @end deffn
 
-@section NAND Drivers; Driver-specific Options and Commands
+@section NAND Drivers, Options, and Commands
 @anchor{NAND Driver List}
 As noted above, the @command{nand device} command allows
 driver-specific options and behaviors.
@@ -2901,7 +3092,7 @@ the @command{nand raw_access} command.
 @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}.
@@ -2926,7 +3117,10 @@ or @code{read_page} methods, so @command{nand raw_access} won't
 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.
@@ -3053,11 +3247,14 @@ OpenOCD will wait 5 seconds for the target to resume.
 @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
@@ -3182,7 +3379,6 @@ Profiling samples the CPU's program counter as quickly as possible, which is use
 @cindex Target Specific Commands
 
 
-@page
 @section Architecture Specific Commands
 @cindex Architecture Specific Commands
 
@@ -3455,8 +3651,13 @@ be used to access files on PCs (either the developer's PC or some other PC).
 
 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
@@ -3486,7 +3687,8 @@ Detailed information about each section can be found at OpenOCD configuration.
 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
 
 
@@ -3504,7 +3706,8 @@ 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:
@@ -3522,7 +3725,7 @@ Using this method has the advantage of GDB starting/stopping OpenOCD for the deb
 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
@@ -3626,8 +3829,9 @@ should be passed in to the proc in question.
 
 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}>
@@ -3664,6 +3868,13 @@ holds one of the following values:
 
 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
@@ -3672,7 +3883,8 @@ Certain OpenOCD commands have been deprecated/removed during the various revisio
 @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
@@ -4370,7 +4582,8 @@ finally issues the init and reset commands. The communication speed
 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:
@@ -4395,8 +4608,8 @@ at91sam9260.cfg  nslu2.cfg     sam7x256.cfg    wi-9c.cfg
 
 @printindex cp
 
-@node OpenOCD Command Index
-@unnumbered OpenOCD Command Index
+@node Command and Driver Index
+@unnumbered Command and Driver Index
 @printindex fn
 
 @bye