@item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk}
@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com}
@item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com}
+@item Copyright @copyright{} 2009 David Brownell
@end itemize
@quotation
* Developers:: OpenOCD Developers
* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
+* About JIM-Tcl:: About JIM-Tcl
* Running:: Running OpenOCD
* OpenOCD Project Setup:: OpenOCD Project Setup
* Config File Guidelines:: Config File Guidelines
-* About JIM-Tcl:: About JIM-Tcl
* Daemon Configuration:: Daemon Configuration
* Interface - Dongle Configuration:: Interface - Dongle Configuration
* Reset Configuration:: Reset Configuration
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
+* Boundary Scan Commands:: Boundary Scan Commands
* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* Tcl Scripting API:: Tcl Scripting API
@b{Flash Programing:} Flash writing is supported for external CFI
compatible NOR flashes (Intel and AMD/Spansion command set) and several
-internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
+internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and
STM32x). Preliminary support for various NAND flash controllers
(LPC3180, Orion, S3C24xx, more) controller is included.
@end itemize
+@node About JIM-Tcl
+@chapter About JIM-Tcl
+@cindex JIM Tcl
+@cindex tcl
+
+OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl.
+This programming language provides a simple and extensible
+command interpreter.
+
+All commands presented in this Guide are extensions to JIM-Tcl.
+You can use them as simple commands, without needing to learn
+much of anything about Tcl.
+Alternatively, can write Tcl programs with them.
+
+You can learn more about JIM at its website, @url{http://jim.berlios.de}.
+
+@itemize @bullet
+@item @b{JIM vs. Tcl}
+@* JIM-TCL is a stripped down version of the well known Tcl language,
+which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
+fewer features. JIM-Tcl is a single .C file and a single .H file and
+implements the basic Tcl command set. In contrast: Tcl 8.6 is a
+4.2 MB .zip file containing 1540 files.
+
+@item @b{Missing Features}
+@* Our practice has been: Add/clone the real Tcl feature if/when
+needed. We welcome JIM Tcl improvements, not bloat.
+
+@item @b{Scripts}
+@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
+command interpreter today is a mixture of (newer)
+JIM-Tcl commands, and (older) the orginal command interpreter.
+
+@item @b{Commands}
+@* At the OpenOCD telnet command line (or via the GDB mon command) one
+can type a Tcl for() loop, set variables, etc.
+
+@item @b{Historical Note}
+@* JIM-Tcl was introduced to OpenOCD in spring 2008.
+
+@item @b{Need a crash course in Tcl?}
+@*@xref{Tcl Crash Course}.
+@end itemize
+
@node Running
@chapter Running
@cindex command line options
If you are having problems, you can enable internal debug messages via
the ``-d'' option.
-Also it is possible to interleave commands w/config scripts using the
+Also it is possible to interleave JIM-Tcl commands w/config scripts using the
@option{-c} command line switch.
To enable debug output (when reporting problems or working on OpenOCD
A simple way to organize them all involves keeping a
single directory for your work with a given board.
When you start OpenOCD from that directory,
-it searches there first for configuration files
+it searches there first for configuration files, scripts,
and for code you upload to the target board.
-It is also be the natural place to write files,
+It is also the natural place to write files,
such as log files and data you download from the board.
@section Configuration Basics
You could wrap such long command lines in shell scripts,
each supporting a different development task.
-One might re-flash the board with specific firmware version.
+One might re-flash the board with a specific firmware version.
Another might set up a particular debugging or run-time environment.
Here we will focus on the simpler solution: one user config
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file.
+TCP/IP port configuration is another example of something which
+is environment-specific, and should only appear in
+a user config file. @xref{TCP/IP Ports}.
+
@section Project-Specific Utilities
A few project-specific utility
needs to get a new board working smoothly.
It provides guidelines for creating those files.
-You should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
+You should find the following directories under @t{$(INSTALLDIR)/scripts}:
@itemize @bullet
-@item @b{interface}
-@*Think JTAG Dongle. Files that configure the JTAG dongle go here.
-@item @b{board}
-@* Think Circuit Board, PWA, PCB, they go by many names. Board files
-contain initialization items that are specific to a board - for
-example: The SDRAM initialization sequence for the board, or the type
-of external flash and what address it is found at. Any initialization
+@item @file{interface} ...
+think JTAG Dongle. Files that configure JTAG adapters go here.
+@item @file{board} ...
+think Circuit Board, PWA, PCB, they go by many names. Board files
+contain initialization items that are specific to a board. For
+example, the SDRAM initialization sequence for the board, or the type
+of external flash and what address it uses. Any initialization
sequence to enable that external flash or SDRAM should be found in the
-board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
+board file. Boards may also contain multiple targets: two CPUs; or
a CPU and an FPGA or CPLD.
-@item @b{target}
-@* Think chip. The ``target'' directory represents the JTAG TAPs
+@item @file{target} ...
+think chip. The ``target'' directory represents the JTAG TAPs
on a chip
which OpenOCD should control, not a board. Two common types of targets
are ARM chips and FPGA or CPLD chips.
@section Interface Config Files
The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
@example
source [find interface/FOOBAR.cfg]
Read the OpenOCD source code if you have a new kind of hardware interface
and need to provide a driver for it.
-Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
-
@section Board Config Files
@cindex config file, board
@cindex board config file
The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
@example
source [find board/FOOBAR.cfg]
@end example
-The board config file should contain one or more @command{source [find
-target/FOO.cfg]} statements along with any board specific things.
-
+The point of a board config file is to package everything
+about a given board that user config files need to know.
In summary the board files should contain (if present)
@enumerate
-@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
-@item SDRAM configuration (size, speed, etc.
-@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
-@item Multiple TARGET source statements
-@item Reset configuration
+@item One or more @command{source [target/...cfg]} statements
+@item NOR flash configuration (@pxref{NOR Configuration})
+@item NAND flash configuration (@pxref{NAND Configuration})
+@item Target @code{reset} handlers for SDRAM and I/O configuration
+@item JTAG adapter reset configuration (@pxref{Reset Configuration})
@item All things that are not ``inside a chip''
-@item Things inside a chip go in a 'target' file
@end enumerate
-@section Target Config Files
-@cindex config file, target
-@cindex target config file
+Generic things inside target chips belong in target config files,
+not board config files. So for example a @code{reset-init} event
+handler should know board-specific oscillator and PLL parameters,
+which it passes to target-specific utility code.
+
+The most complex task of a board config file is creating such a
+@code{reset-init} event handler.
+Define those handlers last, after you verify the rest of the board
+configuration works.
+
+@subsection Communication Between Config files
-Board config files should be able to source one or more
-target config files via a command like this:
+In addition to target-specific utility code, another way that
+board and target config files communicate is by following a
+convention on how to use certain variables.
+
+The full Tcl/Tk language supports ``namespaces'', but JIM-Tcl does not.
+Thus the rule we follow in OpenOCD is this: Variables that begin with
+a leading underscore are temporary in nature, and can be modified and
+used at will within a target configuration file.
+
+Complex board config files can do the things like this,
+for a board with three chips:
@example
-source [find target/FOOBAR.cfg]
+# Chip #1: PXA270 for network side, big endian
+set CHIPNAME network
+set ENDIAN big
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = network.cpu
+# other commands can refer to the "network.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #2: PXA270 for video side, little endian
+set CHIPNAME video
+set ENDIAN little
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = video.cpu
+# other commands can refer to the "video.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #3: Xilinx FPGA for glue logic
+set CHIPNAME xilinx
+unset ENDIAN
+source [find target/spartan3.cfg]
@end example
-In summary the target files should contain
+That example is oversimplified because it doesn't show any flash memory,
+or the @code{reset-init} event handlers to initialize external DRAM
+or (assuming it needs it) load a configuration into the FPGA.
+Such features are usually needed for low-level work with many boards,
+where ``low level'' implies that the board initialization software may
+not be working. (That's a common reason to need JTAG tools. Another
+is to enable working with microcontroller-based systems, which often
+have no debugging support except a JTAG connector.)
-@enumerate
-@item Set defaults
-@item Add TAPs to the scan chain
-@item Add CPU targets (includes GDB support)
-@item CPU/Chip/CPU-Core specific features
-@item On-Chip flash
-@end enumerate
+Target config files may also export utility functions to board and user
+config files. Such functions should use name prefixes, to help avoid
+naming collisions.
-As a rule of thumb, a target file sets up only one chip.
-For a microcontroller, that will often include a single TAP,
-which is a CPU needing a GDB target; and its on-chip flash.
+Board files could also accept input variables from user config files.
+For example, there might be a @code{J4_JUMPER} setting used to identify
+what kind of flash memory a development board is using, or how to set
+up other clocks and peripherals.
-More complex chips may include multiple TAPs, and the target
-config file may need to define them all before OpenOCD
-can talk to the chip.
-For example, some phone chips have JTAG scan chains that include
-an ARM core for operating system use, a DSP,
-another ARM core embedded in an image processing engine,
-and other processing engines.
-
-@subsection Important variable names
+@subsection Variable Naming Convention
+@cindex variable names
-Most boards will have only one instance of a chip.
+Most boards have only one instance of a chip.
However, it should be easy to create a board with more than
-one such chip.
-Accordingly, we encourage some conventions for naming
-variables associated with different TAPs, to promote
-consistency and
-so that board files can override target defaults, and
+one such chip (as shown above).
+Accordingly, we encourage these conventions for naming
+variables associated with different @file{target.cfg} files,
+to promote consistency and
+so that board files can override target defaults.
+
+Inputs to target config files include:
@itemize @bullet
-@item @b{CHIPNAME}
-@* This gives a name to the overall chip, and is used as part of the
-tap identifier dotted name.
-It's normally provided by the chip manufacturer.
-@item @b{ENDIAN}
-@* By default little - unless the chip or board is not normally used that way.
+@item @code{CHIPNAME} ...
+This gives a name to the overall chip, and is used as part of
+tap identifier dotted names.
+While the default is normally provided by the chip manufacturer,
+board files may need to distinguish between instances of a chip.
+@item @code{ENDIAN} ...
+By default @option{little} - although chips may hard-wire @option{big}.
Chips that can't change endianness don't need to use this variable.
-@item @b{CPUTAPID}
-@* When OpenOCD examines the JTAG chain, it will attempt to identify
-every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
-to verify the tap id number verses configuration file and may issue an
-error or warning like this. The hope is that this will help to pinpoint
-problems in OpenOCD configurations.
+@item @code{CPUTAPID} ...
+When OpenOCD examines the JTAG chain, it can be told verify the
+chips against the JTAG IDCODE register.
+The target file will hold one or more defaults, but sometimes the
+chip in a board will use a different ID (perhaps a newer revision).
+@end itemize
-@example
-Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
- (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
-Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678,
- Got: 0x3f0f0f0f
-Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
-Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
-@end example
+Outputs from target config files include:
-@item @b{_TARGETNAME}
-@* By convention, this variable is created by the target configuration
+@itemize @bullet
+@item @code{_TARGETNAME} ...
+By convention, this variable is created by the target configuration
script. The board configuration file may make use of this variable to
configure things like a ``reset init'' script, or other things
specific to that board and that target.
+If the chip has 2 targets, the names are @code{_TARGETNAME0},
+@code{_TARGETNAME1}, ... etc.
+@end itemize
-If the chip has 2 targets, use the names @b{_TARGETNAME0},
-@b{_TARGETNAME1}, ... etc.
-
-@emph{Remember:} The ``board file'' may include multiple targets.
-The user (or board) config file should reasonably be able to:
+@subsection The reset-init Event Handler
+@cindex event, reset-init
+@cindex reset-init handler
-@example
-source [find target/FOO.cfg]
-$_TARGETNAME configure ... FOO specific parameters
+Board config files run in the OpenOCD configuration stage;
+they can't use TAPs or targets, since they haven't been
+fully set up yet.
+This means you can't write memory or access chip registers;
+you can't even verify that a flash chip is present.
+That's done later in event handlers, of which the target @code{reset-init}
+handler is one of the most important.
-source [find target/BAR.cfg]
-$_TARGETNAME configure ... BAR specific parameters
-@end example
+Except on microcontrollers, the basic job of @code{reset-init} event
+handlers is setting up flash and DRAM, as normally handled by boot loaders.
+Microcontrollers rarely use boot loaders; they run right out of their
+on-chip flash and SRAM memory. But they may want to use one of these
+handlers too, if just for developer convenience.
-@end itemize
+@quotation Note
+Because this is so very board-specific, and chip-specific, no examples
+are included here.
+Instead, look at the board config files distributed with OpenOCD.
+If you have a boot loader, its source code may also be useful.
+@end quotation
-@subsection Tcl Variables Guide Line
-The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
+Some of this code could probably be shared between different boards.
+For example, setting up a DRAM controller often doesn't differ by
+much except the bus width (16 bits or 32?) and memory timings, so a
+reusable TCL procedure loaded by the @file{target.cfg} file might take
+those as parameters.
+Similarly with oscillator, PLL, and clock setup;
+and disabling the watchdog.
+Structure the code cleanly, and provide comments to help
+the next developer doing such work.
+(@emph{You might be that next person} trying to reuse init code!)
+
+The last thing normally done in a @code{reset-init} handler is probing
+whatever flash memory was configured. For most chips that needs to be
+done while the associated target is halted, either because JTAG memory
+access uses the CPU or to prevent conflicting CPU access.
+
+@subsection JTAG Clock Rate
+
+Before your @code{reset-init} handler has set up
+the PLLs and clocking, you may need to use
+a low JTAG clock rate; then you'd increase it later.
+(The rule of thumb for ARM-based processors is 1/8 the CPU clock.)
+If the board supports adaptive clocking, use the @command{jtag_rclk}
+command, in case your board is used with JTAG adapter which
+also supports it. Otherwise use @command{jtag_khz}.
+Set the slow rate at the beginning of the reset sequence,
+and the faster rate as soon as the clocks are at full speed.
-Thus the rule we follow in OpenOCD is this: Variables that begin with
-a leading underscore are temporary in nature, and can be modified and
-used at will within a ?TARGET? configuration file.
+@section Target Config Files
+@cindex config file, target
+@cindex target config file
-@b{EXAMPLE:} The user config file should be able to do this:
+Board config files communicate with target config files using
+naming conventions as described above, and may source one or
+more target config files like this:
@example
- # Board has 3 chips,
- # PXA270 #1 network side, big endian
- # PXA270 #2 video side, little endian
- # Xilinx Glue logic
- set CHIPNAME network
- set ENDIAN big
- source [find target/pxa270.cfg]
- # variable: _TARGETNAME = network.cpu
- # other commands can refer to the "network.cpu" tap.
- $_TARGETNAME configure .... params for this CPU..
-
- set ENDIAN little
- set CHIPNAME video
- source [find target/pxa270.cfg]
- # variable: _TARGETNAME = video.cpu
- # other commands can refer to the "video.cpu" tap.
- $_TARGETNAME configure .... params for this CPU..
-
- unset ENDIAN
- set CHIPNAME xilinx
- source [find target/spartan3.cfg]
-
- # Since $_TARGETNAME is temporal..
- # these names still work!
- network.cpu configure ... params
- video.cpu configure ... params
+source [find target/FOOBAR.cfg]
@end example
+The point of a target config file is to package everything
+about a given chip that board config files need to know.
+In summary the target files should contain
+
+@enumerate
+@item Set defaults
+@item Add TAPs to the scan chain
+@item Add CPU targets (includes GDB support)
+@item CPU/Chip/CPU-Core specific features
+@item On-Chip flash
+@end enumerate
+
+As a rule of thumb, a target file sets up only one chip.
+For a microcontroller, that will often include a single TAP,
+which is a CPU needing a GDB target, and its on-chip flash.
+
+More complex chips may include multiple TAPs, and the target
+config file may need to define them all before OpenOCD
+can talk to the chip.
+For example, some phone chips have JTAG scan chains that include
+an ARM core for operating system use, a DSP,
+another ARM core embedded in an image processing engine,
+and other processing engines.
+
@subsection Default Value Boiler Plate Code
-All target configuration files should start with this (or a modified form)
+All target configuration files should start with code like this,
+letting board config files express environment-specific
+differences in how things should be set up.
@example
-# SIMPLE example
+# Boards may override chip names, perhaps based on role,
+# but the default should match what the vendor uses
if @{ [info exists CHIPNAME] @} @{
set _CHIPNAME $CHIPNAME
@} else @{
set _CHIPNAME sam7x256
@}
+# ONLY use ENDIAN with targets that can change it.
if @{ [info exists ENDIAN] @} @{
set _ENDIAN $ENDIAN
@} else @{
set _ENDIAN little
@}
+# TAP identifiers may change as chips mature, for example with
+# new revision fields (the "3" here). Pick a good default; you
+# can pass several such identifiers to the "jtag newtap" command.
if @{ [info exists CPUTAPID ] @} @{
set _CPUTAPID $CPUTAPID
@} else @{
@}
@end example
+@emph{Remember:} Board config files may include multiple target
+config files, or the same target file multiple times
+(changing at least @code{CHIPNAME}).
+
+Likewise, the target configuration file should define
+@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and
+use it later on when defining debug targets:
+
+@example
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
+@end example
+
@subsection Adding TAPs to the Scan Chain
After the ``defaults'' are set up,
add the TAPs on each chip to the JTAG scan chain.
values for @code{CHIPNAME}, so
it adds a different TAP each time.
+If there are one or more nonzero @option{-expected-id} values,
+OpenOCD attempts to verify the actual tap id against those values.
+It will issue error messages if there is mismatch, which
+can help to pinpoint problems in OpenOCD configurations.
+
+@example
+JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
+ (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
+ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
+ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
+ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
+@end example
+
There are more complex examples too, with chips that have
multiple TAPs. Ones worth looking at include:
@itemize
-@item @file{target/omap3530.cfg} -- with a disabled ARM, and a JRC
-(there's a DSP too, which is not listed)
+@item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
+plus a JRC to enable them
@item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
@item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
is not currently used)
After adding a TAP for a CPU, you should set it up so that
GDB and other commands can use it.
@xref{CPU Configuration}.
-For the at91sam7 example above, the command can look like this:
+For the at91sam7 example above, the command can look like this;
+note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
+to little endian, and this chip doesn't support changing that.
@example
set _TARGETNAME $_CHIPNAME.cpu
@item pxa270 - again - CS0 flash - it goes in the board file.
@end itemize
-@node About JIM-Tcl
-@chapter About JIM-Tcl
-@cindex JIM Tcl
-@cindex tcl
-
-OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can
-learn more about JIM here: @url{http://jim.berlios.de}
-
-@itemize @bullet
-@item @b{JIM vs. Tcl}
-@* JIM-TCL is a stripped down version of the well known Tcl language,
-which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far
-fewer features. JIM-Tcl is a single .C file and a single .H file and
-impliments the basic Tcl command set along. In contrast: Tcl 8.6 is a
-4.2 MB .zip file containing 1540 files.
-
-@item @b{Missing Features}
-@* Our practice has been: Add/clone the real Tcl feature if/when
-needed. We welcome JIM Tcl improvements, not bloat.
-
-@item @b{Scripts}
-@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
-command interpreter today is a mixture of (newer)
-JIM-Tcl commands, and (older) the orginal command interpreter.
-
-@item @b{Commands}
-@* At the OpenOCD telnet command line (or via the GDB mon command) one
-can type a Tcl for() loop, set variables, etc.
-
-@item @b{Historical Note}
-@* JIM-Tcl was introduced to OpenOCD in spring 2008.
-
-@item @b{Need a crash course in Tcl?}
-@*@xref{Tcl Crash Course}.
-@end itemize
-
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
the memory read/write commands. This includes @command{nand probe}.
@end deffn
+@anchor{TCP/IP Ports}
@section TCP/IP Ports
@cindex TCP port
@cindex server
@end enumerate
Many CPUs have the ablity to ``boot'' from the first flash bank.
-This means that misprograming that bank can ``brick'' a system,
+This means that misprogramming that bank can ``brick'' a system,
so that it can't boot.
JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
board by (re)installing working boot firmware.
+@anchor{NOR Configuration}
@section Flash Configuration Commands
@cindex flash configuration
@end example
@end deffn
+@deffn {Flash Driver} at91sam3
+@cindex at91sam3
+All members of the AT91SAM3 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M3 core. The driver
+currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
+that the driver was orginaly developed and tested using the
+AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
+the family was cribbed from the data sheet. @emph{Note to future
+readers/updaters: Please remove this worrysome comment after other
+chips are confirmed.}
+
+The AT91SAM3U4[E/C] (256K) chips have 2 flash banks, the other chips
+(3U[1/2][E/C]) have 1 flash bank. In all cases the flash banks are at
+the following fixed locations:
+
+@example
+# Flash bank 0 - all chips
+flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
+# Flash bank 1 - only 256K chips
+flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
+@end example
+
+Internally, the AT91SAM3 flash memory is organized as follows.
+Unlike the AT91SAM7 chips, these are not used as parameters
+to the @command{flash bank} command:
+
+@itemize
+@item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @emph{Bank Size:} 128K/64K Per flash bank
+@item @emph{Sectors:} 16 or 8 per bank
+@item @emph{SectorSize:} 8K Per Sector
+@item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@end itemize
+
+The AT91SAM3 driver adds some additional commands:
+
+@deffn Command {at91sam3 gpnvm}
+@deffnx Command {at91sam3 gpnvm clear} number
+@deffnx Command {at91sam3 gpnvm set} number
+@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+With no parameters, @command{show} or @command{show all},
+shows the status of all GPNVM bits.
+With @command{show} @var{number}, displays that bit.
+
+With @command{set} @var{number} or @command{clear} @var{number},
+modifies that GPNVM bit.
+@end deffn
+
+@deffn Command {at91sam3 info}
+This command attempts to display information about the AT91SAM3
+chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
+Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
+document id: doc6430A] and decodes the values. @emph{Second} it reads the
+various clock configuration registers and attempts to display how it
+believes the chip is configured. By default, the SLOWCLK is assumed to
+be 32768 Hz, see the command @command{at91sam3 slowclk}.
+@end deffn
+
+@deffn Command {at91sam3 slowclk} [value]
+This command shows/sets the slow clock frequency used in the
+@command{at91sam3 info} command calculations above.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} at91sam7
-All members of the AT91SAM7 microcontroller family from Atmel
-include internal flash and use ARM7TDMI cores.
-The driver automatically recognizes a number of these chips using
-the chip identification register, and autoconfigures itself.
+All members of the AT91SAM7 microcontroller family from Atmel include
+internal flash and use ARM7TDMI cores. The driver automatically
+recognizes a number of these chips using the chip identification
+register, and autoconfigures itself.
@example
flash bank at91sam7 0 0 0 0 $_TARGETNAME
plane (of up to 256KB), and it will be used automatically when you issue
@command{flash erase_sector} or @command{flash erase_address} commands.
-@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
bit for the processor. Each processor has a number of such bits,
used for controlling features such as brownout detection (so they
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
-@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
Some larger devices will work, since they are actually multi-chip
modules with two smaller chips and individual chipselect lines.
+@anchor{NAND Configuration}
@section NAND Configuration Commands
@cindex NAND configuration
Consult the documentation for the TAP(s) you are working with.
@end itemize
+@node Boundary Scan Commands
+@chapter Boundary Scan Commands
+
+One of the original purposes of JTAG was to support
+boundary scan based hardware testing.
+Although its primary focus is to support On-Chip Debugging,
+OpenOCD also includes some boundary scan commands.
+
+@section SVF: Serial Vector Format
+@cindex Serial Vector Format
+@cindex SVF
+
+The Serial Vector Format, better known as @dfn{SVF}, is a
+way to represent JTAG test patterns in text files.
+OpenOCD supports running such test files.
+
+@deffn Command {svf} filename [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the SVF script from @file{filename}.
+Unless the @option{quiet} option is specified,
+each command is logged before it is executed.
+@end deffn
+
+@section XSVF: Xilinx Serial Vector Format
+@cindex Xilinx Serial Vector Format
+@cindex XSVF
+
+The Xilinx Serial Vector Format, better known as @dfn{XSVF}, is a
+binary representation of SVF which is optimized for use with
+Xilinx devices.
+OpenOCD supports running such test files.
+
+@quotation Important
+Not all XSVF commands are supported.
+@end quotation
+
+@deffn Command {xsvf} (tapname|@option{plain}) filename [@option{virt2}] [@option{quiet}]
+This issues a JTAG reset (Test-Logic-Reset) and then
+runs the XSVF script from @file{filename}.
+When a @var{tapname} is specified, the commands are directed at
+that TAP.
+When @option{virt2} is specified, the @sc{xruntest} command counts
+are interpreted as TCK cycles instead of microseconds.
+Unless the @option{quiet} option is specified,
+messages are logged for comments and some retries.
+@end deffn
+
@node TFTP
@chapter TFTP
@cindex TFTP