There are several things you should keep in mind when choosing a dongle.
-@enumerate
+@enumerate
@item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
Does your dongle support it? You might need a level converter.
@item @b{Pinout} What pinout does your target board use?
wires, or an "octopus" connector, to convert pinouts.
@item @b{Connection} Does your computer have the USB, printer, or
Ethernet port needed?
-@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
+@item @b{RTCK} Do you require RTCK? Also known as ``adaptive clocking''
@end enumerate
@section Stand alone Systems
@item @b{USBprog}
@* Link: @url{http://www.embedded-projects.net/usbprog} - which uses an Atmel MEGA32 and a UBN9604
-@item @b{USB - Presto}
+@item @b{USB - Presto}
@* Link: @url{http://tools.asix.net/prg_presto.htm}
@item @b{Versaloon-Link}
Other helper scripts might be used to write production system images,
involving considerably more than just a three stage bootloader.
+@section Target Software Changes
+
+Sometimes you may want to make some small changes to the software
+you're developing, to help make JTAG debugging work better.
+For example, in C or assembly language code you might
+use @code{#ifdef JTAG_DEBUG} (or its converse) around code
+handling issues like:
+
+@itemize @bullet
+
+@item @b{ARM Wait-For-Interrupt}...
+Many ARM chips synchronize the JTAG clock using the core clock.
+Low power states which stop that core clock thus prevent JTAG access.
+Idle loops in tasking environments often enter those low power states
+via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7).
+
+You may want to @emph{disable that instruction} in source code,
+or otherwise prevent using that state,
+to ensure you can get JTAG access at any time.
+For example, the OpenOCD @command{halt} command may not
+work for an idle processor otherwise.
+
+@item @b{Delay after reset}...
+Not all chips have good support for debugger access
+right after reset; many LPC2xxx chips have issues here.
+Similarly, applications that reconfigure pins used for
+JTAG access as they start will also block debugger access.
+
+To work with boards like this, @emph{enable a short delay loop}
+the first thing after reset, before "real" startup activities.
+For example, one second's delay is usually more than enough
+time for a JTAG debugger to attach, so that
+early code execution can be debugged
+or firmware can be replaced.
+
+@item @b{Debug Communications Channel (DCC)}...
+Some processors include mechanisms to send messages over JTAG.
+Many ARM cores support these, as do some cores from other vendors.
+(OpenOCD may be able to use this DCC internally, speeding up some
+operations like writing to memory.)
+
+Your application may want to deliver various debugging messages
+over JTAG, by @emph{linking with a small library of code}
+provided with OpenOCD and using the utilities there to send
+various kinds of message.
+@xref{Software Debug Messages and Tracing}.
+
+@end itemize
@node Config File Guidelines
@chapter Config File Guidelines
values for @code{CHIPNAME}, so
it adds a different TAP each time.
-If there are one or more nonzero @option{-expected-id} values,
+If there are 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.
@option{srst_gates_jtag} indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
-while SRST is asserted.
+while SRST is asserted.
The optional @var{trst_type} and @var{srst_type} parameters allow the
driver mode of each reset line to be specified. These values only affect
Every TAP requires at least the following @var{configparams}:
@itemize @bullet
-@item @code{-ircapture} @var{NUMBER}
-@*The bit pattern loaded by the TAP into the JTAG shift register
-on entry to the @sc{ircapture} state, such as 0x01.
-JTAG requires the two LSBs of this value to be 01.
-The value is used to verify that instruction scans work correctly.
@item @code{-irlen} @var{NUMBER}
@*The length in bits of the
instruction register, such as 4 or 5 bits.
-@item @code{-irmask} @var{NUMBER}
-@*A mask for the IR register.
-For some devices, there are bits in the IR that aren't used.
-This lets OpenOCD mask them off when doing IDCODE comparisons.
-In general, this should just be all ones for the size of the IR.
@end itemize
A TAP may also provide optional @var{configparams}:
(the TAP is linked in).
@xref{Enabling and Disabling TAPs}.
@item @code{-expected-id} @var{number}
-@*A non-zero value represents the expected 32-bit IDCODE
-found when the JTAG chain is examined.
+@*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.
@emph{Repeat the option} as many times as required if more than one
ID code could appear (for example, multiple versions).
+Specify @var{number} as zero to suppress warnings about IDCODE
+values that were found but not included in the list.
+@item @code{-ircapture} @var{NUMBER}
+@*The bit pattern loaded by the TAP into the JTAG shift register
+on entry to the @sc{ircapture} state, such as 0x01.
+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; but you may provide
+additional bits, if you know them.
+@item @code{-irmask} @var{NUMBER}
+@*A mask used with @code{-ircapture}
+to verify that instruction scans work correctly.
+Such scans are not used by OpenOCD except to verify that
+there seems to be no problems with JTAG scan chain operations.
@end itemize
@end deffn
+@section Other TAP commands
+
@c @deffn Command {jtag arp_init-reset}
-@c ... more or less "init" ?
+@c ... more or less "toggle TRST ... and SRST too, what the heck"
+
+@deffn Command {jtag cget} dotted.name @option{-event} name
+@deffnx Command {jtag configure} dotted.name @option{-event} name string
+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}
+mechanism for debugger targets.)
+See the next section for information about the available events.
+
+The @code{configure} subcommand assigns an event handler,
+a TCL string which is evaluated when the event is triggered.
+The @code{cget} subcommand returns that handler.
+@end deffn
+
+@anchor{TAP Events}
+@section TAP Events
+@cindex events
+@cindex TAP events
+
+OpenOCD includes two event mechanisms.
+The one presented here applies to all JTAG TAPs.
+The other applies to debugger targets,
+which are associated with certain TAPs.
+
+The TAP events currently defined are:
+
+@itemize @bullet
+@item @b{post-reset}
+@* The TAP has just completed a JTAG reset.
+The tap may still be in the JTAG @sc{reset} state.
+Handlers for these events might perform initialization sequences
+such as issuing TCK cycles, TMS sequences to ensure
+exit from the ARM SWD mode, and more.
+
+Because the scan chain has not yet been verified, handlers for these events
+@emph{should not issue commands which scan the JTAG IR or DR registers}
+of any particular target.
+@b{NOTE:} As this is written (September 2009), nothing prevents such access.
+@item @b{setup}
+@* The scan chain has been reset and verified.
+This handler may enable TAPs as needed.
+@item @b{tap-disable}
+@* The TAP needs to be disabled. This handler should
+implement @command{jtag tapdisable}
+by issuing the relevant JTAG commands.
+@item @b{tap-enable}
+@* The TAP needs to be enabled. This handler should
+implement @command{jtag tapenable}
+by issuing the relevant JTAG commands.
+@end itemize
+
+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:
+
+@example
+jtag configure CHIP.jrc -event post-reset @{
+ echo "JTAG Reset done"
+ ... non-scan jtag operations to be done after reset
+@}
+@end example
+
@anchor{Enabling and Disabling TAPs}
@section Enabling and Disabling TAPs
-@cindex TAP events
@cindex JTAG Route Controller
@cindex jrc
@c (a) currently the event handlers don't seem to be able to
@c fail in a way that could lead to no-change-of-state.
-@c (b) eventually non-event configuration should be possible,
-@c in which case some this documentation must move.
-
-@deffn Command {jtag cget} dotted.name @option{-event} name
-@deffnx Command {jtag configure} dotted.name @option{-event} name string
-At this writing this mechanism is used only for event handling.
-Three events are available. Two events relate to TAP enabling
-and disabling, one to post reset handling.
-
-The @code{configure} subcommand assigns an event handler,
-a TCL string which is evaluated when the event is triggered.
-The @code{cget} subcommand returns that handler.
-The three possible values for an event @var{name} are @option{tap-disable}, @option{tap-enable} and @option{post-reset}.
+In OpenOCD, tap enabling/disabling is invoked by the Tcl commands
+shown below, and is implemented using TAP event handlers.
So for example, when defining a TAP for a CPU connected to
-a JTAG router, you should define TAP event handlers using
+a JTAG router, your @file{target.cfg} file
+should define TAP event handlers using
code that looks something like this:
@example
jtag configure CHIP.cpu -event tap-enable @{
- echo "Enabling CPU TAP"
... jtag operations using CHIP.jrc
@}
jtag configure CHIP.cpu -event tap-disable @{
- echo "Disabling CPU TAP"
... jtag operations using CHIP.jrc
@}
@end example
-If you need some post reset action, you can do:
+Then you might want that CPU's TAP enabled almost all the time:
@example
-jtag configure CHIP.cpu -event post-reset @{
- echo "Reset done"
- ... jtag operations to be done after reset
-@}
+jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
@end example
-@end deffn
+
+Note how that particular setup event handler declaration
+uses quotes to evaluate @code{$CHIP} when the event is configured.
+Using brackets @{ @} would cause it to be evaluated later,
+at runtime, when it might have a different value.
@deffn Command {jtag tapdisable} dotted.name
-@deffnx Command {jtag tapenable} dotted.name
-@deffnx Command {jtag tapisenabled} dotted.name
-These three commands all return the string "1" if the tap
+If necessary, disables the tap
+by sending it a @option{tap-disable} event.
+Returns the string "1" if the tap
specified by @var{dotted.name} is enabled,
-and "0" if it is disbabled.
-The @command{tapenable} variant first enables the tap
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapenable} dotted.name
+If necessary, enables the tap
by sending it a @option{tap-enable} event.
-The @command{tapdisable} variant first disables the tap
-by sending it a @option{tap-disable} event.
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
+@end deffn
+
+@deffn Command {jtag tapisenabled} dotted.name
+Returns the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disabled.
@quotation Note
Humans will find the @command{scan_chain} command more helpful
-than the script-oriented @command{tapisenabled}
for querying the state of the JTAG taps.
@end quotation
@end deffn
@anchor{Target Events}
@section Target Events
+@cindex target events
@cindex events
At various times, certain things can happen, or you want them to happen.
For example:
@anchor{flash erase_sector}
@deffn Command {flash erase_sector} num first last
-Erase sectors in bank @var{num}, starting at sector @var{first} up to and including
-@var{last}. Sector numbering starts at 0.
+Erase sectors in bank @var{num}, starting at sector @var{first}
+up to and including @var{last}.
+Sector numbering starts at 0.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
The @var{num} parameter is a value shown by @command{flash banks}.
This is the only operation that
updates the erase state information displayed by @option{flash info}. That means you have
-to issue an @command{flash erase_check} command after erasing or programming the device
+to issue a @command{flash erase_check} command after erasing or programming the device
to get updated information.
(Code execution may have invalidated any state records kept by OpenOCD.)
@end deffn
@end deffn
@anchor{flash protect}
-@deffn Command {flash protect} num first last (on|off)
-Enable (@var{on}) or disable (@var{off}) protection of flash sectors
-@var{first} to @var{last} of flash bank @var{num}.
+@deffn Command {flash protect} num first last (@option{on}|@option{off})
+Enable (@option{on}) or disable (@option{off}) protection of flash sectors
+in flash bank @var{num}, starting at sector @var{first}
+and continuing up to and including @var{last}.
+Providing a @var{last} sector of @option{last}
+specifies "to the end of the flash bank".
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
The target specific "dangerous" optimisation tweaking options may come and go
as more robust and user friendly ways are found to ensure maximum throughput
-and robustness with a minimum of configuration.
+and robustness with a minimum of configuration.
Typically the "fast enable" is specified first on the command line:
It's unclear how much of a common interface is shared
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
+At this writing (September 2009) only ARM7 and ARM9 support
+for ETM modules is available. The code should be able to
+work with some newer cores; but not all of them support
+this original style of JTAG access.
@end quotation
@subsection ETM Configuration
The @var{clocking} must be @option{half} or @option{full}.
@quotation Note
-You can see the ETM registers using the @command{reg} command, although
-not all of those possible registers are present in every ETM.
+You can see the ETM registers using the @command{reg} command.
+Not all possible registers are present in every ETM.
+Most of the registers are write-only, and are used to configure
+what CPU activities are traced.
@end quotation
@end deffn
@end deffn
@deffn Command {etm status}
-Displays status of the current target's ETM:
+Displays status of the current target's ETM and trace port driver:
is the ETM idle, or is it collecting data?
Did trace data overflow?
Was it triggered?
and any buffered trace data is invalidated.
@itemize
-@item @var{type} ... one of
+@item @var{type} ... describing how data accesses are traced,
+when they pass any ViewData filtering that that was set up.
+The value is one of
@option{none} (save nothing),
@option{data} (save data),
@option{address} (save addresses),
@option{all} (save data and addresses)
@item @var{context_id_bits} ... 0, 8, 16, or 32
@item @var{cycle_accurate} ... @option{enable} or @option{disable}
-@item @var{branch_output} ... @option{enable} or @option{disable}
+cycle-accurate instruction tracing.
+Before ETMv3, enabling this causes much extra data to be recorded.
+@item @var{branch_output} ... @option{enable} or @option{disable}.
+Disable this unless you need to try reconstructing the instruction
+trace stream without an image of the code.
@end itemize
@end deffn
-@deffn Command {etm trigger_percent} percent
-@emph{Buggy and effectively a NOP ... @var{percent} from 2..100}
+@deffn Command {etm trigger_percent} [percent]
+This displays, or optionally changes, the trace port driver's
+behavior after the ETM's configured @emph{trigger} event fires.
+It controls how much more trace data is saved after the (single)
+trace trigger becomes active.
+
+@itemize
+@item The default corresponds to @emph{trace around} usage,
+recording 50 percent data before the event and the rest
+afterwards.
+@item The minimum value of @var{percent} is 2 percent,
+recording almost exclusively data before the trigger.
+Such extreme @emph{trace before} usage can help figure out
+what caused that event to happen.
+@item The maximum value of @var{percent} is 100 percent,
+recording data almost exclusively after the event.
+This extreme @emph{trace after} usage might help sort out
+how the event caused trouble.
+@end itemize
+@c REVISIT allow "break" too -- enter debug mode.
@end deffn
@subsection ETM Trace Operation
That data can be exported to files for later analysis.
It can also be parsed with OpenOCD, for basic sanity checking.
+To configure what is being traced, you will need to write
+various trace registers using @command{reg ETM_*} commands.
+For the definitions of these registers, read ARM publication
+@emph{IHI 0014, ``Embedded Trace Macrocell, Architecture Specification''}.
+Be aware that most of the relevant registers are write-only,
+and that ETM resources are limited. There are only a handful
+of address comparators, data comparators, counters, and so on.
+
+Examples of scenarios you might arrange to trace include:
+
+@itemize
+@item Code flow within a function, @emph{excluding} subroutines
+it calls. Use address range comparators to enable tracing
+for instruction access within that function's body.
+@item Code flow within a function, @emph{including} subroutines
+it calls. Use the sequencer and address comparators to activate
+tracing on an ``entered function'' state, then deactivate it by
+exiting that state when the function's exit code is invoked.
+@item Code flow starting at the fifth invocation of a function,
+combining one of the above models with a counter.
+@item CPU data accesses to the registers for a particular device,
+using address range comparators and the ViewData logic.
+@item Such data accesses only during IRQ handling, combining the above
+model with sequencer triggers which on entry and exit to the IRQ handler.
+@item @emph{... more}
+@end itemize
+
+At this writing, September 2009, there are no Tcl utility
+procedures to help set up any common tracing scenarios.
+
@deffn Command {etm analyze}
Reads trace data into memory, if it wasn't already present.
Decodes and prints the data that was collected.
@deffn Command {armv4_5 reg}
Display a table of all banked core registers, fetching the current value from every
core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current
-register value.
+register value.
@end deffn
@subsection ARM7 and ARM9 specific commands
@deffn Command {arm7_9 dbgrq} (@option{enable}|@option{disable})
Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode,
instead of breakpoints. This should be
-safe for all but ARM7TDMI--S cores (like Philips LPC).
+safe for all but ARM7TDMI--S cores (like Philips LPC).
This feature is enabled by default on most ARM9 cores,
including ARM9TDMI, ARM920T, and ARM926EJ-S.
@end deffn
Enable or disable memory writes and reads that don't check completion of
the operation. This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at very low
-speeds, like the 32kHz startup clock of an AT91RM9200.
+speeds, like the 32kHz startup clock of an AT91RM9200.
@end deffn
@deffn {Debug Command} {arm7_9 write_core_reg} num mode word
@deffn Command {arm11 step_irq_enable} [value]
Displays the value of the flag controlling whether
IRQs are enabled during single stepping;
-they is disabled by default.
+they are disabled by default.
If @var{value} is defined, first assigns that.
@end deffn
+@deffn Command {arm11 vcr} [value]
+@cindex vector_catch
+Displays the value of the @emph{Vector Catch Register (VCR)},
+coprocessor 14 register 7.
+If @var{value} is defined, first assigns that.
+
+Vector Catch hardware provides dedicated breakpoints
+for certain hardware events.
+The specific bit values are core-specific (as in fact is using
+coprocessor 14 register 7 itself) but all current ARM11
+cores @emph{except the ARM1176} use the same six bits.
+@end deffn
+
@section ARMv7 Architecture
@cindex ARMv7
otherwise the libdcc format is used.
@end deffn
-@deffn Command {trace history} (@option{clear}|count)
+@deffn Command {trace history} [@option{clear}|count]
With no parameter, displays all the trace points that have triggered
in the order they triggered.
With the parameter @option{clear}, erases all current trace history records.
history records.
@end deffn
-@deffn Command {trace point} (@option{clear}|identifier)
+@deffn Command {trace point} [@option{clear}|identifier]
With no parameter, displays all trace point identifiers and how many times
they have been triggered.
With the parameter @option{clear}, erases all current trace point counters.
gdb_memory_map disable
@end example
For this to function correctly a valid flash configuration must also be set
-in OpenOCD. For faster performance you should also configure a valid
+in OpenOCD. For faster performance you should also configure a valid
working area.
Informing GDB of the memory map of the target will enable GDB to protect any
information as an argument to each proc.
There are three main types of return values: single value, name value
-pair list and lists.
+pair list and lists.
Name value pair. The proc 'foo' below returns a name/value pair
-list.
+list.
@verbatim
puts "Name: $name, Value: $value"
}
@end verbatim
-
+
Lists returned must be relatively small. Otherwise a range
should be passed in to the proc in question.
variables. JimTCL, as implemented in OpenOCD creates $HostOS which
holds one of the following values:
-@itemize @bullet
+@itemize @bullet
@item @b{winxx} Built using Microsoft Visual Studio
@item @b{linux} Linux is the underlying operating sytem
@item @b{darwin} Darwin (mac-os) is the underlying operating sytem.
that ``deep sleeps'' at 32kHz between every keystroke. It can be
painful.
-@b{Solution #1 - A special circuit}
+@b{Solution #1 - A special circuit}
In order to make use of this, your JTAG dongle must support the RTCK
feature. Not all dongles support this - keep reading!
@item @b{Win32 Pathnames} Why don't backslashes work in Windows paths?
OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
-around Windows filenames.
+around Windows filenames.
@example
> echo \a
@item @b{Data Aborts} When debugging with OpenOCD and GDB (plain GDB, Insight, or Eclipse),
I get lots of "Error: arm7_9_common.c:1771 arm7_9_read_memory():
-memory read caused data abort".
+memory read caused data abort".
The errors are non-fatal, and are the result of GDB trying to trace stack frames
beyond the last valid frame. It might be possible to prevent this by setting up
@b{Also note:} If you have a multi-threaded operating system, they
often do not @b{in the intrest of saving memory} waste these few
-bytes. Painful...
+bytes. Painful...
@item @b{JTAG Reset Config} I get the following message in the OpenOCD console (or log file):
@node Tcl Crash Course
@chapter Tcl Crash Course
-@cindex Tcl
+@cindex Tcl
Not everyone knows Tcl - this is not intended to be a replacement for
learning Tcl, the intent of this chapter is to give you some idea of
Commands are executed like this:
-@enumerate
+@enumerate
@item Parse the next line into (argc) and (argv[]).
@item Look up (argv[0]) in a table and call its function.
@item Repeat until End Of File.
@enumerate
@item The SET command creates 2 variables, X and Y.
@item The double [nested] EXPR command performs math
-@* The EXPR command produces numerical result as a string.
+@* The EXPR command produces numerical result as a string.
@* Refer to Rule #1
@item The format command is executed, producing a single string
@* Refer to Rule #1.
#4 DANGER DANGER DANGER
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
@end example
-@enumerate
+@enumerate
@item The $_TARGETNAME is an OpenOCD variable convention.
@*@b{$_TARGETNAME} represents the last target created, the value changes
each time a new target is created. Remember the parsing rules. When
OpenOCD comes with a target configuration script library. These scripts can be
used as-is or serve as a starting point.
-The target library is published together with the OpenOCD executable and
+The target library is published together with the OpenOCD executable and
the path to the target library is in the OpenOCD script search path.
-Similarly there are example scripts for configuring the JTAG interface.
+Similarly there are example scripts for configuring the JTAG interface.
The command line below uses the example parport configuration script
that ship with OpenOCD, then configures the str710.cfg target and
Code Review / openocd.git / blobdiff