It is not to be confused with the FTDI based adapters that were originally fitted to their
evaluation boards. This is the adapter fitted to the Stellaris LaunchPad.
+@section USB CMSIS-DAP based
+ARM has released a interface standard called CMSIS-DAP that simplifies connecting
+debuggers to ARM Cortex based targets @url{http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm}.
+
@section USB Other
@itemize @bullet
@item @b{USBprog}
@c chooses among list of bit configs ... only one option
@end deffn
+@deffn {Interface Driver} {cmsis-dap}
+CMSIS-DAP compliant based adapter.
+
+@deffn {Config Command} {cmsis_dap_vid_pid} [vid pid]+
+The vendor ID and product ID of the CMSIS-DAP device. If not specified
+known default values are used.
+Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g.
+@example
+cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204
+@end example
+@end deffn
+
+@deffn {Command} {cmsis-dap info}
+Display various device information, like hardware version, firmware version, current bus status.
+@end deffn
+@end deffn
+
@deffn {Interface Driver} {dummy}
A dummy software-only driver for debugging.
@end deffn
No parameters: displays current settings.
@end deffn
+@subsection CMSIS-DAP Transport
+@cindex CMSIS-DAP
+CMSIS-DAP is an ARM-specific transport that is used to connect to
+compilant debuggers.
+
@subsection SPI Transport
@cindex SPI
@cindex Serial Peripheral Interface
TAPs serve many roles, including:
@itemize @bullet
-@item @b{Debug Target} A CPU TAP can be used as a GDB debug target
+@item @b{Debug Target} A CPU TAP can be used as a GDB debug target.
@item @b{Flash Programming} Some chips program the flash directly via JTAG.
Others do it indirectly, making a CPU do it.
@item @b{Program Download} Using the same CPU support GDB uses,
start running that code.
@item @b{Boundary Scan} Most chips support boundary scan, which
helps test for board assembly problems like solder bridges
-and missing connections
+and missing connections.
@end itemize
OpenOCD must know about the active TAPs on your board(s).
@cindex scan chain
TAPs are part of a hardware @dfn{scan chain},
-which is daisy chain of TAPs.
+which is a 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.
OpenOCD can detect some of that information, but not all
of it. @xref{autoprobing,,Autoprobing}.
-Unfortunately those TAPs can't always be autoconfigured,
+Unfortunately, those TAPs can't always be autoconfigured,
because not all devices provide good support for that.
JTAG doesn't require supporting IDCODE instructions, and
chips with JTAG routers may not link TAPs into the chain
Board configuration files combine all the targets on a board,
and so forth.
Note that @emph{the order in which TAPs are declared is very important.}
-It must match the order in the JTAG scan chain, both inside
-a single chip and between them.
+That declaration order must match the order in the JTAG scan chain,
+both inside a single chip and between them.
@xref{faqtaporder,,FAQ TAP Order}.
For example, the ST Microsystems STR912 chip has
jtag newtap str912 bs ... params ...
@end example
-Actual config files use a variable instead of literals like
-@option{str912}, to support more than one chip of each type.
-@xref{Config File Guidelines}.
+Actual config files typically use a variable such as @code{$_CHIPNAME}
+instead of literals like @option{str912}, to support more than one chip
+of each type. @xref{Config File Guidelines}.
@deffn Command {jtag names}
Returns the names of all current TAPs in the scan chain.
name rules: start with an alphabetic character, then numbers
and underscores are OK; while others (including dots!) are not.
-@quotation Tip
-In older code, JTAG TAPs were numbered from 0..N.
-This feature is still present.
-However its use is highly discouraged, and
-should not be relied on; it will be removed by mid-2010.
-Update all of your scripts to use TAP names rather than numbers,
-by paying attention to the runtime warnings they trigger.
-Using TAP numbers in target configuration scripts prevents
-reusing those scripts on boards with multiple targets.
-@end quotation
-
@section TAP Declaration Commands
@c shouldn't this be(come) a {Config Command}?
and should follow this convention:
@itemize @bullet
-@item @code{bs} -- For boundary scan if this is a seperate TAP;
+@item @code{bs} -- For boundary scan if this is a separate TAP;
@item @code{cpu} -- The main CPU of the chip, alternatively
@code{arm} and @code{dsp} on chips with both ARM and DSP CPUs,
-@code{arm1} and @code{arm2} on chips two ARMs, and so forth;
+@code{arm1} and @code{arm2} on chips with two ARMs, and so forth;
@item @code{etb} -- For an embedded trace buffer (example: an ARM ETB11);
@item @code{flash} -- If the chip has a flash TAP, like the str912;
-@item @code{jrc} -- For JTAG route controller (example: the ICEpick modules
+@item @code{jrc} -- For JTAG route controller (example: the ICEPick modules
on many Texas Instruments chips, like the OMAP3530 on Beagleboards);
-@item @code{tap} -- Should be used only FPGA or CPLD like devices
+@item @code{tap} -- Should be used only for FPGA- or CPLD-like devices
with a single TAP;
@item @code{unknownN} -- If you have no idea what the TAP is for (N is a number);
@item @emph{when in doubt} -- Use the chip maker's name in their data sheet.
-For example, the Freescale IMX31 has a SDMA (Smart DMA) with
+For example, the Freescale i.MX31 has a SDMA (Smart DMA) with
a JTAG TAP; that TAP should be named @code{sdma}.
@end itemize
@itemize @bullet
@item @code{-disable} (or @code{-enable})
@*Use the @code{-disable} parameter to flag a TAP which is not
-linked in to the scan chain after a reset using either TRST
+linked into 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{enablinganddisablingtaps,,Enabling and Disabling TAPs}.
-@item @code{-expected-id} @var{number}
+@item @code{-expected-id} @var{NUMBER}
@*A non-zero @var{number} represents a 32-bit IDCODE
which you expect to find when the scan chain is examined.
These codes are not required by all JTAG devices.
JTAG requires the two LSBs of this value to be 01.
By default, @code{-ircapture} and @code{-irmask} are set
up to verify that two-bit value. You may provide
-additional bits, if you know them, or indicate that
+additional bits if you know them, or indicate that
a TAP doesn't conform to the JTAG specification.
@item @code{-irmask} @var{NUMBER}
@*A mask used with @code{-ircapture}
@section Other TAP commands
-@deffn Command {jtag cget} dotted.name @option{-event} name
-@deffnx Command {jtag configure} dotted.name @option{-event} name string
+@deffn Command {jtag cget} dotted.name @option{-event} event_name
+@deffnx Command {jtag configure} dotted.name @option{-event} event_name handler
At this writing this TAP attribute
mechanism is used only for event handling.
(It is not a direct analogue of the @code{cget}/@code{configure}
by issuing the relevant JTAG commands.
@end itemize
-If you need some action after each JTAG reset, which isn't actually
+If you need some action after each JTAG reset which isn't actually
specific to any TAP (since you can't yet trust the scan chain's
contents to be accurate), you might:
In some systems, a @dfn{JTAG Route Controller} (JRC)
is used to enable and/or disable specific JTAG TAPs.
-Many ARM based chips from Texas Instruments include
-an ``ICEpick'' module, which is a JRC.
+Many ARM-based chips from Texas Instruments include
+an ``ICEPick'' module, which is a JRC.
Such chips include DaVinci and OMAP3 processors.
A given TAP may not be visible until the JRC has been
There is often a need to stress-test random access memory (RAM) for
errors. OpenOCD comes with a Tcl implementation of well-known memory
-testing procedures allowing to detect all sorts of issues with
+testing procedures allowing the detection of all sorts of issues with
electrical wiring, defective chips, PCB layout and other common
hardware problems.
-To use them you usually need to initialise your RAM controller first,
+To use them, you usually need to initialise your RAM controller first;
consult your SoC's documentation to get the recommended list of
register operations and translate them to the corresponding
@command{mww}/@command{mwb} commands.
Run all of the above tests over a specified memory region.
@end deffn
+@section Firmware recovery helpers
+@cindex Firmware recovery
+
+OpenOCD includes an easy-to-use script to facilitate mass-market
+devices recovery with JTAG.
+
+For quickstart instructions run:
+@example
+openocd -f tools/firmware-recovery.tcl -c firmware_help
+@end example
+
@node TFTP
@chapter TFTP
@cindex TFTP
-If OpenOCD runs on an embedded host(as ZY1000 does), then TFTP can
+If OpenOCD runs on an embedded host (as ZY1000 does), then TFTP can
be used to access files on PCs (either the developer's PC or some other PC).
The way this works on the ZY1000 is to prefix a filename by
@node GDB and OpenOCD
@chapter GDB and OpenOCD
@cindex GDB
-OpenOCD complies with the remote gdbserver protocol, and as such can be used
+OpenOCD complies with the remote gdbserver protocol and, as such, can be used
to debug remote targets.
Setting up GDB to work with OpenOCD can involve several components:
With the remote protocol, GDB sessions start a little differently
than they do when you're debugging locally.
-Here's an examples showing how to start a debug session with a
+Here's an example showing how to start a debug session with a
small ARM program.
In this case the program was linked to be loaded into SRAM on a Cortex-M3.
Most programs would be written into flash (address 0) and run from there.
that the OpenOCD option @command{gdb_breakpoint_override} is not required when
using a memory map. @xref{gdbbreakpointoverride,,gdb_breakpoint_override}.
-To view the configured memory map in GDB, use the GDB command @option{info mem}
+To view the configured memory map in GDB, use the GDB command @option{info mem}.
All other unassigned addresses within GDB are treated as RAM.
GDB 6.8 and higher set any memory area not in the memory map as inaccessible.
@end itemize
@quotation Note
-Before an RTOS can be detected it must export certain symbols otherwise it cannot be used by
-OpenOCD. Below is a list of the required symbols for each supported RTOS.
+Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
+be used by OpenOCD. Below is a list of the required symbols for each supported RTOS.
@end quotation
@table @code
Code Review / openocd.git / blobdiff