@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
* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
* NAND Flash Commands:: NAND Flash Commands
+* PLD/FPGA Commands:: PLD/FPGA Commands
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
* JTAG Commands:: JTAG Commands
around the world.
@section What is OpenOCD?
+@cindex TAP
+@cindex JTAG
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
@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.
suggestions:
@enumerate
-@item @b{Send patches, including config files, upstream.}
-@item @b{Always build with printer ports enabled.}
-@item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
+@item Send patches, including config files, upstream.
+@item Always build with printer ports enabled.
+@item Use libftdi + libusb for FT2232 support.
@end enumerate
-@itemize @bullet
-@item @b{Why YES to LIBFTDI + LIBUSB?}
-@itemize @bullet
-@item @b{LESS} work - libusb perhaps already there
-@item @b{LESS} work - identical code, multiple platforms
-@item @b{MORE} dongles are supported
-@item @b{MORE} platforms are supported
-@item @b{MORE} complete solution
-@end itemize
-@item @b{Why not LIBFTDI + LIBUSB} (i.e.: ftd2xx instead)?
-@itemize @bullet
-@item @b{LESS} speed - some say it is slower
-@item @b{LESS} complex to distribute (external dependencies)
-@end itemize
-@end itemize
-
@section Building From Source
You can download the current SVN version with an SVN client of your choice from the
@itemize @bullet
@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
-@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
-@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
-homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
+@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}),
+or the Amontec version (from @uref{http://www.amontec.com}),
+for easier support of JTAGkey's vendor and product IDs.
@end itemize
libftdi is supported under Windows. Do not use versions earlier than 0.14.
+To use the newer FT2232H chips, supporting RTCK and USB high speed (480 Mbps),
+you need libftdi version 0.16 or newer.
-In general, the D2XX driver provides superior performance (several times as fast),
-but has the draw-back of being binary-only - though that isn't that bad, as it isn't
-a kernel module, only a user space library.
+Some people say that FTDI's libftd2xx code provides better performance.
+However, it is binary-only, while OpenOCD is licenced according
+to GNU GPLv2 without any exceptions.
+That means that @emph{distributing} copies of OpenOCD built with
+the FTDI code would violate the OpenOCD licensing terms.
+You may, however, build such copies for personal use.
To build OpenOCD (on both Linux and Cygwin), use the following commands:
@item
@option{--enable-gw16012} - Enable building support for the Gateworks GW16012 JTAG programmer.
@item
-@option{--enable-ft2232_ftd2xx} - Numerous USB type ARM JTAG dongles use the FT2232C chip from this FTDICHIP.COM chip (closed source).
+@option{--enable-ft2232_ftd2xx} - Support FT2232-family chips using
+the closed-source library from FTDICHIP.COM
+(result not for re-distribution).
@item
-@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
+@option{--enable-ft2232_libftdi} - Support FT2232-family chips using
+a GPL'd ft2232 support library (result OK for re-distribution).
@item
@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@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.
+@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static.
+Specifies how the FTDICHIP.COM libftd2xx driver should be linked.
+Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}.
+The 'shared' value is supported, however you must manually install the required
+header files and shared libraries in an appropriate place.
@item
@option{--enable-presto_libftdi} - Enable building support for ASIX Presto programmer using the libftdi driver.
@item
There are 2 methods of using the FTD2232, either (1) using the
FTDICHIP.COM closed source driver, or (2) the open (and free) driver
-libftdi. Some claim the (closed) FTDICHIP.COM solution is faster.
+libftdi. Some claim the (closed) FTDICHIP.COM solution is faster,
+which is the motivation for supporting it even though its licensing
+restricts it to non-redistributable OpenOCD binaries, and it is
+not available for all operating systems used with OpenOCD.
The FTDICHIP drivers come as either a (win32) ZIP file, or a (Linux)
TAR.GZ file. You must unpack them ``some where'' convient. As of this
-writing (12/26/2008) FTDICHIP does not supply means to install these
-files ``in an appropriate place'' As a result, there are two
+writing FTDICHIP does not supply means to install these
+files ``in an appropriate place''.
+As a result, there are two
``./configure'' options that help.
Below is an example build process:
@cindex zy1000
@cindex printer port
@cindex USB Adapter
-@cindex rtck
+@cindex RTCK
Defined: @b{dongle}: A small device that plugins into a computer and serves as
an adapter .... [snip]
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:
-
@itemize @bullet
@item @b{usbjtag}
@* Link @url{http://www.hs-augsburg.de/~hhoegl/proj/usbjtag/usbjtag.html}
@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 running OpenOCD
-@cindex --configfile
-@cindex --debug_level
-@cindex --logfile
-@cindex --search
+@cindex command line options
+@cindex logfile
+@cindex directory search
The @option{--help} option shows:
@verbatim
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
@option{debug_level} to "3", outputting the most information,
including debug messages. The default setting is "2", outputting only
informational messages, warnings and errors. You can also change this
-setting from within a telnet or gdb session using @option{debug_level
-<n>} @xref{debug_level}.
+setting from within a telnet or gdb session using @command{debug_level
+<n>} (@pxref{debug_level}).
You can redirect all output from the daemon to a file using the
@option{-l <logfile>} switch.
When you start OpenOCD from that directory,
it searches there first for configuration files
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
to simplify your work.
@section User Config Files
-@cindex config file
+@cindex config file, user
@cindex user config file
+@cindex config file, overview
A user configuration file ties together all the parts of a project
in one place.
@item Ideally almost everything comes from configuration files
provided by someone else.
For example, OpenOCD distributes a @file{scripts} directory
-(probably in @file{/usr/share/openocd/scripts} on Linux);
-board and tool vendors can provide these too.
+(probably in @file{/usr/share/openocd/scripts} on Linux).
+Board and tool vendors can provide these too, as can individual
+user sites; the @option{-s} command line option lets you say
+where to find these files. (@xref{Running}.)
The AT91SAM7X256 example above works this way.
Three main types of non-user configuration file each have their
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
@node Config File Guidelines
@chapter Config File Guidelines
-This section/chapter is aimed at developers and integrators of
-OpenOCD. These are guidelines for creating new boards and new target
-configurations as of 28/Nov/2008.
-
-However, you, the user of OpenOCD, should be somewhat familiar with
-this section as it should help explain some of the internals of what
-you might be looking at.
+This chapter is aimed at any user who needs to write a config file,
+including developers and integrators of OpenOCD and any user who
+needs to get a new board working smoothly.
+It provides guidelines for creating those files.
-The user 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.
the target config file defines all of them.
@end itemize
-@b{If needed...} The user in their ``openocd.cfg'' file or the board
-file might override a specific feature in any of the above files by
-setting a variable or two before sourcing the target file. Or adding
-various commands specific to their situation.
+The @file{openocd.cfg} user config
+file may override features in any of the above files by
+setting variables before sourcing the target file, or by adding
+commands specific to their situation.
@section Interface Config Files
-@cindex config file
-The user should be able to source one of these files via a command like this:
+The user config file
+should be able to source one of these files with a command like this:
@example
- source [find interface/FOOBAR.cfg]
-Or:
- openocd -f interface/FOOBAR.cfg
+source [find interface/FOOBAR.cfg]
@end example
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.
-Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
+A separate chapter gives information about how to set these up.
+@xref{Interface - Dongle Configuration}.
+Read the OpenOCD source code if you have a new kind of hardware interface
+and need to provide a driver for it.
@section Board Config Files
-@cindex config file
-
-@b{Note: BOARD directory NEW as of 28/nov/2008}
+@cindex config file, board
+@cindex board config file
-The user should be able to source one of these files via a command like this:
+The user config file
+should be able to source one of these files with a command like this:
@example
- source [find board/FOOBAR.cfg]
-Or:
- openocd -f board/FOOBAR.cfg
+source [find board/FOOBAR.cfg]
@end example
-
-The board file should contain one or more @t{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
+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 user should be able to source one of these files via a command like this:
+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.
-@example
- source [find target/FOOBAR.cfg]
-Or:
- openocd -f target/FOOBAR.cfg
-@end example
+@subsection Communication Between Config files
-In summary the target files should contain
+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.
-@enumerate
-@item Set defaults
-@item Add TAPs to the scan chain
-@item Add CPU targets
-@item CPU/Chip/CPU-Core specific features
-@item On-Chip flash
-@end enumerate
+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:
-@subsection Important variable names
+@example
+# 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
-By default, the end user should never need to set these
-variables. However, if the user needs to override a setting they only
-need to set the variable in a simple way.
+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.)
+
+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.
+
+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.
+
+@subsection Variable Naming Convention
+@cindex variable names
+
+Most boards have only one instance of a chip.
+However, it should be easy to create a board with more than
+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.
-@item @b{ENDIAN}
-@* By default little - unless the chip or board is not normally used that way.
-@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{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 @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.
+@subsection The reset-init Event Handler
+@cindex event, reset-init
+@cindex reset-init handler
-@b{Remember:} The ``board file'' may include multiple targets.
+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.
-At no time should the name ``target0'' (the default target name if
-none was specified) be used. The name ``target0'' is a hard coded name
-- the next target on the board will be some other number.
-In the same way, avoid using target numbers even when they are
-permitted; use the right target name(s) for your board.
+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.
-The user (or board file) should reasonably be able to:
+@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
-@example
- source [find target/FOO.cfg]
- $_TARGETNAME configure ... FOO specific parameters
+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.
- source [find target/BAR.cfg]
- $_TARGETNAME configure ... BAR specific parameters
-@end example
+@section Target Config Files
+@cindex config file, target
+@cindex target config file
-@end itemize
+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:
-@subsection Tcl Variables Guide Line
-The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
+@example
+source [find target/FOOBAR.cfg]
+@end example
-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.
+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
-@b{EXAMPLE:} The user should be able to do this:
+@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
-@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
-@end example
+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 (28/nov/2008) 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
@cindex port
+@cindex security
The OpenOCD server accepts remote commands in several syntaxes.
Each syntax uses a different TCP/IP port, which you may specify
only during configuration (before those ports are opened).
+For reasons including security, you may wish to prevent remote
+access using one or more of these ports.
+In such cases, just specify the relevant port number as zero.
+If you disable all access through TCP/IP, you will need to
+use the command line @option{-pipe} option.
+
@deffn {Command} gdb_port (number)
@cindex GDB server
Specify or query the first port used for incoming GDB connections.
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
+When specified as zero, this port is not activated.
@end deffn
@deffn {Command} tcl_port (number)
Intended as a machine interface.
When not specified during the configuration stage,
the port @var{number} defaults to 6666.
+When specified as zero, this port is not activated.
@end deffn
@deffn {Command} telnet_port (number)
This port is intended for interaction with one human through TCL commands.
When not specified during the configuration stage,
the port @var{number} defaults to 4444.
+When specified as zero, this port is not activated.
@end deffn
@anchor{GDB Configuration}
@node Interface - Dongle Configuration
@chapter Interface - Dongle Configuration
+@cindex config file, interface
+@cindex interface config file
+
JTAG Adapters/Interfaces/Dongles are normally configured
through commands in an interface configuration
file which is sourced by your @file{openocd.cfg} file, or
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}.)
+They can also interact with JTAG routers.
Please see the various board files for examples.
@quotation Note
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
+user configuration file will need to override parts of
the reset configuration provided by other files.
@end quotation
board-specific script might do things like setting up DRAM.
(@xref{Reset Command}.)
+@anchor{SRST and TRST Issues}
@section SRST and TRST Issues
Because SRST and TRST are hardware signals, they can have a
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 either 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.
+Missing TRST is not a problem, since JTAG level resets can
+be triggered using with TMS signaling.
@item @emph{Signals shorted} ... Sometimes a chip, board, or
adapter will connect SRST to TRST, instead of keeping them separate.
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.
+Information earlier in this section describes the kind of problems
+the command is intended to address (@pxref{SRST and TRST Issues}).
+As a rule this command belongs only in board config files,
+describing issues like @emph{board doesn't connect TRST};
+or in user config files, addressing limitations derived
+from a particular combination of interface and board.
+(An unlikely example would be using a TRST-only adapter
+with a board that only wires up SRST.)
The @var{mode_flag} options can be specified in any order, but only one
of each type -- @var{signals}, @var{combination}, @var{trst_type},
probes flash memory, performs low-level JTAG operations, and more.
@section Scan Chains
-
-OpenOCD uses a JTAG adapter (interface) to talk to your board,
-which has a daisy chain of TAPs.
-That daisy chain is called a @dfn{scan chain}.
-Simple configurations may have a single TAP in the scan chain,
-perhaps for a microcontroller.
-Complex configurations might have a dozen or more TAPs:
+@cindex scan chain
+
+TAPs are part of a hardware @dfn{scan chain},
+which is daisy chain of TAPs.
+They also need to be added to
+OpenOCD's software mirror of that hardware list,
+giving each member a name and associating other data with it.
+Simple scan chains, with a single TAP, are common in
+systems with a single microcontroller or microprocessor.
+More complex chips may have several TAPs internally.
+Very complex scan chains might have a dozen or more TAPs:
several in one chip, more in the next, and connecting
to other boards with their own chips and TAPs.
+You can display the list with the @command{scan_chain} command.
+(Don't confuse this with the list displayed by the @command{targets}
+command, presented in the next chapter.
+That only displays TAPs for CPUs which are configured as
+debugging targets.)
+Here's what the scan chain might look like for a chip more than one TAP:
+
+@verbatim
+ TapName Enabled IdCode Expected IrLen IrCap IrMask Instr
+-- ------------------ ------- ---------- ---------- ----- ----- ------ -----
+ 0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0 0 0x...
+ 1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x1 0 0xc
+ 2 omap5912.unknown Y 0x00000000 0x00000000 8 0 0 0xff
+@end verbatim
+
Unfortunately those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
-(JTAG doesn't require supporting IDCODE instructions.)
+JTAG doesn't require supporting IDCODE instructions, and
+chips with JTAG routers may not link TAPs into the chain
+until they are told to do so.
+
The configuration mechanism currently supported by OpenOCD
requires explicit configuration of all TAP devices using
-@command{jtag newtap} commands.
-One like this would declare a tap and name it @code{chip1.cpu}:
+@command{jtag newtap} commands, as detailed later in this chapter.
+A command like this would declare one tap and name it @code{chip1.cpu}:
@example
jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
@option{str912}, to support more than one chip of each type.
@xref{Config File Guidelines}.
+At this writing there is only a single command to work with
+scan chains, and there is no support for enumerating
+TAPs or examining their attributes.
+
+@deffn Command {scan_chain}
+Displays the TAPs in the scan chain configuration,
+and their status.
+The set of TAPs listed by this command is fixed by
+exiting the OpenOCD configuration stage,
+but systems with a JTAG router can
+enable or disable TAPs dynamically.
+In addition to the enable/disable status, the contents of
+each TAP's instruction register can also change.
+@end deffn
+
+@c FIXME! there should be commands to enumerate TAPs
+@c and get their attributes, like there are for targets.
+@c "jtag cget ..." will handle attributes.
+@c "jtag names" for enumerating TAPs, maybe.
+
+@c Probably want "jtag eventlist", and a "tap-reset" event
+@c (on entry to RESET state).
+
@section TAP Names
+@cindex dotted name
When TAP objects are declared with @command{jtag newtap},
a @dfn{dotted.name} is created for the TAP, combining the
should not be counted upon.
Update all of your scripts to use TAP names rather than numbers.
Using TAP numbers in target configuration scripts prevents
-reusing on boards with multiple targets.
+reusing those scripts on boards with multiple targets.
@end quotation
@section TAP Declaration Commands
@itemize @bullet
@item @code{-disable} (or @code{-enable})
-@*Use the @code{-disable} paramater to flag a TAP which is not
-linked in to the scan chain when it is declared.
+@*Use the @code{-disable} parameter to flag a TAP which is not
+linked in to the scan chain after a reset using either TRST
+or the JTAG state machine's @sc{reset} state.
You may use @code{-enable} to highlight the default state
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@anchor{Enabling and Disabling TAPs}
@section Enabling and Disabling TAPs
@cindex TAP events
+@cindex JTAG Route Controller
+@cindex jrc
In some systems, a @dfn{JTAG Route Controller} (JRC)
is used to enable and/or disable specific JTAG TAPs.
then look at how to add one more target and how to configure it.
@section Target List
+@cindex target, current
+@cindex target, list
All targets that have been set up are part of a list,
where each member has a name.
@end deffn
@section Target CPU Types and Variants
+@cindex target type
+@cindex CPU type
+@cindex CPU variant
Each target has a @dfn{CPU type}, as shown in the output of
the @command{targets} command. You need to specify that type
This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
be detected and the normal reset behaviour used.
@end itemize
+@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core. This supports one variant:
@itemize @minus
However, the documentation also uses ``flash'' as a generic term;
for example, ``Put flash configuration in board-specific files''.
-@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 @command{flash bank}
@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 (cortex-M3) microcontroller family from
+atmel include internal flash and use the 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 where cribbed from the data sheet [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 0x000080000 0 1 1 $_TARGETNAME
+# Flash bank 1 - only 256K chips
+flash bank at91sam3 0x000100000 0 1 1 $_TARGETNAME
+@end example
+
+Internally, the AT91SAM3 flash memory is organized as follows:
+
+@itemize
+@item @var{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @var{Bank Size:} 128K/64K Per flash bank
+@item @var{Sectors:} 16 or 8 per bank
+@item @var{SectorSize:} 8K Per Sector
+@item @var{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@end itemize
+
+The AT91SAM3 driver adds an additional command:
+
+@deffn Command {at91sam3 gpnvm set|clear|show all|NUMBER}
+This command allows you to set, clear, or show the state of the GPNVM bits.
+@end deffn
+
+@deffn Command {at91sam3 info}
+This command attempts to display information about the AT91SAM3
+chip. @b{First} it read the @var{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. @b{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 @b{at91sam3 slowclk}.
+@end deffn
+
+@deffn Command {at91sam3 slowclk [VALUE]}
+This command shows/sets the slow clock frequency used in the
+@b{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.
+@end deffn
+
@example
flash bank at91sam7 0 0 0 0 $_TARGETNAME
the appropriate at91sam7 target.
@end quotation
@end deffn
-@end deffn
@deffn {Flash Driver} avr
The AVR 8-bit microcontrollers from Atmel integrate flash memory.
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
change any behavior.
@end deffn
+@node PLD/FPGA Commands
+@chapter PLD/FPGA Commands
+@cindex PLD
+@cindex FPGA
+
+Programmable Logic Devices (PLDs) and the more flexible
+Field Programmable Gate Arrays (FPGAs) are both types of programmable hardware.
+OpenOCD can support programming them.
+Although PLDs are generally restrictive (cells are less functional, and
+there are no special purpose cells for memory or computational tasks),
+they share the same OpenOCD infrastructure.
+Accordingly, both are called PLDs here.
+
+@section PLD/FPGA Configuration and Commands
+
+As it does for JTAG TAPs, debug targets, and flash chips (both NOR and NAND),
+OpenOCD maintains a list of PLDs available for use in various commands.
+Also, each such PLD requires a driver.
+
+They are referenced by the number shown by the @command{pld devices} command,
+and new PLDs are defined by @command{pld device driver_name}.
+
+@deffn {Config Command} {pld device} driver_name tap_name [driver_options]
+Defines a new PLD device, supported by driver @var{driver_name},
+using the TAP named @var{tap_name}.
+The driver may make use of any @var{driver_options} to configure its
+behavior.
+@end deffn
+
+@deffn {Command} {pld devices}
+Lists the PLDs and their numbers.
+@end deffn
+
+@deffn {Command} {pld load} num filename
+Loads the file @file{filename} into the PLD identified by @var{num}.
+The file format must be inferred by the driver.
+@end deffn
+
+@section PLD/FPGA Drivers, Options, and Commands
+
+Drivers may support PLD-specific options to the @command{pld device}
+definition command, and may also define commands usable only with
+that particular type of PLD.
+
+@deffn {FPGA Driver} virtex2
+Virtex-II is a family of FPGAs sold by Xilinx.
+It supports the IEEE 1532 standard for In-System Configuration (ISC).
+No driver-specific PLD definition options are used,
+and one driver-specific command is defined.
+
+@deffn {Command} {virtex2 read_stat} num
+Reads and displays the Virtex-II status register (STAT)
+for FPGA @var{num}.
+@end deffn
+@end deffn
+
@node General Commands
@chapter General Commands
@cindex commands
This affects the kind of messages sent to the server log.
Level 0 is error messages only;
level 1 adds warnings;
-level 2 (the default) adds informational messages;
+level 2 adds informational messages;
and level 3 adds debugging messages.
+The default is level 2, but that can be overridden on
+the command line along with the location of that log
+file (which is normally the server's standard output).
+@xref{Running}.
@end deffn
@deffn Command fast (@option{enable}|@option{disable})
In this section ``target'' refers to a CPU configured as
shown earlier (@pxref{CPU Configuration}).
These commands, like many, implicitly refer to
-a @dfn{current target} which is used to perform the
+a current target which is used to perform the
various operations. The current target may be changed
by using @command{targets} command with the name of the
target which should become current.
to execute before they take effect.
@end deffn
-@deffn Command {scan_chain}
-Displays the TAPs in the scan chain configuration,
-and their status.
-The set of TAPs listed by this command is fixed by
-exiting the OpenOCD configuration stage,
-but systems with a JTAG router can
-enable or disable TAPs dynamically.
-In addition to the enable/disable status, the contents of
-each TAP's instruction register can also change.
-@end deffn
-
@c tms_sequence (short|long)
@c ... temporary, debug-only, probably gone before 0.2 ships
@end itemize
Note that only six of those states are fully ``stable'' in the
-face of TMS fixed (usually low)
+face of TMS fixed (low except for @sc{reset})
and a free-running JTAG clock. For all the
others, the next TCK transition changes to a new state.
parsed, but are NOT expanded or executed. @{Curly-Braces@} are like
'single-quote' operators in BASH shell scripts, with the added
feature: @{curly-braces@} can be nested, single quotes can not. @{@{@{this is
-nested 3 times@}@}@} NOTE: [date] is perhaps a bad example, as of
-28/nov/2008, Jim/OpenOCD does not have a date command.
+nested 3 times@}@}@} NOTE: [date] is a bad example;
+at this writing, Jim/OpenOCD does not have a date command.
@end itemize
@section Consequences of Rule 1/2/3/4
and the text is evaluated. In case #4, they are replaced before the
``Target Object Command'' is executed. This occurs at the same time
$_TARGETNAME is replaced. In case #4 the date will never
-change. @{BTW: [date] is perhaps a bad example, as of 28/nov/2008,
+change. @{BTW: [date] is a bad example; at this writing,
Jim/OpenOCD does not have a date command@}
@end enumerate
@subsection Global Variables
Code Review / openocd.git / blobdiff