* 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
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}
@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
@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.
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
@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)/lib/openocd} :
@itemize @bullet
@item @b{interface}
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 via 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.
+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.
+
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@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 via 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
+The board config file should contain one or more @command{source [find
target/FOO.cfg]} statements along with any board specific things.
In summary the board files should contain (if present)
@end enumerate
@section Target Config Files
-@cindex config file
+@cindex config file, target
+@cindex target config file
-The user should be able to source one of these files via a command like this:
+Board config files should be able to source one or more
+target config files via a command like this:
@example
- source [find target/FOOBAR.cfg]
-Or:
- openocd -f target/FOOBAR.cfg
+source [find target/FOOBAR.cfg]
@end example
In summary the target files should contain
@enumerate
@item Set defaults
@item Add TAPs to the scan chain
-@item Add CPU targets
+@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 Important variable names
-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.
+Most boards will 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
@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.
+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
If the chip has 2 targets, use the names @b{_TARGETNAME0},
@b{_TARGETNAME1}, ... etc.
-@b{Remember:} The ``board file'' may include multiple targets.
-
-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.
-
-The user (or board file) should reasonably be able to:
+@emph{Remember:} The ``board file'' may include multiple targets.
+The user (or board) config file should reasonably be able to:
@example
- source [find target/FOO.cfg]
- $_TARGETNAME configure ... FOO specific parameters
+source [find target/FOO.cfg]
+$_TARGETNAME configure ... FOO specific parameters
- source [find target/BAR.cfg]
- $_TARGETNAME configure ... BAR specific parameters
+source [find target/BAR.cfg]
+$_TARGETNAME configure ... BAR specific parameters
@end example
@end itemize
a leading underscore are temporary in nature, and can be modified and
used at will within a ?TARGET? configuration file.
-@b{EXAMPLE:} The user should be able to do this:
+@b{EXAMPLE:} The user config file should be able to do this:
@example
# Board has 3 chips,
@item @b{Scripts}
@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's
-command interpreter today (28/nov/2008) is a mixture of (newer)
+command interpreter today is a mixture of (newer)
JIM-Tcl commands, and (older) the orginal command interpreter.
@item @b{Commands}
@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
probes flash memory, performs low-level JTAG operations, and more.
@section Scan Chains
+@cindex scan chain
TAPs are part of a hardware @dfn{scan chain},
which is daisy chain of TAPs.
@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
@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
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}
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.
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