5422 lines
267 KiB
Plaintext
5422 lines
267 KiB
Plaintext
|
This is openocd.info, produced by makeinfo version 6.7 from
|
|||
|
openocd.texi.
|
|||
|
|
|||
|
This User's Guide documents release 0.11.0+dev, dated 10 January 2022,
|
|||
|
of the Open On-Chip Debugger (OpenOCD).
|
|||
|
|
|||
|
* Copyright (C) 2008 The OpenOCD Project
|
|||
|
* Copyright (C) 2007-2008 Spencer Oliver <spen@spen-soft.co.uk>
|
|||
|
* Copyright (C) 2008-2010 Oyvind Harboe <oyvind.harboe@zylin.com>
|
|||
|
* Copyright (C) 2008 Duane Ellis <openocd@duaneellis.com>
|
|||
|
* Copyright (C) 2009-2010 David Brownell
|
|||
|
|
|||
|
Permission is granted to copy, distribute and/or modify this
|
|||
|
document under the terms of the GNU Free Documentation License,
|
|||
|
Version 1.2 or any later version published by the Free Software
|
|||
|
Foundation; with no Invariant Sections, no Front-Cover Texts, and
|
|||
|
no Back-Cover Texts. A copy of the license is included in the
|
|||
|
section entitled "GNU Free Documentation License".
|
|||
|
INFO-DIR-SECTION Development
|
|||
|
START-INFO-DIR-ENTRY
|
|||
|
* OpenOCD: (openocd). OpenOCD User's Guide
|
|||
|
END-INFO-DIR-ENTRY
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Flash Programming, Next: PLD/FPGA Commands, Prev: Flash Commands, Up: Top
|
|||
|
|
|||
|
13 Flash Programming
|
|||
|
********************
|
|||
|
|
|||
|
OpenOCD implements numerous ways to program the target flash, whether
|
|||
|
internal or external. Programming can be achieved by either using *note
|
|||
|
Programming using GDB: programmingusinggdb, or using the commands given
|
|||
|
in *note Flash Programming Commands: flashprogrammingcommands.
|
|||
|
|
|||
|
|
|||
|
To simplify using the flash commands directly a jimtcl script is
|
|||
|
available that handles the programming and verify stage. OpenOCD will
|
|||
|
program/verify/reset the target and optionally shutdown.
|
|||
|
|
|||
|
The script is executed as follows and by default the following actions
|
|||
|
will be performed.
|
|||
|
1. 'init' is executed.
|
|||
|
2. 'reset init' is called to reset and halt the target, any 'reset
|
|||
|
init' scripts are executed.
|
|||
|
3. 'flash write_image' is called to erase and write any flash using
|
|||
|
the filename given.
|
|||
|
4. If the 'preverify' parameter is given, the target is "verified"
|
|||
|
first and only flashed if this fails.
|
|||
|
5. 'verify_image' is called if 'verify' parameter is given.
|
|||
|
6. 'reset run' is called if 'reset' parameter is given.
|
|||
|
7. OpenOCD is shutdown if 'exit' parameter is given.
|
|||
|
|
|||
|
An example of usage is given below. *Note program::.
|
|||
|
|
|||
|
# program and verify using elf/hex/s19. verify and reset
|
|||
|
# are optional parameters
|
|||
|
openocd -f board/stm32f3discovery.cfg \
|
|||
|
-c "program filename.elf verify reset exit"
|
|||
|
|
|||
|
# binary files need the flash address passing
|
|||
|
openocd -f board/stm32f3discovery.cfg \
|
|||
|
-c "program filename.bin exit 0x08000000"
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: PLD/FPGA Commands, Next: General Commands, Prev: Flash Programming, Up: Top
|
|||
|
|
|||
|
14 PLD/FPGA Commands
|
|||
|
********************
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
14.1 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 'pld devices' command,
|
|||
|
and new PLDs are defined by 'pld device driver_name'.
|
|||
|
|
|||
|
-- Config Command: pld device driver_name tap_name [driver_options]
|
|||
|
Defines a new PLD device, supported by driver DRIVER_NAME, using
|
|||
|
the TAP named TAP_NAME. The driver may make use of any
|
|||
|
DRIVER_OPTIONS to configure its behavior.
|
|||
|
|
|||
|
-- Command: pld devices
|
|||
|
Lists the PLDs and their numbers.
|
|||
|
|
|||
|
-- Command: pld load num filename
|
|||
|
Loads the file 'filename' into the PLD identified by NUM. The file
|
|||
|
format must be inferred by the driver.
|
|||
|
|
|||
|
14.2 PLD/FPGA Drivers, Options, and Commands
|
|||
|
============================================
|
|||
|
|
|||
|
Drivers may support PLD-specific options to the 'pld device' definition
|
|||
|
command, and may also define commands usable only with that particular
|
|||
|
type of PLD.
|
|||
|
|
|||
|
-- FPGA Driver: virtex2 [no_jstart]
|
|||
|
Virtex-II is a family of FPGAs sold by Xilinx. It supports the
|
|||
|
IEEE 1532 standard for In-System Configuration (ISC).
|
|||
|
|
|||
|
If NO_JSTART is non-zero, the JSTART instruction is not used after
|
|||
|
loading the bitstream. While required for Series2, Series3, and
|
|||
|
Series6, it breaks bitstream loading on Series7.
|
|||
|
|
|||
|
-- Command: virtex2 read_stat num
|
|||
|
Reads and displays the Virtex-II status register (STAT) for
|
|||
|
FPGA NUM.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: General Commands, Next: Architecture and Core Commands, Prev: PLD/FPGA Commands, Up: Top
|
|||
|
|
|||
|
15 General Commands
|
|||
|
*******************
|
|||
|
|
|||
|
The commands documented in this chapter here are common commands that
|
|||
|
you, as a human, may want to type and see the output of. Configuration
|
|||
|
type commands are documented elsewhere.
|
|||
|
|
|||
|
Intent:
|
|||
|
* Source Of Commands
|
|||
|
OpenOCD commands can occur in a configuration script (discussed
|
|||
|
elsewhere) or typed manually by a human or supplied
|
|||
|
programmatically, or via one of several TCP/IP Ports.
|
|||
|
|
|||
|
* From the human
|
|||
|
A human should interact with the telnet interface (default port:
|
|||
|
4444) or via GDB (default port 3333).
|
|||
|
|
|||
|
To issue commands from within a GDB session, use the 'monitor'
|
|||
|
command, e.g. use 'monitor poll' to issue the 'poll' command. All
|
|||
|
output is relayed through the GDB session.
|
|||
|
|
|||
|
* Machine Interface The Tcl interface's intent is to be a machine
|
|||
|
interface. The default Tcl port is 5555.
|
|||
|
|
|||
|
15.1 Server Commands
|
|||
|
====================
|
|||
|
|
|||
|
-- Command: exit
|
|||
|
Exits the current telnet session.
|
|||
|
|
|||
|
-- Command: help [string]
|
|||
|
With no parameters, prints help text for all commands. Otherwise,
|
|||
|
prints each helptext containing STRING. Not every command provides
|
|||
|
helptext.
|
|||
|
|
|||
|
Configuration commands, and commands valid at any time, are
|
|||
|
explicitly noted in parenthesis. In most cases, no such
|
|||
|
restriction is listed; this indicates commands which are only
|
|||
|
available after the configuration stage has completed.
|
|||
|
|
|||
|
-- Command: usage [string]
|
|||
|
With no parameters, prints usage text for all commands. Otherwise,
|
|||
|
prints all usage text of which command, help text, and usage text
|
|||
|
containing STRING. Not every command provides helptext.
|
|||
|
|
|||
|
-- Command: sleep msec ['busy']
|
|||
|
Wait for at least MSEC milliseconds before resuming. If 'busy' is
|
|||
|
passed, busy-wait instead of sleeping. (This option is strongly
|
|||
|
discouraged.) Useful in connection with script files ('script'
|
|||
|
command and 'target_name' configuration).
|
|||
|
|
|||
|
-- Command: shutdown ['error']
|
|||
|
Close the OpenOCD server, disconnecting all clients (GDB, telnet,
|
|||
|
other). If option 'error' is used, OpenOCD will return a non-zero
|
|||
|
exit code to the parent process.
|
|||
|
|
|||
|
Like any TCL commands, also 'shutdown' can be redefined, e.g.:
|
|||
|
# redefine shutdown
|
|||
|
rename shutdown original_shutdown
|
|||
|
proc shutdown {} {
|
|||
|
puts "This is my implementation of shutdown"
|
|||
|
# my own stuff before exit OpenOCD
|
|||
|
original_shutdown
|
|||
|
}
|
|||
|
If user types CTRL-C or kills OpenOCD, either the command
|
|||
|
'shutdown' or its replacement will be automatically executed before
|
|||
|
OpenOCD exits.
|
|||
|
|
|||
|
-- Command: debug_level [n]
|
|||
|
Display debug level. If N (from 0..4) is provided, then set it to
|
|||
|
that level. This affects the kind of messages sent to the server
|
|||
|
log. Level 0 is error messages only; level 1 adds warnings; level
|
|||
|
2 adds informational messages; level 3 adds debugging messages; and
|
|||
|
level 4 adds verbose low-level debug 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). *Note Running::.
|
|||
|
|
|||
|
-- Command: echo [-n] message
|
|||
|
Logs a message at "user" priority. Option "-n" suppresses trailing
|
|||
|
newline.
|
|||
|
echo "Downloading kernel -- please wait"
|
|||
|
|
|||
|
-- Command: log_output [filename | "default"]
|
|||
|
Redirect logging to FILENAME or set it back to default output; the
|
|||
|
default log output channel is stderr.
|
|||
|
|
|||
|
-- Command: add_script_search_dir [directory]
|
|||
|
Add DIRECTORY to the file/script search path.
|
|||
|
|
|||
|
-- Config Command: bindto [NAME]
|
|||
|
Specify hostname or IPv4 address on which to listen for incoming
|
|||
|
TCP/IP connections. By default, OpenOCD will listen on the
|
|||
|
loopback interface only. If your network environment is safe,
|
|||
|
'bindto 0.0.0.0' can be used to cover all available interfaces.
|
|||
|
|
|||
|
15.2 Target State handling
|
|||
|
==========================
|
|||
|
|
|||
|
In this section "target" refers to a CPU configured as shown earlier
|
|||
|
(*note CPU Configuration::). These commands, like many, implicitly
|
|||
|
refer to a current target which is used to perform the various
|
|||
|
operations. The current target may be changed by using 'targets'
|
|||
|
command with the name of the target which should become current.
|
|||
|
|
|||
|
-- Command: reg [(number|name) [(value|'force')]]
|
|||
|
Access a single register by NUMBER or by its NAME. The target must
|
|||
|
generally be halted before access to CPU core registers is allowed.
|
|||
|
Depending on the hardware, some other registers may be accessible
|
|||
|
while the target is running.
|
|||
|
|
|||
|
_With no arguments_: list all available registers for the current
|
|||
|
target, showing number, name, size, value, and cache status. For
|
|||
|
valid entries, a value is shown; valid entries which are also dirty
|
|||
|
(and will be written back later) are flagged as such.
|
|||
|
|
|||
|
_With number/name_: display that register's value. Use FORCE
|
|||
|
argument to read directly from the target, bypassing any internal
|
|||
|
cache.
|
|||
|
|
|||
|
_With both number/name and value_: set register's value. Writes
|
|||
|
may be held in a writeback cache internal to OpenOCD, so that
|
|||
|
setting the value marks the register as dirty instead of
|
|||
|
immediately flushing that value. Resuming CPU execution (including
|
|||
|
by single stepping) or otherwise activating the relevant module
|
|||
|
will flush such values.
|
|||
|
|
|||
|
Cores may have surprisingly many registers in their Debug and trace
|
|||
|
infrastructure:
|
|||
|
|
|||
|
> reg
|
|||
|
===== ARM registers
|
|||
|
(0) r0 (/32): 0x0000D3C2 (dirty)
|
|||
|
(1) r1 (/32): 0xFD61F31C
|
|||
|
(2) r2 (/32)
|
|||
|
...
|
|||
|
(164) ETM_contextid_comparator_mask (/32)
|
|||
|
>
|
|||
|
|
|||
|
-- Command: halt [ms]
|
|||
|
-- Command: wait_halt [ms]
|
|||
|
The 'halt' command first sends a halt request to the target, which
|
|||
|
'wait_halt' doesn't. Otherwise these behave the same: wait up to
|
|||
|
MS milliseconds, or 5 seconds if there is no parameter, for the
|
|||
|
target to halt (and enter debug mode). Using 0 as the MS parameter
|
|||
|
prevents OpenOCD from waiting.
|
|||
|
|
|||
|
Warning: On ARM cores, software using the _wait for interrupt_
|
|||
|
operation often blocks the JTAG access needed by a 'halt'
|
|||
|
command. This is because that operation also puts the core
|
|||
|
into a low power mode by gating the core clock; but the core
|
|||
|
clock is needed to detect JTAG clock transitions.
|
|||
|
|
|||
|
One partial workaround uses adaptive clocking: when the core
|
|||
|
is interrupted the operation completes, then JTAG clocks are
|
|||
|
accepted at least until the interrupt handler completes.
|
|||
|
However, this workaround is often unusable since the
|
|||
|
processor, board, and JTAG adapter must all support adaptive
|
|||
|
JTAG clocking. Also, it can't work until an interrupt is
|
|||
|
issued.
|
|||
|
|
|||
|
A more complete workaround is to not use that operation while
|
|||
|
you work with a JTAG debugger. Tasking environments generally
|
|||
|
have idle loops where the body is the _wait for interrupt_
|
|||
|
operation. (On older cores, it is a coprocessor action; newer
|
|||
|
cores have a 'wfi' instruction.) Such loops can just remove
|
|||
|
that operation, at the cost of higher power consumption
|
|||
|
(because the CPU is needlessly clocked).
|
|||
|
|
|||
|
-- Command: resume [address]
|
|||
|
Resume the target at its current code position, or the optional
|
|||
|
ADDRESS if it is provided. OpenOCD will wait 5 seconds for the
|
|||
|
target to resume.
|
|||
|
|
|||
|
-- Command: step [address]
|
|||
|
Single-step the target at its current code position, or the
|
|||
|
optional ADDRESS if it is provided.
|
|||
|
|
|||
|
-- Command: reset
|
|||
|
-- Command: reset run
|
|||
|
-- Command: reset halt
|
|||
|
-- Command: reset init
|
|||
|
Perform as hard a reset as possible, using SRST if possible. _All
|
|||
|
defined targets will be reset, and target events will fire during
|
|||
|
the reset sequence._
|
|||
|
|
|||
|
The optional parameter specifies what should happen after the
|
|||
|
reset. If there is no parameter, a 'reset run' is executed. The
|
|||
|
other options will not work on all systems. *Note Reset
|
|||
|
Configuration::.
|
|||
|
|
|||
|
- run Let the target run
|
|||
|
- halt Immediately halt the target
|
|||
|
- init Immediately halt the target, and execute the reset-init
|
|||
|
script
|
|||
|
|
|||
|
-- Command: soft_reset_halt
|
|||
|
Requesting target halt and executing a soft reset. This is often
|
|||
|
used when a target cannot be reset and halted. The target, after
|
|||
|
reset is released begins to execute code. OpenOCD attempts to stop
|
|||
|
the CPU and then sets the program counter back to the reset vector.
|
|||
|
Unfortunately the code that was executed may have left the hardware
|
|||
|
in an unknown state.
|
|||
|
|
|||
|
-- Command: adapter assert [signal [assert|deassert signal]]
|
|||
|
-- Command: adapter deassert [signal [assert|deassert signal]]
|
|||
|
Set values of reset signals. Without parameters returns current
|
|||
|
status of the signals. The SIGNAL parameter values may be 'srst',
|
|||
|
indicating that srst signal is to be asserted or deasserted,
|
|||
|
'trst', indicating that trst signal is to be asserted or
|
|||
|
deasserted.
|
|||
|
|
|||
|
The 'reset_config' command should already have been used to
|
|||
|
configure how the board and the adapter treat these two signals,
|
|||
|
and to say if either signal is even present. *Note Reset
|
|||
|
Configuration::. Trying to assert a signal that is not present
|
|||
|
triggers an error. If a signal is present on the adapter and not
|
|||
|
specified in the command, the signal will not be modified.
|
|||
|
|
|||
|
Note: TRST is specially handled. It actually signifies JTAG's
|
|||
|
RESET state. So if the board doesn't support the optional
|
|||
|
TRST signal, or it doesn't support it along with the specified
|
|||
|
SRST value, JTAG reset is triggered with TMS and TCK signals
|
|||
|
instead of the TRST signal. And no matter how that JTAG reset
|
|||
|
is triggered, once the scan chain enters RESET with TRST
|
|||
|
inactive, TAP 'post-reset' events are delivered to all TAPs
|
|||
|
with handlers for that event.
|
|||
|
|
|||
|
15.3 Memory access commands
|
|||
|
===========================
|
|||
|
|
|||
|
These commands allow accesses of a specific size to the memory system.
|
|||
|
Often these are used to configure the current target in some special
|
|||
|
way. For example - one may need to write certain values to the SDRAM
|
|||
|
controller to enable SDRAM.
|
|||
|
|
|||
|
1. Use the 'targets' (plural) command to change the current target.
|
|||
|
2. In system level scripts these commands are deprecated. Please use
|
|||
|
their TARGET object siblings to avoid making assumptions about what
|
|||
|
TAP is the current target, or about MMU configuration.
|
|||
|
|
|||
|
-- Command: mdd [phys] addr [count]
|
|||
|
-- Command: mdw [phys] addr [count]
|
|||
|
-- Command: mdh [phys] addr [count]
|
|||
|
-- Command: mdb [phys] addr [count]
|
|||
|
Display contents of address ADDR, as 64-bit doublewords ('mdd'),
|
|||
|
32-bit words ('mdw'), 16-bit halfwords ('mdh'), or 8-bit bytes
|
|||
|
('mdb'). When the current target has an MMU which is present and
|
|||
|
active, ADDR is interpreted as a virtual address. Otherwise, or if
|
|||
|
the optional PHYS flag is specified, ADDR is interpreted as a
|
|||
|
physical address. If COUNT is specified, displays that many units.
|
|||
|
(If you want to manipulate the data instead of displaying it, see
|
|||
|
the 'mem2array' primitives.)
|
|||
|
|
|||
|
-- Command: mwd [phys] addr doubleword [count]
|
|||
|
-- Command: mww [phys] addr word [count]
|
|||
|
-- Command: mwh [phys] addr halfword [count]
|
|||
|
-- Command: mwb [phys] addr byte [count]
|
|||
|
Writes the specified DOUBLEWORD (64 bits), WORD (32 bits), HALFWORD
|
|||
|
(16 bits), or BYTE (8-bit) value, at the specified address ADDR.
|
|||
|
When the current target has an MMU which is present and active,
|
|||
|
ADDR is interpreted as a virtual address. Otherwise, or if the
|
|||
|
optional PHYS flag is specified, ADDR is interpreted as a physical
|
|||
|
address. If COUNT is specified, fills that many units of
|
|||
|
consecutive address.
|
|||
|
|
|||
|
15.4 Image loading commands
|
|||
|
===========================
|
|||
|
|
|||
|
-- Command: dump_image filename address size
|
|||
|
Dump SIZE bytes of target memory starting at ADDRESS to the binary
|
|||
|
file named FILENAME.
|
|||
|
|
|||
|
-- Command: fast_load
|
|||
|
Loads an image stored in memory by 'fast_load_image' to the current
|
|||
|
target. Must be preceded by fast_load_image.
|
|||
|
|
|||
|
-- Command: fast_load_image filename address ['bin'|'ihex'|'elf'|'s19']
|
|||
|
Normally you should be using 'load_image' or GDB load. However,
|
|||
|
for testing purposes or when I/O overhead is significant(OpenOCD
|
|||
|
running on an embedded host), storing the image in memory and
|
|||
|
uploading the image to the target can be a way to upload e.g.
|
|||
|
multiple debug sessions when the binary does not change. Arguments
|
|||
|
are the same as 'load_image', but the image is stored in OpenOCD
|
|||
|
host memory, i.e. does not affect target. This approach is also
|
|||
|
useful when profiling target programming performance as I/O and
|
|||
|
target programming can easily be profiled separately.
|
|||
|
|
|||
|
-- Command: load_image filename address [['bin'|'ihex'|'elf'|'s19']
|
|||
|
'min_addr' 'max_length']
|
|||
|
Load image from file FILENAME to target memory offset by ADDRESS
|
|||
|
from its load address. The file format may optionally be specified
|
|||
|
('bin', 'ihex', 'elf', or 's19'). In addition the following
|
|||
|
arguments may be specified: MIN_ADDR - ignore data below MIN_ADDR
|
|||
|
(this is w.r.t. to the target's load address + ADDRESS) MAX_LENGTH
|
|||
|
- maximum number of bytes to load.
|
|||
|
proc load_image_bin {fname foffset address length } {
|
|||
|
# Load data from fname filename at foffset offset to
|
|||
|
# target at address. Load at most length bytes.
|
|||
|
load_image $fname [expr $address - $foffset] bin \
|
|||
|
$address $length
|
|||
|
}
|
|||
|
|
|||
|
-- Command: test_image filename [address ['bin'|'ihex'|'elf']]
|
|||
|
Displays image section sizes and addresses as if FILENAME were
|
|||
|
loaded into target memory starting at ADDRESS (defaults to zero).
|
|||
|
The file format may optionally be specified ('bin', 'ihex', or
|
|||
|
'elf')
|
|||
|
|
|||
|
-- Command: verify_image filename address ['bin'|'ihex'|'elf']
|
|||
|
Verify FILENAME against target memory starting at ADDRESS. The
|
|||
|
file format may optionally be specified ('bin', 'ihex', or 'elf')
|
|||
|
This will first attempt a comparison using a CRC checksum, if this
|
|||
|
fails it will try a binary compare.
|
|||
|
|
|||
|
-- Command: verify_image_checksum filename address ['bin'|'ihex'|'elf']
|
|||
|
Verify FILENAME against target memory starting at ADDRESS. The
|
|||
|
file format may optionally be specified ('bin', 'ihex', or 'elf')
|
|||
|
This perform a comparison using a CRC checksum only
|
|||
|
|
|||
|
15.5 Breakpoint and Watchpoint commands
|
|||
|
=======================================
|
|||
|
|
|||
|
CPUs often make debug modules accessible through JTAG, with hardware
|
|||
|
support for a handful of code breakpoints and data watchpoints. In
|
|||
|
addition, CPUs almost always support software breakpoints.
|
|||
|
|
|||
|
-- Command: bp [address len ['hw']]
|
|||
|
With no parameters, lists all active breakpoints. Else sets a
|
|||
|
breakpoint on code execution starting at ADDRESS for LENGTH bytes.
|
|||
|
This is a software breakpoint, unless 'hw' is specified in which
|
|||
|
case it will be a hardware breakpoint.
|
|||
|
|
|||
|
(*Note arm9 vector_catch: arm9vectorcatch, or *note xscale
|
|||
|
vector_catch: xscalevectorcatch, for similar mechanisms that do not
|
|||
|
consume hardware breakpoints.)
|
|||
|
|
|||
|
-- Command: rbp 'all' | address
|
|||
|
Remove the breakpoint at ADDRESS or all breakpoints.
|
|||
|
|
|||
|
-- Command: rwp address
|
|||
|
Remove data watchpoint on ADDRESS
|
|||
|
|
|||
|
-- Command: wp [address len [('r'|'w'|'a') [value [mask]]]]
|
|||
|
With no parameters, lists all active watchpoints. Else sets a data
|
|||
|
watchpoint on data from ADDRESS for LENGTH bytes. The watch point
|
|||
|
is an "access" watchpoint unless the 'r' or 'w' parameter is
|
|||
|
provided, defining it as respectively a read or write watchpoint.
|
|||
|
If a VALUE is provided, that value is used when determining if the
|
|||
|
watchpoint should trigger. The value may be first be masked using
|
|||
|
MASK to mark "don't care" fields.
|
|||
|
|
|||
|
15.6 Real Time Transfer (RTT)
|
|||
|
=============================
|
|||
|
|
|||
|
Real Time Transfer (RTT) is an interface specified by SEGGER based on
|
|||
|
basic memory reads and writes to transfer data bidirectionally between
|
|||
|
target and host. The specification is independent of the target
|
|||
|
architecture. Every target that supports so called "background memory
|
|||
|
access", which means that the target memory can be accessed by the
|
|||
|
debugger while the target is running, can be used. This interface is
|
|||
|
especially of interest for targets without Serial Wire Output (SWO),
|
|||
|
such as ARM Cortex-M0, or where semihosting is not applicable because of
|
|||
|
real-time constraints.
|
|||
|
|
|||
|
Note: The current implementation supports only single target
|
|||
|
devices.
|
|||
|
|
|||
|
The data transfer between host and target device is organized through
|
|||
|
unidirectional up/down-channels for target-to-host and host-to-target
|
|||
|
communication, respectively.
|
|||
|
|
|||
|
Note: The current implementation does not respect channel buffer
|
|||
|
flags. They are used to determine what happens when writing to a
|
|||
|
full buffer, for example.
|
|||
|
|
|||
|
Channels are exposed via raw TCP/IP connections. One or more RTT
|
|||
|
servers can be assigned to each channel to make them accessible to an
|
|||
|
unlimited number of TCP/IP connections.
|
|||
|
|
|||
|
-- Command: rtt setup address size ID
|
|||
|
Configure RTT for the currently selected target. Once RTT is
|
|||
|
started, OpenOCD searches for a control block with the identifier
|
|||
|
ID starting at the memory address ADDRESS within the next SIZE
|
|||
|
bytes.
|
|||
|
|
|||
|
-- Command: rtt start
|
|||
|
Start RTT. If the control block location is not known, OpenOCD
|
|||
|
starts searching for it.
|
|||
|
|
|||
|
-- Command: rtt stop
|
|||
|
Stop RTT.
|
|||
|
|
|||
|
-- Command: rtt polling_interval [interval]
|
|||
|
Display the polling interval. If INTERVAL is provided, set the
|
|||
|
polling interval. The polling interval determines (in
|
|||
|
milliseconds) how often the up-channels are checked for new data.
|
|||
|
|
|||
|
-- Command: rtt channels
|
|||
|
Display a list of all channels and their properties.
|
|||
|
|
|||
|
-- Command: rtt channellist
|
|||
|
Return a list of all channels and their properties as Tcl list.
|
|||
|
The list can be manipulated easily from within scripts.
|
|||
|
|
|||
|
-- Command: rtt server start port channel
|
|||
|
Start a TCP server on PORT for the channel CHANNEL.
|
|||
|
|
|||
|
-- Command: rtt server stop port
|
|||
|
Stop the TCP sever with port PORT.
|
|||
|
|
|||
|
The following example shows how to setup RTT using the SEGGER RTT
|
|||
|
implementation on the target device.
|
|||
|
|
|||
|
resume
|
|||
|
|
|||
|
rtt setup 0x20000000 2048 "SEGGER RTT"
|
|||
|
rtt start
|
|||
|
|
|||
|
rtt server start 9090 0
|
|||
|
|
|||
|
In this example, OpenOCD searches the control block with the ID "SEGGER
|
|||
|
RTT" starting at 0x20000000 for 2048 bytes. The RTT channel 0 is
|
|||
|
exposed through the TCP/IP port 9090.
|
|||
|
|
|||
|
15.7 Misc Commands
|
|||
|
==================
|
|||
|
|
|||
|
-- Command: profile seconds filename [start end]
|
|||
|
Profiling samples the CPU's program counter as quickly as possible,
|
|||
|
which is useful for non-intrusive stochastic profiling. Saves up
|
|||
|
to 10000 samples in 'filename' using "gmon.out" format. Optional
|
|||
|
'start' and 'end' parameters allow to limit the address range.
|
|||
|
|
|||
|
-- Command: version
|
|||
|
Displays a string identifying the version of this OpenOCD server.
|
|||
|
|
|||
|
-- Command: virt2phys virtual_address
|
|||
|
Requests the current target to map the specified VIRTUAL_ADDRESS to
|
|||
|
its corresponding physical address, and displays the result.
|
|||
|
|
|||
|
-- Command: add_help_text 'command_name' 'help-string'
|
|||
|
Add or replace help text on the given COMMAND_NAME.
|
|||
|
|
|||
|
-- Command: add_usage_text 'command_name' 'help-string'
|
|||
|
Add or replace usage text on the given COMMAND_NAME.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Architecture and Core Commands, Next: JTAG Commands, Prev: General Commands, Up: Top
|
|||
|
|
|||
|
16 Architecture and Core Commands
|
|||
|
*********************************
|
|||
|
|
|||
|
Most CPUs have specialized JTAG operations to support debugging.
|
|||
|
OpenOCD packages most such operations in its standard command framework.
|
|||
|
Some of those operations don't fit well in that framework, so they are
|
|||
|
exposed here as architecture or implementation (core) specific commands.
|
|||
|
|
|||
|
16.1 ARM Hardware Tracing
|
|||
|
=========================
|
|||
|
|
|||
|
CPUs based on ARM cores may include standard tracing interfaces, based
|
|||
|
on an "Embedded Trace Module" (ETM) which sends voluminous address and
|
|||
|
data bus trace records to a "Trace Port".
|
|||
|
|
|||
|
* Development-oriented boards will sometimes provide a high speed
|
|||
|
trace connector for collecting that data, when the particular CPU
|
|||
|
supports such an interface. (The standard connector is a 38-pin
|
|||
|
Mictor, with both JTAG and trace port support.) Those trace
|
|||
|
connectors are supported by higher end JTAG adapters and some logic
|
|||
|
analyzer modules; frequently those modules can buffer several
|
|||
|
megabytes of trace data. Configuring an ETM coupled to such an
|
|||
|
external trace port belongs in the board-specific configuration
|
|||
|
file.
|
|||
|
* If the CPU doesn't provide an external interface, it probably has
|
|||
|
an "Embedded Trace Buffer" (ETB) on the chip, which is a dedicated
|
|||
|
SRAM. 4KBytes is one common ETB size. Configuring an ETM coupled
|
|||
|
only to an ETB belongs in the CPU-specific (target) configuration
|
|||
|
file, since it works the same on all boards.
|
|||
|
|
|||
|
ETM support in OpenOCD doesn't seem to be widely used yet.
|
|||
|
|
|||
|
Issues: ETM support may be buggy, and at least some 'etm config'
|
|||
|
parameters should be detected by asking the ETM for them.
|
|||
|
|
|||
|
ETM trigger events could also implement a kind of complex hardware
|
|||
|
breakpoint, much more powerful than the simple watchpoint hardware
|
|||
|
exported by EmbeddedICE modules. _Such breakpoints can be
|
|||
|
triggered even when using the dummy trace port driver_.
|
|||
|
|
|||
|
It seems like a GDB hookup should be possible, as well as tracing
|
|||
|
only during specific states (perhaps _handling IRQ 23_ or _calls
|
|||
|
foo()_).
|
|||
|
|
|||
|
There should be GUI tools to manipulate saved trace data and help
|
|||
|
analyse it in conjunction with the source code. 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 (November 2009) only ARM7, ARM9, and ARM11 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.
|
|||
|
|
|||
|
16.1.1 ETM Configuration
|
|||
|
------------------------
|
|||
|
|
|||
|
ETM setup is coupled with the trace port driver configuration.
|
|||
|
|
|||
|
-- Config Command: etm config target width mode clocking driver
|
|||
|
Declares the ETM associated with TARGET, and associates it with a
|
|||
|
given trace port DRIVER. *Note Trace Port Drivers:
|
|||
|
traceportdrivers.
|
|||
|
|
|||
|
Several of the parameters must reflect the trace port capabilities,
|
|||
|
which are a function of silicon capabilities (exposed later using
|
|||
|
'etm info') and of what hardware is connected to that port (such as
|
|||
|
an external pod, or ETB). The WIDTH must be either 4, 8, or 16,
|
|||
|
except with ETMv3.0 and newer modules which may also support 1, 2,
|
|||
|
24, 32, 48, and 64 bit widths. (With those versions, 'etm info'
|
|||
|
also shows whether the selected port width and mode are supported.)
|
|||
|
|
|||
|
The MODE must be 'normal', 'multiplexed', or 'demultiplexed'. The
|
|||
|
CLOCKING must be 'half' or 'full'.
|
|||
|
|
|||
|
Warning: With ETMv3.0 and newer, the bits set with the MODE
|
|||
|
and CLOCKING parameters both control the mode. This modified
|
|||
|
mode does not map to the values supported by previous ETM
|
|||
|
modules, so this syntax is subject to change.
|
|||
|
|
|||
|
Note: You can see the ETM registers using the '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.
|
|||
|
|
|||
|
-- Command: etm info
|
|||
|
Displays information about the current target's ETM. This includes
|
|||
|
resource counts from the 'ETM_CONFIG' register, as well as silicon
|
|||
|
capabilities (except on rather old modules). from the
|
|||
|
'ETM_SYS_CONFIG' register.
|
|||
|
|
|||
|
-- Command: etm status
|
|||
|
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?
|
|||
|
|
|||
|
-- Command: etm tracemode [type context_id_bits cycle_accurate
|
|||
|
branch_output]
|
|||
|
Displays what data that ETM will collect. If arguments are
|
|||
|
provided, first configures that data. When the configuration
|
|||
|
changes, tracing is stopped and any buffered trace data is
|
|||
|
invalidated.
|
|||
|
|
|||
|
* TYPE ... describing how data accesses are traced, when they
|
|||
|
pass any ViewData filtering that was set up. The value is one
|
|||
|
of 'none' (save nothing), 'data' (save data), 'address' (save
|
|||
|
addresses), 'all' (save data and addresses)
|
|||
|
* CONTEXT_ID_BITS ... 0, 8, 16, or 32
|
|||
|
* CYCLE_ACCURATE ... 'enable' or 'disable' cycle-accurate
|
|||
|
instruction tracing. Before ETMv3, enabling this causes much
|
|||
|
extra data to be recorded.
|
|||
|
* BRANCH_OUTPUT ... 'enable' or 'disable'. Disable this unless
|
|||
|
you need to try reconstructing the instruction trace stream
|
|||
|
without an image of the code.
|
|||
|
|
|||
|
-- Command: etm trigger_debug ('enable'|'disable')
|
|||
|
Displays whether ETM triggering debug entry (like a breakpoint) is
|
|||
|
enabled or disabled, after optionally modifying that configuration.
|
|||
|
The default behaviour is 'disable'. Any change takes effect after
|
|||
|
the next 'etm start'.
|
|||
|
|
|||
|
By using script commands to configure ETM registers, you can make
|
|||
|
the processor enter debug state automatically when certain
|
|||
|
conditions, more complex than supported by the breakpoint hardware,
|
|||
|
happen.
|
|||
|
|
|||
|
16.1.2 ETM Trace Operation
|
|||
|
--------------------------
|
|||
|
|
|||
|
After setting up the ETM, you can use it to collect data. 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 'reg ETM_*' commands. For the definitions of these
|
|||
|
registers, read ARM publication _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:
|
|||
|
|
|||
|
* Code flow within a function, _excluding_ subroutines it calls. Use
|
|||
|
address range comparators to enable tracing for instruction access
|
|||
|
within that function's body.
|
|||
|
* Code flow within a function, _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.
|
|||
|
* Code flow starting at the fifth invocation of a function, combining
|
|||
|
one of the above models with a counter.
|
|||
|
* CPU data accesses to the registers for a particular device, using
|
|||
|
address range comparators and the ViewData logic.
|
|||
|
* Such data accesses only during IRQ handling, combining the above
|
|||
|
model with sequencer triggers which on entry and exit to the IRQ
|
|||
|
handler.
|
|||
|
* _... more_
|
|||
|
|
|||
|
At this writing, September 2009, there are no Tcl utility procedures to
|
|||
|
help set up any common tracing scenarios.
|
|||
|
|
|||
|
-- Command: etm analyze
|
|||
|
Reads trace data into memory, if it wasn't already present.
|
|||
|
Decodes and prints the data that was collected.
|
|||
|
|
|||
|
-- Command: etm dump filename
|
|||
|
Stores the captured trace data in 'filename'.
|
|||
|
|
|||
|
-- Command: etm image filename [base_address] [type]
|
|||
|
Opens an image file.
|
|||
|
|
|||
|
-- Command: etm load filename
|
|||
|
Loads captured trace data from 'filename'.
|
|||
|
|
|||
|
-- Command: etm start
|
|||
|
Starts trace data collection.
|
|||
|
|
|||
|
-- Command: etm stop
|
|||
|
Stops trace data collection.
|
|||
|
|
|||
|
16.1.3 Trace Port Drivers
|
|||
|
-------------------------
|
|||
|
|
|||
|
To use an ETM trace port it must be associated with a driver.
|
|||
|
|
|||
|
-- Trace Port Driver: dummy
|
|||
|
Use the 'dummy' driver if you are configuring an ETM that's not
|
|||
|
connected to anything (on-chip ETB or off-chip trace connector).
|
|||
|
_This driver lets OpenOCD talk to the ETM, but it does not expose
|
|||
|
any trace data collection._
|
|||
|
-- Config Command: etm_dummy config target
|
|||
|
Associates the ETM for TARGET with a dummy driver.
|
|||
|
|
|||
|
-- Trace Port Driver: etb
|
|||
|
Use the 'etb' driver if you are configuring an ETM to use on-chip
|
|||
|
ETB memory.
|
|||
|
-- Config Command: etb config target etb_tap
|
|||
|
Associates the ETM for TARGET with the ETB at ETB_TAP. You
|
|||
|
can see the ETB registers using the 'reg' command.
|
|||
|
-- Command: etb trigger_percent [percent]
|
|||
|
This displays, or optionally changes, ETB behavior after the
|
|||
|
ETM's configured _trigger_ event fires. It controls how much
|
|||
|
more trace data is saved after the (single) trace trigger
|
|||
|
becomes active.
|
|||
|
|
|||
|
* The default corresponds to _trace around_ usage,
|
|||
|
recording 50 percent data before the event and the rest
|
|||
|
afterwards.
|
|||
|
* The minimum value of PERCENT is 2 percent, recording
|
|||
|
almost exclusively data before the trigger. Such extreme
|
|||
|
_trace before_ usage can help figure out what caused that
|
|||
|
event to happen.
|
|||
|
* The maximum value of PERCENT is 100 percent, recording
|
|||
|
data almost exclusively after the event. This extreme
|
|||
|
_trace after_ usage might help sort out how the event
|
|||
|
caused trouble.
|
|||
|
|
|||
|
16.2 ARM Cross-Trigger Interface
|
|||
|
================================
|
|||
|
|
|||
|
The ARM Cross-Trigger Interface (CTI) is a generic CoreSight component
|
|||
|
that connects event sources like tracing components or CPU cores with
|
|||
|
each other through a common trigger matrix (CTM). For ARMv8
|
|||
|
architecture, a CTI is mandatory for core run control and each core has
|
|||
|
an individual CTI instance attached to it. OpenOCD has limited support
|
|||
|
for CTI using the _cti_ group of commands.
|
|||
|
|
|||
|
-- Command: cti create cti_name '-dap' dap_name '-ap-num' apn
|
|||
|
'-baseaddr' base_address
|
|||
|
Creates a CTI instance CTI_NAME on the DAP instance DAP_NAME on
|
|||
|
MEM-AP APN. The BASE_ADDRESS must match the base address of the
|
|||
|
CTI on the respective MEM-AP. All arguments are mandatory. This
|
|||
|
creates a new command '$cti_name' which is used for various
|
|||
|
purposes including additional configuration.
|
|||
|
|
|||
|
-- Command: $cti_name enable 'on|off'
|
|||
|
Enable ('on') or disable ('off') the CTI.
|
|||
|
|
|||
|
-- Command: $cti_name dump
|
|||
|
Displays a register dump of the CTI.
|
|||
|
|
|||
|
-- Command: $cti_name write REG_NAME VALUE
|
|||
|
Write VALUE to the CTI register with the symbolic name REG_NAME.
|
|||
|
|
|||
|
-- Command: $cti_name read REG_NAME
|
|||
|
Print the value read from the CTI register with the symbolic name
|
|||
|
REG_NAME.
|
|||
|
|
|||
|
-- Command: $cti_name ack EVENT
|
|||
|
Acknowledge a CTI EVENT.
|
|||
|
|
|||
|
-- Command: $cti_name channel CHANNEL_NUMBER OPERATION
|
|||
|
Perform a specific channel operation, the possible operations are:
|
|||
|
gate, ungate, set, clear and pulse
|
|||
|
|
|||
|
-- Command: $cti_name testmode 'on|off'
|
|||
|
Enable ('on') or disable ('off') the integration test mode of the
|
|||
|
CTI.
|
|||
|
|
|||
|
-- Command: cti names
|
|||
|
Prints a list of names of all CTI objects created. This command is
|
|||
|
mainly useful in TCL scripting.
|
|||
|
|
|||
|
16.3 Generic ARM
|
|||
|
================
|
|||
|
|
|||
|
These commands should be available on all ARM processors. They are
|
|||
|
available in addition to other core-specific commands that may be
|
|||
|
available.
|
|||
|
|
|||
|
-- Command: arm core_state ['arm'|'thumb']
|
|||
|
Displays the core_state, optionally changing it to process either
|
|||
|
'arm' or 'thumb' instructions. The target may later be resumed in
|
|||
|
the currently set core_state. (Processors may also support the
|
|||
|
Jazelle state, but that is not currently supported in OpenOCD.)
|
|||
|
|
|||
|
-- Command: arm disassemble address [count ['thumb']]
|
|||
|
Disassembles COUNT instructions starting at ADDRESS. If COUNT is
|
|||
|
not specified, a single instruction is disassembled. If 'thumb' is
|
|||
|
specified, or the low bit of the address is set, Thumb2 (mixed
|
|||
|
16/32-bit) instructions are used; else ARM (32-bit) instructions
|
|||
|
are used. (Processors may also support the Jazelle state, but
|
|||
|
those instructions are not currently understood by OpenOCD.)
|
|||
|
|
|||
|
Note that all Thumb instructions are Thumb2 instructions, so older
|
|||
|
processors (without Thumb2 support) will still see correct
|
|||
|
disassembly of Thumb code. Also, ThumbEE opcodes are the same as
|
|||
|
Thumb2, with a handful of exceptions. ThumbEE disassembly
|
|||
|
currently has no explicit support.
|
|||
|
|
|||
|
-- Command: arm mcr pX op1 CRn CRm op2 value
|
|||
|
Write VALUE to a coprocessor PX register passing parameters CRN,
|
|||
|
CRM, opcodes OPC1 and OPC2, and using the MCR instruction.
|
|||
|
(Parameter sequence matches the ARM instruction, but omits an ARM
|
|||
|
register.)
|
|||
|
|
|||
|
-- Command: arm mrc pX coproc op1 CRn CRm op2
|
|||
|
Read a coprocessor PX register passing parameters CRN, CRM, opcodes
|
|||
|
OPC1 and OPC2, and the MRC instruction. Returns the result so it
|
|||
|
can be manipulated by Jim scripts. (Parameter sequence matches the
|
|||
|
ARM instruction, but omits an ARM register.)
|
|||
|
|
|||
|
-- Command: arm reg
|
|||
|
Display a table of all banked core registers, fetching the current
|
|||
|
value from every core mode if necessary.
|
|||
|
|
|||
|
-- Command: arm semihosting ['enable'|'disable']
|
|||
|
Display status of semihosting, after optionally changing that
|
|||
|
status.
|
|||
|
|
|||
|
Semihosting allows for code executing on an ARM target to use the
|
|||
|
I/O facilities on the host computer i.e. the system where OpenOCD
|
|||
|
is running. The target application must be linked against a
|
|||
|
library implementing the ARM semihosting convention that forwards
|
|||
|
operation requests by using a special SVC instruction that is
|
|||
|
trapped at the Supervisor Call vector by OpenOCD.
|
|||
|
|
|||
|
-- Command: arm semihosting_cmdline ['enable'|'disable']
|
|||
|
Set the command line to be passed to the debugger.
|
|||
|
|
|||
|
arm semihosting_cmdline argv0 argv1 argv2 ...
|
|||
|
|
|||
|
This option lets one set the command line arguments to be passed to
|
|||
|
the program. The first argument (argv0) is the program name in a
|
|||
|
standard C environment (argv[0]). Depending on the program (not
|
|||
|
much programs look at argv[0]), argv0 is ignored and can be any
|
|||
|
string.
|
|||
|
|
|||
|
-- Command: arm semihosting_fileio ['enable'|'disable']
|
|||
|
Display status of semihosting fileio, after optionally changing
|
|||
|
that status.
|
|||
|
|
|||
|
Enabling this option forwards semihosting I/O to GDB process using
|
|||
|
the File-I/O remote protocol extension. This is especially useful
|
|||
|
for interacting with remote files or displaying console messages in
|
|||
|
the debugger.
|
|||
|
|
|||
|
-- Command: arm semihosting_resexit ['enable'|'disable']
|
|||
|
Enable resumable SEMIHOSTING_SYS_EXIT.
|
|||
|
|
|||
|
When SEMIHOSTING_SYS_EXIT is called outside a debug session, things
|
|||
|
are simple, the openocd process calls exit() and passes the value
|
|||
|
returned by the target.
|
|||
|
|
|||
|
When SEMIHOSTING_SYS_EXIT is called during a debug session, by
|
|||
|
default execution returns to the debugger, leaving the debugger in
|
|||
|
a HALT state, similar to the state entered when encountering a
|
|||
|
break.
|
|||
|
|
|||
|
In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT return
|
|||
|
normally, as any semihosting call, and do not break to the
|
|||
|
debugger. The standard allows this to happen, but the condition to
|
|||
|
trigger it is a bit obscure ("by performing an RDI_Execute request
|
|||
|
or equivalent").
|
|||
|
|
|||
|
To make the SEMIHOSTING_SYS_EXIT call return normally, enable this
|
|||
|
option (default: disabled).
|
|||
|
|
|||
|
16.4 ARMv4 and ARMv5 Architecture
|
|||
|
=================================
|
|||
|
|
|||
|
The ARMv4 and ARMv5 architectures are widely used in embedded systems,
|
|||
|
and introduced core parts of the instruction set in use today. That
|
|||
|
includes the Thumb instruction set, introduced in the ARMv4T variant.
|
|||
|
|
|||
|
16.4.1 ARM7 and ARM9 specific commands
|
|||
|
--------------------------------------
|
|||
|
|
|||
|
These commands are specific to ARM7 and ARM9 cores, like ARM7TDMI,
|
|||
|
ARM720T, ARM9TDMI, ARM920T or ARM926EJ-S. They are available in addition
|
|||
|
to the ARM commands, and any other core-specific commands that may be
|
|||
|
available.
|
|||
|
|
|||
|
-- Command: arm7_9 dbgrq ['enable'|'disable']
|
|||
|
Displays the value of the flag controlling use of the EmbeddedIce
|
|||
|
DBGRQ signal to force entry into debug mode, instead of
|
|||
|
breakpoints. If a boolean parameter is provided, first assigns
|
|||
|
that flag.
|
|||
|
|
|||
|
This should be safe for all but ARM7TDMI-S cores (like NXP LPC).
|
|||
|
This feature is enabled by default on most ARM9 cores, including
|
|||
|
ARM9TDMI, ARM920T, and ARM926EJ-S.
|
|||
|
|
|||
|
-- Command: arm7_9 dcc_downloads ['enable'|'disable']
|
|||
|
Displays the value of the flag controlling use of the debug
|
|||
|
communications channel (DCC) to write larger (>128 byte) amounts of
|
|||
|
memory. If a boolean parameter is provided, first assigns that
|
|||
|
flag.
|
|||
|
|
|||
|
DCC downloads offer a huge speed increase, but might be unsafe,
|
|||
|
especially with targets running at very low speeds. This command
|
|||
|
was introduced with OpenOCD rev. 60, and requires a few bytes of
|
|||
|
working area.
|
|||
|
|
|||
|
-- Command: arm7_9 fast_memory_access ['enable'|'disable']
|
|||
|
Displays the value of the flag controlling use of memory writes and
|
|||
|
reads that don't check completion of the operation. If a boolean
|
|||
|
parameter is provided, first assigns that flag.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
16.4.2 ARM9 specific commands
|
|||
|
-----------------------------
|
|||
|
|
|||
|
ARM9-family cores are built around ARM9TDMI or ARM9E (including ARM9EJS)
|
|||
|
integer processors. Such cores include the ARM920T, ARM926EJ-S, and
|
|||
|
ARM966.
|
|||
|
|
|||
|
-- Command: arm9 vector_catch ['all'|'none'|list]
|
|||
|
Vector Catch hardware provides a sort of dedicated breakpoint for
|
|||
|
hardware events such as reset, interrupt, and abort. You can use
|
|||
|
this to conserve normal breakpoint resources, so long as you're not
|
|||
|
concerned with code that branches directly to those hardware
|
|||
|
vectors.
|
|||
|
|
|||
|
This always finishes by listing the current configuration. If
|
|||
|
parameters are provided, it first reconfigures the vector catch
|
|||
|
hardware to intercept 'all' of the hardware vectors, 'none' of
|
|||
|
them, or a list with one or more of the following: 'reset' 'undef'
|
|||
|
'swi' 'pabt' 'dabt' 'irq' 'fiq'.
|
|||
|
|
|||
|
16.4.3 ARM920T specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
These commands are available to ARM920T based CPUs, which are
|
|||
|
implementations of the ARMv4T architecture built using the ARM9TDMI
|
|||
|
integer core. They are available in addition to the ARM, ARM7/ARM9, and
|
|||
|
ARM9 commands.
|
|||
|
|
|||
|
-- Command: arm920t cache_info
|
|||
|
Print information about the caches found. This allows to see
|
|||
|
whether your target is an ARM920T (2x16kByte cache) or ARM922T
|
|||
|
(2x8kByte cache).
|
|||
|
|
|||
|
-- Command: arm920t cp15 regnum [value]
|
|||
|
Display cp15 register REGNUM; else if a VALUE is provided, that
|
|||
|
value is written to that register. This uses "physical access" and
|
|||
|
the register number is as shown in bits 38..33 of table 9-9 in the
|
|||
|
ARM920T TRM. (Not all registers can be written.)
|
|||
|
|
|||
|
-- Command: arm920t read_cache filename
|
|||
|
Dump the content of ICache and DCache to a file named 'filename'.
|
|||
|
|
|||
|
-- Command: arm920t read_mmu filename
|
|||
|
Dump the content of the ITLB and DTLB to a file named 'filename'.
|
|||
|
|
|||
|
16.4.4 ARM926ej-s specific commands
|
|||
|
-----------------------------------
|
|||
|
|
|||
|
These commands are available to ARM926ej-s based CPUs, which are
|
|||
|
implementations of the ARMv5TEJ architecture based on the ARM9EJ-S
|
|||
|
integer core. They are available in addition to the ARM, ARM7/ARM9, and
|
|||
|
ARM9 commands.
|
|||
|
|
|||
|
The Feroceon cores also support these commands, although they are not
|
|||
|
built from ARM926ej-s designs.
|
|||
|
|
|||
|
-- Command: arm926ejs cache_info
|
|||
|
Print information about the caches found.
|
|||
|
|
|||
|
16.4.5 ARM966E specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
These commands are available to ARM966 based CPUs, which are
|
|||
|
implementations of the ARMv5TE architecture. They are available in
|
|||
|
addition to the ARM, ARM7/ARM9, and ARM9 commands.
|
|||
|
|
|||
|
-- Command: arm966e cp15 regnum [value]
|
|||
|
Display cp15 register REGNUM; else if a VALUE is provided, that
|
|||
|
value is written to that register. The six bit REGNUM values are
|
|||
|
bits 37..32 from table 7-2 of the ARM966E-S TRM. There is no
|
|||
|
current control over bits 31..30 from that table, as required for
|
|||
|
BIST support.
|
|||
|
|
|||
|
16.4.6 XScale specific commands
|
|||
|
-------------------------------
|
|||
|
|
|||
|
Some notes about the debug implementation on the XScale CPUs:
|
|||
|
|
|||
|
The XScale CPU provides a special debug-only mini-instruction cache
|
|||
|
(mini-IC) in which exception vectors and target-resident debug handler
|
|||
|
code are placed by OpenOCD. In order to get access to the CPU, OpenOCD
|
|||
|
must point vector 0 (the reset vector) to the entry of the debug
|
|||
|
handler. However, this means that the complete first cacheline in the
|
|||
|
mini-IC is marked valid, which makes the CPU fetch all exception
|
|||
|
handlers from the mini-IC, ignoring the code in RAM.
|
|||
|
|
|||
|
To address this situation, OpenOCD provides the 'xscale vector_table'
|
|||
|
command, which allows the user to explicitly write individual entries to
|
|||
|
either the high or low vector table stored in the mini-IC.
|
|||
|
|
|||
|
It is recommended to place a pc-relative indirect branch in the vector
|
|||
|
table, and put the branch destination somewhere in memory. Doing so
|
|||
|
makes sure the code in the vector table stays constant regardless of
|
|||
|
code layout in memory:
|
|||
|
_vectors:
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
ldr pc,[pc,#0x100-8]
|
|||
|
.org 0x100
|
|||
|
.long real_reset_vector
|
|||
|
.long real_ui_handler
|
|||
|
.long real_swi_handler
|
|||
|
.long real_pf_abort
|
|||
|
.long real_data_abort
|
|||
|
.long 0 /* unused */
|
|||
|
.long real_irq_handler
|
|||
|
.long real_fiq_handler
|
|||
|
|
|||
|
Alternatively, you may choose to keep some or all of the mini-IC vector
|
|||
|
table entries synced with those written to memory by your system
|
|||
|
software. The mini-IC can not be modified while the processor is
|
|||
|
executing, but for each vector table entry not previously defined using
|
|||
|
the 'xscale vector_table' command, OpenOCD will copy the value from
|
|||
|
memory to the mini-IC every time execution resumes from a halt. This is
|
|||
|
done for both high and low vector tables (although the table not in use
|
|||
|
may not be mapped to valid memory, and in this case that copy operation
|
|||
|
will silently fail). This means that you will need to briefly halt
|
|||
|
execution at some strategic point during system start-up; e.g., after
|
|||
|
the software has initialized the vector table, but before exceptions are
|
|||
|
enabled. A breakpoint can be used to accomplish this once the
|
|||
|
appropriate location in the start-up code has been identified. A
|
|||
|
watchpoint over the vector table region is helpful in finding the
|
|||
|
location if you're not sure. Note that the same situation exists any
|
|||
|
time the vector table is modified by the system software.
|
|||
|
|
|||
|
The debug handler must be placed somewhere in the address space using
|
|||
|
the 'xscale debug_handler' command. The allowed locations for the debug
|
|||
|
handler are either (0x800 - 0x1fef800) or (0xfe000800 - 0xfffff800).
|
|||
|
The default value is 0xfe000800.
|
|||
|
|
|||
|
XScale has resources to support two hardware breakpoints and two
|
|||
|
watchpoints. However, the following restrictions on watchpoint
|
|||
|
functionality apply: (1) the value and mask arguments to the 'wp'
|
|||
|
command are not supported, (2) the watchpoint length must be a power of
|
|||
|
two and not less than four, and can not be greater than the watchpoint
|
|||
|
address, and (3) a watchpoint with a length greater than four consumes
|
|||
|
all the watchpoint hardware resources. This means that at any one time,
|
|||
|
you can have enabled either two watchpoints with a length of four, or
|
|||
|
one watchpoint with a length greater than four.
|
|||
|
|
|||
|
These commands are available to XScale based CPUs, which are
|
|||
|
implementations of the ARMv5TE architecture.
|
|||
|
|
|||
|
-- Command: xscale analyze_trace
|
|||
|
Displays the contents of the trace buffer.
|
|||
|
|
|||
|
-- Command: xscale cache_clean_address address
|
|||
|
Changes the address used when cleaning the data cache.
|
|||
|
|
|||
|
-- Command: xscale cache_info
|
|||
|
Displays information about the CPU caches.
|
|||
|
|
|||
|
-- Command: xscale cp15 regnum [value]
|
|||
|
Display cp15 register REGNUM; else if a VALUE is provided, that
|
|||
|
value is written to that register.
|
|||
|
|
|||
|
-- Command: xscale debug_handler target address
|
|||
|
Changes the address used for the specified target's debug handler.
|
|||
|
|
|||
|
-- Command: xscale dcache ['enable'|'disable']
|
|||
|
Enables or disable the CPU's data cache.
|
|||
|
|
|||
|
-- Command: xscale dump_trace filename
|
|||
|
Dumps the raw contents of the trace buffer to 'filename'.
|
|||
|
|
|||
|
-- Command: xscale icache ['enable'|'disable']
|
|||
|
Enables or disable the CPU's instruction cache.
|
|||
|
|
|||
|
-- Command: xscale mmu ['enable'|'disable']
|
|||
|
Enables or disable the CPU's memory management unit.
|
|||
|
|
|||
|
-- Command: xscale trace_buffer ['enable'|'disable' ['fill' [n] |
|
|||
|
'wrap']]
|
|||
|
Displays the trace buffer status, after optionally enabling or
|
|||
|
disabling the trace buffer and modifying how it is emptied.
|
|||
|
|
|||
|
-- Command: xscale trace_image filename [offset [type]]
|
|||
|
Opens a trace image from 'filename', optionally rebasing its
|
|||
|
segment addresses by OFFSET. The image TYPE may be one of 'bin'
|
|||
|
(binary), 'ihex' (Intel hex), 'elf' (ELF file), 's19' (Motorola
|
|||
|
s19), 'mem', or 'builder'.
|
|||
|
|
|||
|
-- Command: xscale vector_catch [mask]
|
|||
|
Display a bitmask showing the hardware vectors to catch. If the
|
|||
|
optional parameter is provided, first set the bitmask to that
|
|||
|
value.
|
|||
|
|
|||
|
The mask bits correspond with bit 16..23 in the DCSR:
|
|||
|
0x01 Trap Reset
|
|||
|
0x02 Trap Undefined Instructions
|
|||
|
0x04 Trap Software Interrupt
|
|||
|
0x08 Trap Prefetch Abort
|
|||
|
0x10 Trap Data Abort
|
|||
|
0x20 reserved
|
|||
|
0x40 Trap IRQ
|
|||
|
0x80 Trap FIQ
|
|||
|
|
|||
|
-- Command: xscale vector_table [('low'|'high') index value]
|
|||
|
|
|||
|
Set an entry in the mini-IC vector table. There are two tables:
|
|||
|
one for low vectors (at 0x00000000), and one for high vectors
|
|||
|
(0xFFFF0000), each holding the 8 exception vectors. INDEX can be
|
|||
|
1-7, because vector 0 points to the debug handler entry and can not
|
|||
|
be overwritten. VALUE holds the 32-bit opcode that is placed in
|
|||
|
the mini-IC.
|
|||
|
|
|||
|
Without arguments, the current settings are displayed.
|
|||
|
|
|||
|
16.5 ARMv6 Architecture
|
|||
|
=======================
|
|||
|
|
|||
|
16.5.1 ARM11 specific commands
|
|||
|
------------------------------
|
|||
|
|
|||
|
-- Command: arm11 memwrite burst ['enable'|'disable']
|
|||
|
Displays the value of the memwrite burst-enable flag, which is
|
|||
|
enabled by default. If a boolean parameter is provided, first
|
|||
|
assigns that flag. Burst writes are only used for memory writes
|
|||
|
larger than 1 word. They improve performance by assuming that the
|
|||
|
CPU has read each data word over JTAG and completed its write
|
|||
|
before the next word arrives, instead of polling for a status flag
|
|||
|
to verify that completion. This is usually safe, because JTAG runs
|
|||
|
much slower than the CPU.
|
|||
|
|
|||
|
-- Command: arm11 memwrite error_fatal ['enable'|'disable']
|
|||
|
Displays the value of the memwrite error_fatal flag, which is
|
|||
|
enabled by default. If a boolean parameter is provided, first
|
|||
|
assigns that flag. When set, certain memory write errors cause
|
|||
|
earlier transfer termination.
|
|||
|
|
|||
|
-- Command: arm11 step_irq_enable ['enable'|'disable']
|
|||
|
Displays the value of the flag controlling whether IRQs are enabled
|
|||
|
during single stepping; they are disabled by default. If a boolean
|
|||
|
parameter is provided, first assigns that.
|
|||
|
|
|||
|
-- Command: arm11 vcr [value]
|
|||
|
Displays the value of the _Vector Catch Register (VCR)_,
|
|||
|
coprocessor 14 register 7. If 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 _except the ARM1176_ use the same six bits.
|
|||
|
|
|||
|
16.6 ARMv7 and ARMv8 Architecture
|
|||
|
=================================
|
|||
|
|
|||
|
16.6.1 ARMv7-A specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
-- Command: cortex_a cache_info
|
|||
|
display information about target caches
|
|||
|
|
|||
|
-- Command: cortex_a dacrfixup ['on'|'off']
|
|||
|
Work around issues with software breakpoints when the program text
|
|||
|
is mapped read-only by the operating system. This option sets the
|
|||
|
CP15 DACR to "all-manager" to bypass MMU permission checks on
|
|||
|
memory access. Defaults to 'off'.
|
|||
|
|
|||
|
-- Command: cortex_a dbginit
|
|||
|
Initialize core debug Enables debug by unlocking the Software Lock
|
|||
|
and clearing sticky powerdown indications
|
|||
|
|
|||
|
-- Command: cortex_a smp [on|off]
|
|||
|
Display/set the current SMP mode
|
|||
|
|
|||
|
-- Command: cortex_a smp_gdb [core_id]
|
|||
|
Display/set the current core displayed in GDB
|
|||
|
|
|||
|
-- Command: cortex_a maskisr ['on'|'off']
|
|||
|
Selects whether interrupts will be processed when single stepping
|
|||
|
|
|||
|
-- Command: cache_config l2x [base way]
|
|||
|
configure l2x cache
|
|||
|
|
|||
|
-- Command: cortex_a mmu dump ['0'|'1'|'addr' address ['num_entries']]
|
|||
|
Dump the MMU translation table from TTB0 or TTB1 register, or from
|
|||
|
physical memory location ADDRESS. When dumping the table from
|
|||
|
ADDRESS, print at most NUM_ENTRIES page table entries. NUM_ENTRIES
|
|||
|
is optional, if omitted, the maximum possible (4096) entries are
|
|||
|
printed.
|
|||
|
|
|||
|
16.6.2 ARMv7-R specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
-- Command: cortex_r4 dbginit
|
|||
|
Initialize core debug Enables debug by unlocking the Software Lock
|
|||
|
and clearing sticky powerdown indications
|
|||
|
|
|||
|
-- Command: cortex_r4 maskisr ['on'|'off']
|
|||
|
Selects whether interrupts will be processed when single stepping
|
|||
|
|
|||
|
16.6.3 ARM CoreSight TPIU and SWO specific commands
|
|||
|
---------------------------------------------------
|
|||
|
|
|||
|
ARM CoreSight provides several modules to generate debugging information
|
|||
|
internally (ITM, DWT and ETM). Their output is directed through TPIU or
|
|||
|
SWO modules to be captured externally either on an SWO pin (this
|
|||
|
configuration is called SWV) or on a synchronous parallel trace port.
|
|||
|
|
|||
|
ARM CoreSight provides independent HW blocks named TPIU and SWO each
|
|||
|
with its own functionality. Embedded in Cortex-M3 and M4, ARM provides
|
|||
|
an optional HW block that includes both TPIU and SWO functionalities and
|
|||
|
is again named TPIU, which causes quite some confusion. The registers
|
|||
|
map of all the TPIU and SWO implementations allows using a single driver
|
|||
|
that detects at runtime the features available.
|
|||
|
|
|||
|
The 'tpiu' is used for either TPIU or SWO. A convenient alias 'swo' is
|
|||
|
available to help distinguish, in scripts, the commands for SWO from the
|
|||
|
commands for TPIU.
|
|||
|
|
|||
|
-- Command: swo ...
|
|||
|
Alias of 'tpiu ...'. Can be used in scripts to distinguish the
|
|||
|
commands for SWO from the commands for TPIU.
|
|||
|
|
|||
|
-- Command: tpiu create tpiu_name configparams...
|
|||
|
Creates a TPIU or a SWO object. The two commands are equivalent.
|
|||
|
Add the object in a list and add new commands ('TPIU_NAME') which
|
|||
|
are used for various purposes including additional configuration.
|
|||
|
|
|||
|
* TPIU_NAME - the name of the TPIU or SWO object. This name is
|
|||
|
also used to create the object's command, referred to here as
|
|||
|
'$tpiu_name', and in other places where the TPIU or SWO needs
|
|||
|
to be identified.
|
|||
|
* CONFIGPARAMS - all parameters accepted by '$tpiu_name
|
|||
|
configure' are permitted.
|
|||
|
|
|||
|
You _must_ set here the AP and MEM_AP base_address through
|
|||
|
'-dap DAP_NAME', '-ap-num AP_NUMBER' and '-baseaddr
|
|||
|
BASE_ADDRESS'.
|
|||
|
|
|||
|
-- Command: tpiu names
|
|||
|
Lists all the TPIU or SWO objects created so far. The two commands
|
|||
|
are equivalent.
|
|||
|
|
|||
|
-- Command: tpiu init
|
|||
|
Initialize all registered TPIU and SWO. The two commands are
|
|||
|
equivalent. These commands are used internally during
|
|||
|
initialization. They can be issued at any time after the
|
|||
|
initialization, too.
|
|||
|
|
|||
|
-- Command: $tpiu_name cget queryparm
|
|||
|
Each configuration parameter accepted by '$tpiu_name configure' can
|
|||
|
be individually queried, to return its current value. The
|
|||
|
QUERYPARM is a parameter name accepted by that command, such as
|
|||
|
'-dap'.
|
|||
|
|
|||
|
-- Command: $tpiu_name configure configparams...
|
|||
|
The options accepted by this command may also be specified as
|
|||
|
parameters to 'tpiu create'. Their values can later be queried one
|
|||
|
at a time by using the '$tpiu_name cget' command.
|
|||
|
|
|||
|
* '-dap' DAP_NAME - names the DAP used to access this TPIU.
|
|||
|
*Note DAP declaration: dapdeclaration, on how to create and
|
|||
|
manage DAP instances.
|
|||
|
|
|||
|
* '-ap-num' AP_NUMBER - sets DAP access port for TPIU, AP_NUMBER
|
|||
|
is the numeric index of the DAP AP the TPIU is connected to.
|
|||
|
|
|||
|
* '-baseaddr' BASE_ADDRESS - sets the TPIU BASE_ADDRESS where to
|
|||
|
access the TPIU in the DAP AP memory space.
|
|||
|
|
|||
|
* '-protocol' ('sync'|'uart'|'manchester') - sets the protocol
|
|||
|
used for trace data:
|
|||
|
- 'sync' - synchronous parallel trace output mode, using
|
|||
|
PORT_WIDTH data bits (default);
|
|||
|
- 'uart' - use asynchronous SWO mode with NRZ (same as
|
|||
|
regular UART 8N1) coding;
|
|||
|
- 'manchester' - use asynchronous SWO mode with Manchester
|
|||
|
coding.
|
|||
|
|
|||
|
* '-event' EVENT_NAME EVENT_BODY - assigns an event handler, a
|
|||
|
TCL string which is evaluated when the event is triggered.
|
|||
|
The events 'pre-enable', 'post-enable', 'pre-disable' and
|
|||
|
'post-disable' are defined for TPIU/SWO. A typical use case
|
|||
|
for the event 'pre-enable' is to enable the trace clock of the
|
|||
|
TPIU.
|
|||
|
|
|||
|
* '-output' ('external'|':'PORT|FILENAME|'-') - specifies the
|
|||
|
destination of the trace data:
|
|||
|
- 'external' - configure TPIU/SWO to let user capture trace
|
|||
|
output externally, either with an additional UART or with
|
|||
|
a logic analyzer (default);
|
|||
|
- '-' - configure TPIU/SWO and debug adapter to gather
|
|||
|
trace data and forward it to 'tcl_trace' command;
|
|||
|
- ':'PORT - configure TPIU/SWO and debug adapter to gather
|
|||
|
trace data, open a TCP server at port PORT and send the
|
|||
|
trace data to each connected client;
|
|||
|
- FILENAME - configure TPIU/SWO and debug adapter to gather
|
|||
|
trace data and append it to FILENAME, which can be either
|
|||
|
a regular file or a named pipe.
|
|||
|
|
|||
|
* '-traceclk' TRACECLKIN_FREQ - mandatory parameter. Specifies
|
|||
|
the frequency in Hz of the trace clock. For the TPIU embedded
|
|||
|
in Cortex-M3 or M4, this is usually the same frequency as
|
|||
|
HCLK. For protocol 'sync' this is twice the frequency of the
|
|||
|
pin data rate.
|
|||
|
|
|||
|
* '-pin-freq' TRACE_FREQ - specifies the expected data rate in
|
|||
|
Hz of the SWO pin. Parameter used only on protocols 'uart'
|
|||
|
and 'manchester'. Can be omitted to let the adapter driver
|
|||
|
select the maximum supported rate automatically.
|
|||
|
|
|||
|
* '-port-width' PORT_WIDTH - sets to PORT_WIDTH the width of the
|
|||
|
synchronous parallel port used for trace output. Parameter
|
|||
|
used only on protocol 'sync'. If not specified, default value
|
|||
|
is 1.
|
|||
|
|
|||
|
* '-formatter' ('0'|'1') - specifies if the formatter should be
|
|||
|
enabled. Parameter used only on protocol 'sync'. If not
|
|||
|
specified, default value is 0.
|
|||
|
|
|||
|
-- Command: $tpiu_name enable
|
|||
|
Uses the parameters specified by the previous '$tpiu_name
|
|||
|
configure' to configure and enable the TPIU or the SWO. If
|
|||
|
required, the adapter is also configured and enabled to receive the
|
|||
|
trace data. This command can be used before 'init', but it will
|
|||
|
take effect only after the 'init'.
|
|||
|
|
|||
|
-- Command: $tpiu_name disable
|
|||
|
Disable the TPIU or the SWO, terminating the receiving of the trace
|
|||
|
data.
|
|||
|
|
|||
|
Example usage:
|
|||
|
1. STM32L152 board is programmed with an application that configures
|
|||
|
PLL to provide core clock with 24MHz frequency; to use ITM output
|
|||
|
it's enough to:
|
|||
|
#include <libopencm3/cm3/itm.h>
|
|||
|
...
|
|||
|
ITM_STIM8(0) = c;
|
|||
|
...
|
|||
|
(the most obvious way is to use the first stimulus port for printf,
|
|||
|
for that this ITM_STIM8 assignment can be used inside _write(); to
|
|||
|
make it blocking to avoid data loss, add 'while (!(ITM_STIM8(0) &
|
|||
|
ITM_STIM_FIFOREADY));');
|
|||
|
2. An FT2232H UART is connected to the SWO pin of the board;
|
|||
|
3. Commands to configure UART for 12MHz baud rate:
|
|||
|
$ setserial /dev/ttyUSB1 spd_cust divisor 5
|
|||
|
$ stty -F /dev/ttyUSB1 38400
|
|||
|
(FT2232H's base frequency is 60MHz, spd_cust allows to alias 38400
|
|||
|
baud with our custom divisor to get 12MHz)
|
|||
|
4. 'itmdump -f /dev/ttyUSB1 -d1'
|
|||
|
5. OpenOCD invocation line:
|
|||
|
openocd -f interface/stlink.cfg \
|
|||
|
-c "transport select hla_swd" \
|
|||
|
-f target/stm32l1.cfg \
|
|||
|
-c "stm32l1.tpiu configure -protocol uart" \
|
|||
|
-c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \
|
|||
|
-c "stm32l1.tpiu enable"
|
|||
|
|
|||
|
16.6.4 ARMv7-M specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
-- Command: itm port PORT ('0'|'1'|'on'|'off')
|
|||
|
Enable or disable trace output for ITM stimulus PORT (counting from
|
|||
|
0). Port 0 is enabled on target creation automatically.
|
|||
|
|
|||
|
-- Command: itm ports ('0'|'1'|'on'|'off')
|
|||
|
Enable or disable trace output for all ITM stimulus ports.
|
|||
|
|
|||
|
16.6.5 Cortex-M specific commands
|
|||
|
---------------------------------
|
|||
|
|
|||
|
-- Command: cortex_m maskisr ('auto'|'on'|'off'|'steponly')
|
|||
|
Control masking (disabling) interrupts during target step/resume.
|
|||
|
|
|||
|
The 'auto' option handles interrupts during stepping in a way that
|
|||
|
they get served but don't disturb the program flow. The step
|
|||
|
command first allows pending interrupt handlers to execute, then
|
|||
|
disables interrupts and steps over the next instruction where the
|
|||
|
core was halted. After the step interrupts are enabled again. If
|
|||
|
the interrupt handlers don't complete within 500ms, the step
|
|||
|
command leaves with the core running.
|
|||
|
|
|||
|
The 'steponly' option disables interrupts during single-stepping
|
|||
|
but enables them during normal execution. This can be used as a
|
|||
|
partial workaround for 702596 erratum in Cortex-M7 r0p1. See
|
|||
|
"Cortex-M7 (AT610) and Cortex-M7 with FPU (AT611) Software
|
|||
|
Developer Errata Notice" from ARM for further details.
|
|||
|
|
|||
|
Note that a free hardware (FPB) breakpoint is required for the
|
|||
|
'auto' option. If no breakpoint is available at the time of the
|
|||
|
step, then the step is taken with interrupts enabled, i.e. the
|
|||
|
same way the 'off' option does.
|
|||
|
|
|||
|
Default is 'auto'.
|
|||
|
|
|||
|
-- Command: cortex_m vector_catch ['all'|'none'|list]
|
|||
|
Vector Catch hardware provides dedicated breakpoints for certain
|
|||
|
hardware events.
|
|||
|
|
|||
|
Parameters request interception of 'all' of these hardware event
|
|||
|
vectors, 'none' of them, or one or more of the following:
|
|||
|
'hard_err' for a HardFault exception; 'mm_err' for a MemManage
|
|||
|
exception; 'bus_err' for a BusFault exception; 'irq_err',
|
|||
|
'state_err', 'chk_err', or 'nocp_err' for various UsageFault
|
|||
|
exceptions; or 'reset'. If NVIC setup code does not enable them,
|
|||
|
MemManage, BusFault, and UsageFault exceptions are mapped to
|
|||
|
HardFault. UsageFault checks for divide-by-zero and unaligned
|
|||
|
access must also be explicitly enabled.
|
|||
|
|
|||
|
This finishes by listing the current vector catch configuration.
|
|||
|
|
|||
|
-- Command: cortex_m reset_config ('sysresetreq'|'vectreset')
|
|||
|
Control reset handling if hardware srst is not fitted *Note
|
|||
|
reset_config: reset_config.
|
|||
|
|
|||
|
- 'sysresetreq' use AIRCR SYSRESETREQ to reset system.
|
|||
|
- 'vectreset' use AIRCR VECTRESET to reset system (default).
|
|||
|
|
|||
|
Using 'vectreset' is a safe option for Cortex-M3, M4 and M7 cores.
|
|||
|
This however has the disadvantage of only resetting the core, all
|
|||
|
peripherals are unaffected. A solution would be to use a
|
|||
|
'reset-init' event handler to manually reset the peripherals.
|
|||
|
*Note Target Events: targetevents.
|
|||
|
|
|||
|
Cortex-M0, M0+ and M1 do not support 'vectreset', use 'sysresetreq'
|
|||
|
instead.
|
|||
|
|
|||
|
16.6.6 ARMv8-A specific commands
|
|||
|
--------------------------------
|
|||
|
|
|||
|
-- Command: aarch64 cache_info
|
|||
|
Display information about target caches
|
|||
|
|
|||
|
-- Command: aarch64 dbginit
|
|||
|
This command enables debugging by clearing the OS Lock and sticky
|
|||
|
power-down and reset indications. It also establishes the
|
|||
|
expected, basic cross-trigger configuration the aarch64 target code
|
|||
|
relies on. In a configuration file, the command would typically be
|
|||
|
called from a 'reset-end' or 'reset-deassert-post' handler, to
|
|||
|
re-enable debugging after a system reset. However, normally it is
|
|||
|
not necessary to use the command at all.
|
|||
|
|
|||
|
-- Command: aarch64 disassemble address [count]
|
|||
|
Disassembles COUNT instructions starting at ADDRESS. If COUNT is
|
|||
|
not specified, a single instruction is disassembled.
|
|||
|
|
|||
|
-- Command: aarch64 smp [on|off]
|
|||
|
Display, enable or disable SMP handling mode. The state of SMP
|
|||
|
handling influences the way targets in an SMP group are handled by
|
|||
|
the run control. With SMP handling enabled, issuing halt or resume
|
|||
|
to one core will trigger halting or resuming of all cores in the
|
|||
|
group. The command 'target smp' defines which targets are in the
|
|||
|
SMP group. With SMP handling disabled, all targets need to be
|
|||
|
treated individually.
|
|||
|
|
|||
|
-- Command: aarch64 maskisr ['on'|'off']
|
|||
|
Selects whether interrupts will be processed when single stepping.
|
|||
|
The default configuration is 'on'.
|
|||
|
|
|||
|
-- Command: $target_name catch_exc
|
|||
|
['off'|'sec_el1'|'sec_el3'|'nsec_el1'|'nsec_el2']+
|
|||
|
Cause '$target_name' to halt when an exception is taken. Any
|
|||
|
combination of Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is
|
|||
|
valid. The target '$target_name' will halt before taking the
|
|||
|
exception. In order to resume the target, the exception catch must
|
|||
|
be disabled again with '$target_name catch_exc off'. Issuing the
|
|||
|
command without options prints the current configuration.
|
|||
|
|
|||
|
16.7 EnSilica eSi-RISC Architecture
|
|||
|
===================================
|
|||
|
|
|||
|
eSi-RISC is a highly configurable microprocessor architecture for
|
|||
|
embedded systems provided by EnSilica. (See:
|
|||
|
<http://www.ensilica.com/risc-ip/>.)
|
|||
|
|
|||
|
16.7.1 eSi-RISC Configuration
|
|||
|
-----------------------------
|
|||
|
|
|||
|
-- Command: esirisc cache_arch ('harvard'|'von_neumann')
|
|||
|
Configure the caching architecture. Targets with the
|
|||
|
'UNIFIED_ADDRESS_SPACE' option disabled employ a Harvard
|
|||
|
architecture. By default, 'von_neumann' is assumed.
|
|||
|
|
|||
|
-- Command: esirisc hwdc ('all'|'none'|mask ...)
|
|||
|
Configure hardware debug control. The HWDC register controls which
|
|||
|
exceptions return control back to the debugger. Possible masks are
|
|||
|
'all', 'none', 'reset', 'interrupt', 'syscall', 'error', and
|
|||
|
'debug'. By default, 'reset', 'error', and 'debug' are enabled.
|
|||
|
|
|||
|
16.7.2 eSi-RISC Operation
|
|||
|
-------------------------
|
|||
|
|
|||
|
-- Command: esirisc flush_caches
|
|||
|
Flush instruction and data caches. This command requires that the
|
|||
|
target is halted when the command is issued and configured with an
|
|||
|
instruction or data cache.
|
|||
|
|
|||
|
16.7.3 eSi-Trace Configuration
|
|||
|
------------------------------
|
|||
|
|
|||
|
eSi-RISC targets may be configured with support for instruction tracing.
|
|||
|
Trace data may be written to an in-memory buffer or FIFO. If a FIFO is
|
|||
|
configured, DMA is typically employed to move trace data off-device
|
|||
|
using a high-speed peripheral (eg. SPI). Collected trace data is
|
|||
|
encoded in one of three different formats. At a minimum, 'esirisc trace
|
|||
|
buffer' or 'esirisc trace fifo' must be issued along with 'esirisc trace
|
|||
|
format' before trace data can be collected.
|
|||
|
|
|||
|
OpenOCD provides rudimentary analysis of collected trace data. If more
|
|||
|
detail is needed, collected trace data can be dumped to a file and
|
|||
|
processed by external tooling.
|
|||
|
|
|||
|
Issues: OpenOCD is unable to process trace data sent to a FIFO. A
|
|||
|
potential workaround for this issue is to configure DMA to copy
|
|||
|
trace data to an in-memory buffer, which can then be passed to the
|
|||
|
'esirisc trace analyze' and 'esirisc trace dump' commands.
|
|||
|
|
|||
|
It is possible to corrupt trace data when using a FIFO if the
|
|||
|
peripheral responsible for draining data from the FIFO is not fast
|
|||
|
enough. This can be managed by enabling flow control, however this
|
|||
|
can impact timing-sensitive software operation on the CPU.
|
|||
|
|
|||
|
-- Command: esirisc trace buffer address size ['wrap']
|
|||
|
Configure trace buffer using the provided address and size. If the
|
|||
|
'wrap' option is specified, trace collection will continue once the
|
|||
|
end of the buffer is reached. By default, wrap is disabled.
|
|||
|
|
|||
|
-- Command: esirisc trace fifo address
|
|||
|
Configure trace FIFO using the provided address.
|
|||
|
|
|||
|
-- Command: esirisc trace flow_control ('enable'|'disable')
|
|||
|
Enable or disable stalling the CPU to collect trace data. By
|
|||
|
default, flow control is disabled.
|
|||
|
|
|||
|
-- Command: esirisc trace format ('full'|'branch'|'icache') pc_bits
|
|||
|
Configure trace format and number of PC bits to be captured.
|
|||
|
'pc_bits' must be within 1 and 31 as the LSB is not collected. If
|
|||
|
external tooling is used to analyze collected trace data, these
|
|||
|
values must match.
|
|||
|
|
|||
|
Supported trace formats:
|
|||
|
* 'full' capture full trace data, allowing execution history and
|
|||
|
timing to be determined.
|
|||
|
* 'branch' capture taken branch instructions and branch target
|
|||
|
addresses.
|
|||
|
* 'icache' capture instruction cache misses.
|
|||
|
|
|||
|
-- Command: esirisc trace trigger start ('condition') [start_data
|
|||
|
start_mask]
|
|||
|
Configure trigger start condition using the provided start data and
|
|||
|
mask. A brief description of each condition is provided below; for
|
|||
|
more detail on how these values are used, see the eSi-RISC
|
|||
|
Architecture Manual.
|
|||
|
|
|||
|
Supported conditions:
|
|||
|
* 'none' manual tracing (see 'esirisc trace start').
|
|||
|
* 'pc' start tracing if the PC matches start data and mask.
|
|||
|
* 'load' start tracing if the effective address of a load
|
|||
|
instruction matches start data and mask.
|
|||
|
* 'store' start tracing if the effective address of a store
|
|||
|
instruction matches start data and mask.
|
|||
|
* 'exception' start tracing if the EID of an exception matches
|
|||
|
start data and mask.
|
|||
|
* 'eret' start tracing when an 'ERET' instruction is executed.
|
|||
|
* 'wait' start tracing when a 'WAIT' instruction is executed.
|
|||
|
* 'stop' start tracing when a 'STOP' instruction is executed.
|
|||
|
* 'high' start tracing when an external signal is a logical
|
|||
|
high.
|
|||
|
* 'low' start tracing when an external signal is a logical low.
|
|||
|
|
|||
|
-- Command: esirisc trace trigger stop ('condition') [stop_data
|
|||
|
stop_mask]
|
|||
|
Configure trigger stop condition using the provided stop data and
|
|||
|
mask. A brief description of each condition is provided below; for
|
|||
|
more detail on how these values are used, see the eSi-RISC
|
|||
|
Architecture Manual.
|
|||
|
|
|||
|
Supported conditions:
|
|||
|
* 'none' manual tracing (see 'esirisc trace stop').
|
|||
|
* 'pc' stop tracing if the PC matches stop data and mask.
|
|||
|
* 'load' stop tracing if the effective address of a load
|
|||
|
instruction matches stop data and mask.
|
|||
|
* 'store' stop tracing if the effective address of a store
|
|||
|
instruction matches stop data and mask.
|
|||
|
* 'exception' stop tracing if the EID of an exception matches
|
|||
|
stop data and mask.
|
|||
|
* 'eret' stop tracing when an 'ERET' instruction is executed.
|
|||
|
* 'wait' stop tracing when a 'WAIT' instruction is executed.
|
|||
|
* 'stop' stop tracing when a 'STOP' instruction is executed.
|
|||
|
|
|||
|
-- Command: esirisc trace trigger delay ('trigger') [cycles]
|
|||
|
Configure trigger start/stop delay in clock cycles.
|
|||
|
|
|||
|
Supported triggers:
|
|||
|
* 'none' no delay to start or stop collection.
|
|||
|
* 'start' delay 'cycles' after trigger to start collection.
|
|||
|
* 'stop' delay 'cycles' after trigger to stop collection.
|
|||
|
* 'both' delay 'cycles' after both triggers to start or stop
|
|||
|
collection.
|
|||
|
|
|||
|
16.7.4 eSi-Trace Operation
|
|||
|
--------------------------
|
|||
|
|
|||
|
-- Command: esirisc trace init
|
|||
|
Initialize trace collection. This command must be called any time
|
|||
|
the configuration changes. If a trace buffer has been configured,
|
|||
|
the contents will be overwritten when trace collection starts.
|
|||
|
|
|||
|
-- Command: esirisc trace info
|
|||
|
Display trace configuration.
|
|||
|
|
|||
|
-- Command: esirisc trace status
|
|||
|
Display trace collection status.
|
|||
|
|
|||
|
-- Command: esirisc trace start
|
|||
|
Start manual trace collection.
|
|||
|
|
|||
|
-- Command: esirisc trace stop
|
|||
|
Stop manual trace collection.
|
|||
|
|
|||
|
-- Command: esirisc trace analyze [address size]
|
|||
|
Analyze collected trace data. This command may only be used if a
|
|||
|
trace buffer has been configured. If a trace FIFO has been
|
|||
|
configured, trace data must be copied to an in-memory buffer
|
|||
|
identified by the 'address' and 'size' options using DMA.
|
|||
|
|
|||
|
-- Command: esirisc trace dump [address size] 'filename'
|
|||
|
Dump collected trace data to file. This command may only be used
|
|||
|
if a trace buffer has been configured. If a trace FIFO has been
|
|||
|
configured, trace data must be copied to an in-memory buffer
|
|||
|
identified by the 'address' and 'size' options using DMA.
|
|||
|
|
|||
|
16.8 Intel Architecture
|
|||
|
=======================
|
|||
|
|
|||
|
Intel Quark X10xx is the first product in the Quark family of SoCs. It
|
|||
|
is an IA-32 (Pentium x86 ISA) compatible SoC. The core CPU in the X10xx
|
|||
|
is codenamed Lakemont. Lakemont version 1 (LMT1) is used in X10xx. The
|
|||
|
CPU TAP (Lakemont TAP) is used for software debug and the CLTAP is used
|
|||
|
for SoC level operations. Useful docs are here:
|
|||
|
https://communities.intel.com/community/makers/documentation
|
|||
|
* Intel Quark SoC X1000 OpenOCD/GDB/Eclipse App Note (web search for
|
|||
|
doc num 330015)
|
|||
|
* Intel Quark SoC X1000 Debug Operations User Guide (web search for
|
|||
|
doc num 329866)
|
|||
|
* Intel Quark SoC X1000 Datasheet (web search for doc num 329676)
|
|||
|
|
|||
|
16.8.1 x86 32-bit specific commands
|
|||
|
-----------------------------------
|
|||
|
|
|||
|
The three main address spaces for x86 are memory, I/O and configuration
|
|||
|
space. These commands allow a user to read and write to the 64Kbyte I/O
|
|||
|
address space.
|
|||
|
|
|||
|
-- Command: x86_32 idw address
|
|||
|
Display the contents of a 32-bit I/O port from address range 0x0000
|
|||
|
- 0xffff.
|
|||
|
|
|||
|
-- Command: x86_32 idh address
|
|||
|
Display the contents of a 16-bit I/O port from address range 0x0000
|
|||
|
- 0xffff.
|
|||
|
|
|||
|
-- Command: x86_32 idb address
|
|||
|
Display the contents of a 8-bit I/O port from address range 0x0000
|
|||
|
- 0xffff.
|
|||
|
|
|||
|
-- Command: x86_32 iww address
|
|||
|
Write the contents of a 32-bit I/O port to address range 0x0000 -
|
|||
|
0xffff.
|
|||
|
|
|||
|
-- Command: x86_32 iwh address
|
|||
|
Write the contents of a 16-bit I/O port to address range 0x0000 -
|
|||
|
0xffff.
|
|||
|
|
|||
|
-- Command: x86_32 iwb address
|
|||
|
Write the contents of a 8-bit I/O port to address range 0x0000 -
|
|||
|
0xffff.
|
|||
|
|
|||
|
16.9 OpenRISC Architecture
|
|||
|
==========================
|
|||
|
|
|||
|
The OpenRISC CPU is a soft core. It is used in a programmable SoC which
|
|||
|
can be configured with any of the TAP / Debug Unit available.
|
|||
|
|
|||
|
16.9.1 TAP and Debug Unit selection commands
|
|||
|
--------------------------------------------
|
|||
|
|
|||
|
-- Command: tap_select ('vjtag'|'mohor'|'xilinx_bscan')
|
|||
|
Select between the Altera Virtual JTAG , Xilinx Virtual JTAG and
|
|||
|
Mohor TAP.
|
|||
|
-- Command: du_select ('adv'|'mohor') [option]
|
|||
|
Select between the Advanced Debug Interface and the classic one.
|
|||
|
|
|||
|
An option can be passed as a second argument to the debug unit.
|
|||
|
|
|||
|
When using the Advanced Debug Interface, option = 1 means the RTL
|
|||
|
core is configured with ADBG_USE_HISPEED = 1. This configuration
|
|||
|
skips status checking between bytes while doing read or write
|
|||
|
bursts.
|
|||
|
|
|||
|
16.9.2 Registers commands
|
|||
|
-------------------------
|
|||
|
|
|||
|
-- Command: addreg [name] [address] [feature] [reg_group]
|
|||
|
Add a new register in the cpu register list. This register will be
|
|||
|
included in the generated target descriptor file.
|
|||
|
|
|||
|
*[feature]* must be "org.gnu.gdb.or1k.group[0..10]".
|
|||
|
|
|||
|
*[reg_group]* can be anything. The default register list defines
|
|||
|
"system", "dmmu", "immu", "dcache", "icache", "mac", "debug",
|
|||
|
"perf", "power", "pic" and "timer" groups.
|
|||
|
|
|||
|
_example:_
|
|||
|
addreg rtest 0x1234 org.gnu.gdb.or1k.group0 system
|
|||
|
|
|||
|
16.10 RISC-V Architecture
|
|||
|
=========================
|
|||
|
|
|||
|
RISC-V (http://riscv.org/) is a free and open ISA. OpenOCD supports JTAG
|
|||
|
debug of RV32 and RV64 cores in heterogeneous multicore systems of up to
|
|||
|
32 harts. (It's possible to increase this limit to 1024 by changing
|
|||
|
RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the
|
|||
|
RISC-V Debug Specification, but there is also support for legacy targets
|
|||
|
that implement version 0.11.
|
|||
|
|
|||
|
16.10.1 RISC-V Terminology
|
|||
|
--------------------------
|
|||
|
|
|||
|
A _hart_ is a hardware thread. A hart may share resources (eg. FPU)
|
|||
|
with another hart, or may be a separate core. RISC-V treats those the
|
|||
|
same, and OpenOCD exposes each hart as a separate core.
|
|||
|
|
|||
|
16.10.2 Vector Registers
|
|||
|
------------------------
|
|||
|
|
|||
|
For harts that implement the vector extension, OpenOCD provides access
|
|||
|
to the relevant CSRs, as well as the vector registers (v0-v31). The
|
|||
|
size of each vector register is dependent on the value of vlenb. RISC-V
|
|||
|
allows each vector register to be divided into selected-width elements,
|
|||
|
and this division can be changed at run-time. Because OpenOCD cannot
|
|||
|
update register definitions at run-time, it exposes each vector register
|
|||
|
to gdb as a union of fields of vectors so that users can easily access
|
|||
|
individual bytes, shorts, words, longs, and quads inside each vector
|
|||
|
register. It is left to gdb or higher-level debuggers to present this
|
|||
|
data in a more intuitive format.
|
|||
|
|
|||
|
In the XML register description, the vector registers (when vlenb=16)
|
|||
|
look as follows:
|
|||
|
|
|||
|
<feature name="org.gnu.gdb.riscv.vector">
|
|||
|
<vector id="bytes" type="uint8" count="16"/>
|
|||
|
<vector id="shorts" type="uint16" count="8"/>
|
|||
|
<vector id="words" type="uint32" count="4"/>
|
|||
|
<vector id="longs" type="uint64" count="2"/>
|
|||
|
<vector id="quads" type="uint128" count="1"/>
|
|||
|
<union id="riscv_vector">
|
|||
|
<field name="b" type="bytes"/>
|
|||
|
<field name="s" type="shorts"/>
|
|||
|
<field name="w" type="words"/>
|
|||
|
<field name="l" type="longs"/>
|
|||
|
<field name="q" type="quads"/>
|
|||
|
</union>
|
|||
|
<reg name="v0" bitsize="128" regnum="4162" save-restore="no"
|
|||
|
type="riscv_vector" group="vector"/>
|
|||
|
...
|
|||
|
<reg name="v31" bitsize="128" regnum="4193" save-restore="no"
|
|||
|
type="riscv_vector" group="vector"/>
|
|||
|
</feature>
|
|||
|
|
|||
|
16.10.3 RISC-V Debug Configuration Commands
|
|||
|
-------------------------------------------
|
|||
|
|
|||
|
-- Command: riscv dump_sample_buf [base64]
|
|||
|
Dump and clear the contents of the sample buffer. Which samples
|
|||
|
are collected is configured with 'riscv memory_sample'. If the
|
|||
|
optional base64 argument is passed, the raw buffer is dumped in
|
|||
|
base64 format, so that external tools can gather the data
|
|||
|
efficiently.
|
|||
|
|
|||
|
-- Config Command: riscv expose_csrs n[-m|=name] [...]
|
|||
|
Configure which CSRs to expose in addition to the standard ones.
|
|||
|
The CSRs to expose can be specified as individual register numbers
|
|||
|
or register ranges (inclusive). For the individually listed CSRs,
|
|||
|
a human-readable name can optionally be set using the 'n=name'
|
|||
|
syntax, which will get 'csr_' prepended to it. If no name is
|
|||
|
provided, the register will be named 'csr<n>'.
|
|||
|
|
|||
|
By default OpenOCD attempts to expose only CSRs that are mentioned
|
|||
|
in a spec, and then only if the corresponding extension appears to
|
|||
|
be implemented. This command can be used if OpenOCD gets this
|
|||
|
wrong, or if the target implements custom CSRs.
|
|||
|
|
|||
|
# Expose a single RISC-V CSR number 128 under the name "csr128":
|
|||
|
$_TARGETNAME expose_csrs 128
|
|||
|
|
|||
|
# Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132":
|
|||
|
$_TARGETNAME expose_csrs 128-132
|
|||
|
|
|||
|
# Expose a single RISC-V CSR number 1996 under custom name "csr_myregister":
|
|||
|
$_TARGETNAME expose_csrs 1996=myregister
|
|||
|
|
|||
|
-- Config Command: riscv expose_custom n[-m|=name] [...]
|
|||
|
The RISC-V Debug Specification allows targets to expose custom
|
|||
|
registers through abstract commands. (See Section 3.5.1.1 in that
|
|||
|
document.) This command configures individual registers or
|
|||
|
register ranges (inclusive) that shall be exposed. Number 0
|
|||
|
indicates the first custom register, whose abstract command number
|
|||
|
is 0xc000. For individually listed registers, a human-readable
|
|||
|
name can be optionally provided using the 'n=name' syntax, which
|
|||
|
will get 'custom_' prepended to it. If no name is provided, the
|
|||
|
register will be named 'custom<n>'.
|
|||
|
|
|||
|
# Expose one RISC-V custom register with number 0xc010 (0xc000 + 16)
|
|||
|
# under the name "custom16":
|
|||
|
$_TARGETNAME expose_custom 16
|
|||
|
|
|||
|
# Expose a range of RISC-V custom registers with numbers 0xc010 .. 0xc018
|
|||
|
# (0xc000+16 .. 0xc000+24) under the names "custom16" through "custom24":
|
|||
|
$_TARGETNAME expose_custom 16-24
|
|||
|
|
|||
|
# Expose one RISC-V custom register with number 0xc020 (0xc000 + 32) under
|
|||
|
# user-defined name "custom_myregister":
|
|||
|
$_TARGETNAME expose_custom 32=myregister
|
|||
|
|
|||
|
-- Command: riscv memory_sample bucket address|clear [size=4]
|
|||
|
Configure OpenOCD to frequently read size bytes at the given
|
|||
|
addresses. Execute the command with no arguments to see the
|
|||
|
current configuration. Use clear to stop using a given bucket.
|
|||
|
|
|||
|
OpenOCD will allocate a 1MB sample buffer, and when it fills up no
|
|||
|
more samples will be collected until it is emptied with 'riscv
|
|||
|
dump_sample_buf'.
|
|||
|
|
|||
|
-- Command: riscv repeat_read count address [size=4]
|
|||
|
Quickly read count words of the given size from address. This can
|
|||
|
be useful to read out a buffer that's memory-mapped to be accessed
|
|||
|
through a single address, or to sample a changing value in a
|
|||
|
memory-mapped device.
|
|||
|
|
|||
|
-- Command: riscv set_command_timeout_sec [seconds]
|
|||
|
Set the wall-clock timeout (in seconds) for individual commands.
|
|||
|
The default should work fine for all but the slowest targets (eg.
|
|||
|
simulators).
|
|||
|
|
|||
|
-- Command: riscv set_reset_timeout_sec [seconds]
|
|||
|
Set the maximum time to wait for a hart to come out of reset after
|
|||
|
reset is deasserted.
|
|||
|
|
|||
|
-- Command: riscv set_scratch_ram none|[address]
|
|||
|
Set the address of 16 bytes of scratch RAM the debugger can use, or
|
|||
|
'none'. This is used to access 64-bit floating point registers on
|
|||
|
32-bit targets.
|
|||
|
|
|||
|
-- Command: riscv set_mem_access method1 [method2] [method3]
|
|||
|
Specify which RISC-V memory access method(s) shall be used, and in
|
|||
|
which order of priority. At least one method must be specified.
|
|||
|
|
|||
|
Available methods are:
|
|||
|
* 'progbuf' - Use RISC-V Debug Program Buffer to access memory.
|
|||
|
* 'sysbus' - Access memory via RISC-V Debug System Bus
|
|||
|
interface.
|
|||
|
* 'abstract' - Access memory via RISC-V Debug abstract commands.
|
|||
|
|
|||
|
By default, all memory access methods are enabled in the following
|
|||
|
order: 'progbuf sysbus abstract'.
|
|||
|
|
|||
|
This command can be used to change the memory access methods if the
|
|||
|
default behavior is not suitable for a particular target.
|
|||
|
|
|||
|
-- Command: riscv set_enable_virtual on|off
|
|||
|
When on, memory accesses are performed on physical or virtual
|
|||
|
memory depending on the current system configuration. When off
|
|||
|
(default), all memory accessses are performed on physical memory.
|
|||
|
|
|||
|
-- Command: riscv set_enable_virt2phys on|off
|
|||
|
When on (default), memory accesses are performed on physical or
|
|||
|
virtual memory depending on the current satp configuration. When
|
|||
|
off, all memory accessses are performed on physical memory.
|
|||
|
|
|||
|
-- Command: riscv resume_order normal|reversed
|
|||
|
Some software assumes all harts are executing nearly continuously.
|
|||
|
Such software may be sensitive to the order that harts are resumed
|
|||
|
in. On harts that don't support hasel, this option allows the user
|
|||
|
to choose the order the harts are resumed in. If you are using
|
|||
|
this option, it's probably masking a race condition problem in your
|
|||
|
code.
|
|||
|
|
|||
|
Normal order is from lowest hart index to highest. This is the
|
|||
|
default behavior. Reversed order is from highest hart index to
|
|||
|
lowest.
|
|||
|
|
|||
|
-- Command: riscv set_ir ('idcode'|'dtmcs'|'dmi') [value]
|
|||
|
Set the IR value for the specified JTAG register. This is useful,
|
|||
|
for example, when using the existing JTAG interface on a Xilinx
|
|||
|
FPGA by way of BSCANE2 primitives that only permit a limited
|
|||
|
selection of IR values.
|
|||
|
|
|||
|
When utilizing version 0.11 of the RISC-V Debug Specification,
|
|||
|
'dtmcs' and 'dmi' set the IR values for the DTMCONTROL and DBUS
|
|||
|
registers, respectively.
|
|||
|
|
|||
|
-- Command: riscv use_bscan_tunnel value
|
|||
|
Enable or disable use of a BSCAN tunnel to reach the Debug Module.
|
|||
|
Supply the width of the DM transport TAP's instruction register to
|
|||
|
enable. Supply a value of 0 to disable.
|
|||
|
|
|||
|
This BSCAN tunnel interface is specific to SiFive IP. Anybody may
|
|||
|
implement it, but currently there is no good documentation on it.
|
|||
|
In a nutshell, this feature scans USER4 into a Xilinx TAP to select
|
|||
|
the tunnel device (assuming hardware is present and it is hooked up
|
|||
|
to the Xilinx USER4 IR) and encapsulates a tunneled scan directive
|
|||
|
into a DR scan into the Xilinx TAP. A tunneled DR scan consists of:
|
|||
|
1. 1 bit that selects IR when 0, or DR when 1
|
|||
|
2. 7 bits that encode the width of the desired tunneled scan
|
|||
|
3. A width+1 stream of bits for the tunneled TDI. The plus one is
|
|||
|
because there is a one-clock skew between TDI of Xilinx chain
|
|||
|
and TDO from tunneled chain.
|
|||
|
4. 3 bits of zero that the tunnel uses to go back to idle state.
|
|||
|
|
|||
|
-- Command: riscv set_ebreakm on|off
|
|||
|
Control dcsr.ebreakm. When on (default), M-mode ebreak
|
|||
|
instructions trap to OpenOCD. When off, they generate a breakpoint
|
|||
|
exception handled internally.
|
|||
|
|
|||
|
-- Command: riscv set_ebreaks on|off
|
|||
|
Control dcsr.ebreaks. When on (default), S-mode ebreak
|
|||
|
instructions trap to OpenOCD. When off, they generate a breakpoint
|
|||
|
exception handled internally.
|
|||
|
|
|||
|
-- Command: riscv set_ebreaku on|off
|
|||
|
Control dcsr.ebreaku. When on (default), U-mode ebreak
|
|||
|
instructions trap to OpenOCD. When off, they generate a breakpoint
|
|||
|
exception handled internally.
|
|||
|
|
|||
|
16.10.4 RISC-V Authentication Commands
|
|||
|
--------------------------------------
|
|||
|
|
|||
|
The following commands can be used to authenticate to a RISC-V system.
|
|||
|
Eg. a trivial challenge-response protocol could be implemented as
|
|||
|
follows in a configuration file, immediately following 'init':
|
|||
|
set challenge [riscv authdata_read]
|
|||
|
riscv authdata_write [expr $challenge + 1]
|
|||
|
|
|||
|
-- Command: riscv authdata_read [index=0]
|
|||
|
Return the 32-bit value read from authdata or authdata0 (index=0),
|
|||
|
or authdata1 (index=1).
|
|||
|
|
|||
|
-- Command: riscv authdata_write [index=0] value
|
|||
|
Write the 32-bit value to authdata or authdata0 (index=0), or
|
|||
|
authdata1 (index=1).
|
|||
|
|
|||
|
16.10.5 RISC-V DMI Commands
|
|||
|
---------------------------
|
|||
|
|
|||
|
The following commands allow direct access to the Debug Module
|
|||
|
Interface, which can be used to interact with custom debug features.
|
|||
|
|
|||
|
-- Command: riscv dmi_read address
|
|||
|
Perform a 32-bit DMI read at address, returning the value.
|
|||
|
|
|||
|
-- Command: riscv dmi_write address value
|
|||
|
Perform a 32-bit DMI write of value at address.
|
|||
|
|
|||
|
16.11 ARC Architecture
|
|||
|
======================
|
|||
|
|
|||
|
Synopsys DesignWare ARC Processors are a family of 32-bit CPUs that SoC
|
|||
|
designers can optimize for a wide range of uses, from deeply embedded to
|
|||
|
high-performance host applications in a variety of market segments. See
|
|||
|
more at:
|
|||
|
<http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx>.
|
|||
|
OpenOCD currently supports ARC EM processors. There is a set
|
|||
|
ARC-specific OpenOCD commands that allow low-level access to the core
|
|||
|
and provide necessary support for ARC extensibility and configurability
|
|||
|
capabilities. ARC processors has much more configuration capabilities
|
|||
|
than most of the other processors and in addition there is an extension
|
|||
|
interface that allows SoC designers to add custom registers and
|
|||
|
instructions. For the OpenOCD that mostly means that set of core and
|
|||
|
AUX registers in target will vary and is not fixed for a particular
|
|||
|
processor model. To enable extensibility several TCL commands are
|
|||
|
provided that allow to describe those optional registers in OpenOCD
|
|||
|
configuration files. Moreover those commands allow for a dynamic target
|
|||
|
features discovery.
|
|||
|
|
|||
|
16.11.1 General ARC commands
|
|||
|
----------------------------
|
|||
|
|
|||
|
-- Config Command: arc add-reg configparams
|
|||
|
|
|||
|
Add a new register to processor target. By default newly created
|
|||
|
register is marked as not existing. CONFIGPARAMS must have
|
|||
|
following required arguments:
|
|||
|
|
|||
|
* '-name' name
|
|||
|
Name of a register.
|
|||
|
|
|||
|
* '-num' number
|
|||
|
Architectural register number: core register number or AUX
|
|||
|
register number.
|
|||
|
|
|||
|
* '-feature' XML_feature
|
|||
|
Name of GDB XML target description feature.
|
|||
|
|
|||
|
CONFIGPARAMS may have following optional arguments:
|
|||
|
|
|||
|
* '-gdbnum' number
|
|||
|
GDB register number. It is recommended to not assign GDB
|
|||
|
register number manually, because there would be a risk that
|
|||
|
two register will have same number. When register GDB number
|
|||
|
is not set with this option, then register will get a previous
|
|||
|
register number + 1. This option is required only for those
|
|||
|
registers that must be at particular address expected by GDB.
|
|||
|
|
|||
|
* '-core'
|
|||
|
This option specifies that register is a core registers. If
|
|||
|
not - this is an AUX register. AUX registers and core
|
|||
|
registers reside in different address spaces.
|
|||
|
|
|||
|
* '-bcr'
|
|||
|
This options specifies that register is a BCR register. BCR
|
|||
|
means Build Configuration Registers - this is a special type
|
|||
|
of AUX registers that are read only and non-volatile, that is
|
|||
|
- they never change their value. Therefore OpenOCD never
|
|||
|
invalidates values of those registers in internal caches.
|
|||
|
Because BCR is a type of AUX registers, this option cannot be
|
|||
|
used with '-core'.
|
|||
|
|
|||
|
* '-type' type_name
|
|||
|
Name of type of this register. This can be either one of the
|
|||
|
basic GDB types, or a custom types described with 'arc
|
|||
|
add-reg-type-[flags|struct]'.
|
|||
|
|
|||
|
* '-g'
|
|||
|
If specified then this is a "general" register. General
|
|||
|
registers are always read by OpenOCD on context save (when
|
|||
|
core has just been halted) and is always transferred to GDB
|
|||
|
client in a response to g-packet. Contrary to this,
|
|||
|
non-general registers are read and sent to GDB client
|
|||
|
on-demand. In general it is not recommended to apply this
|
|||
|
option to custom registers.
|
|||
|
|
|||
|
-- Config Command: arc add-reg-type-flags -name name flags...
|
|||
|
Adds new register type of "flags" class. "Flags" types can contain
|
|||
|
only one-bit fields. Each flag definition looks like '-flag name
|
|||
|
bit-position'.
|
|||
|
|
|||
|
-- Config Command: arc add-reg-type-struct -name name structs...
|
|||
|
Adds new register type of "struct" class. "Struct" types can
|
|||
|
contain either bit-fields or fields of other types, however at the
|
|||
|
moment only bit fields are supported. Structure bit field
|
|||
|
definition looks like '-bitfield name startbit endbit'.
|
|||
|
|
|||
|
-- Command: arc get-reg-field reg-name field-name
|
|||
|
Returns value of bit-field in a register. Register must be
|
|||
|
"struct" register type, *Note add-reg-type-struct::. command
|
|||
|
definition.
|
|||
|
|
|||
|
-- Command: arc set-reg-exists reg-names...
|
|||
|
Specify that some register exists. Any amount of names can be
|
|||
|
passed as an argument for a single command invocation.
|
|||
|
|
|||
|
16.11.2 ARC JTAG commands
|
|||
|
-------------------------
|
|||
|
|
|||
|
-- Command: arc jtag set-aux-reg regnum value
|
|||
|
This command writes value to AUX register via its number. This
|
|||
|
command access register in target directly via JTAG, bypassing any
|
|||
|
OpenOCD internal caches, therefore it is unsafe to use if that
|
|||
|
register can be operated by other means.
|
|||
|
|
|||
|
-- Command: arc jtag set-core-reg regnum value
|
|||
|
This command is similar to 'arc jtag set-aux-reg' but is for core
|
|||
|
registers.
|
|||
|
|
|||
|
-- Command: arc jtag get-aux-reg regnum
|
|||
|
This command returns the value storded in AUX register via its
|
|||
|
number. This commands access register in target directly via JTAG,
|
|||
|
bypassing any OpenOCD internal caches, therefore it is unsafe to
|
|||
|
use if that register can be operated by other means.
|
|||
|
|
|||
|
-- Command: arc jtag get-core-reg regnum
|
|||
|
This command is similar to 'arc jtag get-aux-reg' but is for core
|
|||
|
registers.
|
|||
|
|
|||
|
16.12 STM8 Architecture
|
|||
|
=======================
|
|||
|
|
|||
|
STM8 (http://st.com/stm8/) is a 8-bit microcontroller platform from
|
|||
|
STMicroelectronics, based on a proprietary 8-bit core architecture.
|
|||
|
|
|||
|
OpenOCD supports debugging STM8 through the STMicroelectronics debug
|
|||
|
protocol SWIM, *note SWIM: swimtransport.
|
|||
|
|
|||
|
16.13 Software Debug Messages and Tracing
|
|||
|
=========================================
|
|||
|
|
|||
|
OpenOCD can process certain requests from target software, when the
|
|||
|
target uses appropriate libraries. The most powerful mechanism is
|
|||
|
semihosting, but there is also a lighter weight mechanism using only the
|
|||
|
DCC channel.
|
|||
|
|
|||
|
Currently 'target_request debugmsgs' is supported only for 'arm7_9' and
|
|||
|
'cortex_m' cores. These messages are received as part of target
|
|||
|
polling, so you need to have 'poll on' active to receive them. They are
|
|||
|
intrusive in that they will affect program execution times. If that is
|
|||
|
a problem, *note ARM Hardware Tracing: armhardwaretracing.
|
|||
|
|
|||
|
See 'libdcc' in the contrib dir for more details. In addition to
|
|||
|
sending strings, characters, and arrays of various size integers from
|
|||
|
the target, 'libdcc' also exports a software trace point mechanism. The
|
|||
|
target being debugged may issue trace messages which include a 24-bit
|
|||
|
"trace point" number. Trace point support includes two distinct
|
|||
|
mechanisms, each supported by a command:
|
|||
|
|
|||
|
* _History_ ... A circular buffer of trace points can be set up, and
|
|||
|
then displayed at any time. This tracks where code has been, which
|
|||
|
can be invaluable in finding out how some fault was triggered.
|
|||
|
|
|||
|
The buffer may overflow, since it collects records continuously.
|
|||
|
It may be useful to use some of the 24 bits to represent a
|
|||
|
particular event, and other bits to hold data.
|
|||
|
|
|||
|
* _Counting_ ... An array of counters can be set up, and then
|
|||
|
displayed at any time. This can help establish code coverage and
|
|||
|
identify hot spots.
|
|||
|
|
|||
|
The array of counters is directly indexed by the trace point
|
|||
|
number, so trace points with higher numbers are not counted.
|
|||
|
|
|||
|
Linux-ARM kernels have a "Kernel low-level debugging via EmbeddedICE DCC
|
|||
|
channel" option (CONFIG_DEBUG_ICEDCC, depends on CONFIG_DEBUG_LL) which
|
|||
|
uses this mechanism to deliver messages before a serial console can be
|
|||
|
activated. This is not the same format used by 'libdcc'. Other
|
|||
|
software, such as the U-Boot boot loader, sometimes does the same thing.
|
|||
|
|
|||
|
-- Command: target_request debugmsgs ['enable'|'disable'|'charmsg']
|
|||
|
Displays current handling of target DCC message requests. These
|
|||
|
messages may be sent to the debugger while the target is running.
|
|||
|
The optional 'enable' and 'charmsg' parameters both enable the
|
|||
|
messages, while 'disable' disables them.
|
|||
|
|
|||
|
With 'charmsg' the DCC words each contain one character, as used by
|
|||
|
Linux with CONFIG_DEBUG_ICEDCC; otherwise the libdcc format is
|
|||
|
used.
|
|||
|
|
|||
|
-- Command: trace history ['clear'|count]
|
|||
|
With no parameter, displays all the trace points that have
|
|||
|
triggered in the order they triggered. With the parameter 'clear',
|
|||
|
erases all current trace history records. With a COUNT parameter,
|
|||
|
allocates space for that many history records.
|
|||
|
|
|||
|
-- Command: trace point ['clear'|identifier]
|
|||
|
With no parameter, displays all trace point identifiers and how
|
|||
|
many times they have been triggered. With the parameter 'clear',
|
|||
|
erases all current trace point counters. With a numeric IDENTIFIER
|
|||
|
parameter, creates a new a trace point counter and associates it
|
|||
|
with that identifier.
|
|||
|
|
|||
|
_Important:_ The identifier and the trace point number are not
|
|||
|
related except by this command. These trace point numbers always
|
|||
|
start at zero (from server startup, or after 'trace point clear')
|
|||
|
and count up from there.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: JTAG Commands, Next: Boundary Scan Commands, Prev: Architecture and Core Commands, Up: Top
|
|||
|
|
|||
|
17 JTAG Commands
|
|||
|
****************
|
|||
|
|
|||
|
Most general purpose JTAG commands have been presented earlier. (*Note
|
|||
|
JTAG Speed: jtagspeed, *note Reset Configuration::, and *note TAP
|
|||
|
Declaration::.) Lower level JTAG commands, as presented here, may be
|
|||
|
needed to work with targets which require special attention during
|
|||
|
operations such as reset or initialization.
|
|||
|
|
|||
|
To use these commands you will need to understand some of the basics of
|
|||
|
JTAG, including:
|
|||
|
|
|||
|
* A JTAG scan chain consists of a sequence of individual TAP devices
|
|||
|
such as a CPUs.
|
|||
|
* Control operations involve moving each TAP through the same
|
|||
|
standard state machine (in parallel) using their shared TMS and
|
|||
|
clock signals.
|
|||
|
* Data transfer involves shifting data through the chain of
|
|||
|
instruction or data registers of each TAP, writing new register
|
|||
|
values while the reading previous ones.
|
|||
|
* Data register sizes are a function of the instruction active in a
|
|||
|
given TAP, while instruction register sizes are fixed for each TAP.
|
|||
|
All TAPs support a BYPASS instruction with a single bit data
|
|||
|
register.
|
|||
|
* The way OpenOCD differentiates between TAP devices is by shifting
|
|||
|
different instructions into (and out of) their instruction
|
|||
|
registers.
|
|||
|
|
|||
|
17.1 Low Level JTAG Commands
|
|||
|
============================
|
|||
|
|
|||
|
These commands are used by developers who need to access JTAG
|
|||
|
instruction or data registers, possibly controlling the order of TAP
|
|||
|
state transitions. If you're not debugging OpenOCD internals, or
|
|||
|
bringing up a new JTAG adapter or a new type of TAP device (like a CPU
|
|||
|
or JTAG router), you probably won't need to use these commands. In a
|
|||
|
debug session that doesn't use JTAG for its transport protocol, these
|
|||
|
commands are not available.
|
|||
|
|
|||
|
-- Command: drscan tap [numbits value]+ ['-endstate' tap_state]
|
|||
|
Loads the data register of TAP with a series of bit fields that
|
|||
|
specify the entire register. Each field is NUMBITS bits long with
|
|||
|
a numeric VALUE (hexadecimal encouraged). The return value holds
|
|||
|
the original value of each of those fields.
|
|||
|
|
|||
|
For example, a 38 bit number might be specified as one field of 32
|
|||
|
bits then one of 6 bits. _For portability, never pass fields which
|
|||
|
are more than 32 bits long. Many OpenOCD implementations do not
|
|||
|
support 64-bit (or larger) integer values._
|
|||
|
|
|||
|
All TAPs other than TAP must be in BYPASS mode. The single bit in
|
|||
|
their data registers does not matter.
|
|||
|
|
|||
|
When TAP_STATE is specified, the JTAG state machine is left in that
|
|||
|
state. For example DRPAUSE might be specified, so that more
|
|||
|
instructions can be issued before re-entering the RUN/IDLE state.
|
|||
|
If the end state is not specified, the RUN/IDLE state is entered.
|
|||
|
|
|||
|
Warning: OpenOCD does not record information about data
|
|||
|
register lengths, so _it is important that you get the bit
|
|||
|
field lengths right_. Remember that different JTAG
|
|||
|
instructions refer to different data registers, which may have
|
|||
|
different lengths. Moreover, those lengths may not be fixed;
|
|||
|
the SCAN_N instruction can change the length of the register
|
|||
|
accessed by the INTEST instruction (by connecting a different
|
|||
|
scan chain).
|
|||
|
|
|||
|
-- Command: flush_count
|
|||
|
Returns the number of times the JTAG queue has been flushed. This
|
|||
|
may be used for performance tuning.
|
|||
|
|
|||
|
For example, flushing a queue over USB involves a minimum latency,
|
|||
|
often several milliseconds, which does not change with the amount
|
|||
|
of data which is written. You may be able to identify performance
|
|||
|
problems by finding tasks which waste bandwidth by flushing small
|
|||
|
transfers too often, instead of batching them into larger
|
|||
|
operations.
|
|||
|
|
|||
|
-- Command: irscan [tap instruction]+ ['-endstate' tap_state]
|
|||
|
For each TAP listed, loads the instruction register with its
|
|||
|
associated numeric INSTRUCTION. (The number of bits in that
|
|||
|
instruction may be displayed using the 'scan_chain' command.) For
|
|||
|
other TAPs, a BYPASS instruction is loaded.
|
|||
|
|
|||
|
When TAP_STATE is specified, the JTAG state machine is left in that
|
|||
|
state. For example IRPAUSE might be specified, so the data
|
|||
|
register can be loaded before re-entering the RUN/IDLE state. If
|
|||
|
the end state is not specified, the RUN/IDLE state is entered.
|
|||
|
|
|||
|
Note: OpenOCD currently supports only a single field for
|
|||
|
instruction register values, unlike data register values. For
|
|||
|
TAPs where the instruction register length is more than 32
|
|||
|
bits, portable scripts currently must issue only BYPASS
|
|||
|
instructions.
|
|||
|
|
|||
|
-- Command: pathmove start_state [next_state ...]
|
|||
|
Start by moving to START_STATE, which must be one of the _stable_
|
|||
|
states. Unless it is the only state given, this will often be the
|
|||
|
current state, so that no TCK transitions are needed. Then, in a
|
|||
|
series of single state transitions (conforming to the JTAG state
|
|||
|
machine) shift to each NEXT_STATE in sequence, one per TCK cycle.
|
|||
|
The final state must also be stable.
|
|||
|
|
|||
|
-- Command: runtest NUM_CYCLES
|
|||
|
Move to the RUN/IDLE state, and execute at least NUM_CYCLES of the
|
|||
|
JTAG clock (TCK). Instructions often need some time to execute
|
|||
|
before they take effect.
|
|||
|
|
|||
|
-- Command: verify_ircapture ('enable'|'disable')
|
|||
|
Verify values captured during IRCAPTURE and returned during IR
|
|||
|
scans. Default is enabled, but this can be overridden by
|
|||
|
'verify_jtag'. This flag is ignored when validating JTAG chain
|
|||
|
configuration.
|
|||
|
|
|||
|
-- Command: verify_jtag ('enable'|'disable')
|
|||
|
Enables verification of DR and IR scans, to help detect programming
|
|||
|
errors. For IR scans, 'verify_ircapture' must also be enabled.
|
|||
|
Default is enabled.
|
|||
|
|
|||
|
17.2 TAP state names
|
|||
|
====================
|
|||
|
|
|||
|
The TAP_STATE names used by OpenOCD in the 'drscan', 'irscan', and
|
|||
|
'pathmove' commands are the same as those used in SVF boundary scan
|
|||
|
documents, except that SVF uses IDLE instead of RUN/IDLE.
|
|||
|
|
|||
|
* RESET ... _stable_ (with TMS high); acts as if TRST were pulsed
|
|||
|
* RUN/IDLE ... _stable_; don't assume this always means IDLE
|
|||
|
* DRSELECT
|
|||
|
* DRCAPTURE
|
|||
|
* DRSHIFT ... _stable_; TDI/TDO shifting through the data register
|
|||
|
* DREXIT1
|
|||
|
* DRPAUSE ... _stable_; data register ready for update or more
|
|||
|
shifting
|
|||
|
* DREXIT2
|
|||
|
* DRUPDATE
|
|||
|
* IRSELECT
|
|||
|
* IRCAPTURE
|
|||
|
* IRSHIFT ... _stable_; TDI/TDO shifting through the instruction
|
|||
|
register
|
|||
|
* IREXIT1
|
|||
|
* IRPAUSE ... _stable_; instruction register ready for update or
|
|||
|
more shifting
|
|||
|
* IREXIT2
|
|||
|
* IRUPDATE
|
|||
|
|
|||
|
Note that only six of those states are fully "stable" in the face of TMS
|
|||
|
fixed (low except for RESET) and a free-running JTAG clock. For all the
|
|||
|
others, the next TCK transition changes to a new state.
|
|||
|
|
|||
|
* From DRSHIFT and IRSHIFT, clock transitions will produce side
|
|||
|
effects by changing register contents. The values to be latched in
|
|||
|
upcoming DRUPDATE or IRUPDATE states may not be as expected.
|
|||
|
* RUN/IDLE, DRPAUSE, and IRPAUSE are reasonable choices after
|
|||
|
'drscan' or 'irscan' commands, since they are free of JTAG side
|
|||
|
effects.
|
|||
|
* RUN/IDLE may have side effects that appear at non-JTAG levels, such
|
|||
|
as advancing the ARM9E-S instruction pipeline. Consult the
|
|||
|
documentation for the TAP(s) you are working with.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Boundary Scan Commands, Next: Utility Commands, Prev: JTAG Commands, Up: Top
|
|||
|
|
|||
|
18 Boundary Scan Commands
|
|||
|
*************************
|
|||
|
|
|||
|
One of the original purposes of JTAG was to support boundary scan based
|
|||
|
hardware testing. Although its primary focus is to support On-Chip
|
|||
|
Debugging, OpenOCD also includes some boundary scan commands.
|
|||
|
|
|||
|
18.1 SVF: Serial Vector Format
|
|||
|
==============================
|
|||
|
|
|||
|
The Serial Vector Format, better known as "SVF", is a way to represent
|
|||
|
JTAG test patterns in text files. In a debug session using JTAG for its
|
|||
|
transport protocol, OpenOCD supports running such test files.
|
|||
|
|
|||
|
-- Command: svf 'filename' ['-tap TAPNAME'] ['[-]quiet'] ['[-]nil']
|
|||
|
['[-]progress'] ['[-]ignore_error']
|
|||
|
This issues a JTAG reset (Test-Logic-Reset) and then runs the SVF
|
|||
|
script from 'filename'.
|
|||
|
|
|||
|
Arguments can be specified in any order; the optional dash doesn't
|
|||
|
affect their semantics.
|
|||
|
|
|||
|
Command options:
|
|||
|
- '-tap TAPNAME' ignore IR and DR headers and footers specified
|
|||
|
by the SVF file with HIR, TIR, HDR and TDR commands; instead,
|
|||
|
calculate them automatically according to the current JTAG
|
|||
|
chain configuration, targeting TAPNAME;
|
|||
|
- '[-]quiet' do not log every command before execution;
|
|||
|
- '[-]nil' "dry run", i.e., do not perform any operations on the
|
|||
|
real interface;
|
|||
|
- '[-]progress' enable progress indication;
|
|||
|
- '[-]ignore_error' continue execution despite TDO check errors.
|
|||
|
|
|||
|
18.2 XSVF: Xilinx Serial Vector Format
|
|||
|
======================================
|
|||
|
|
|||
|
The Xilinx Serial Vector Format, better known as "XSVF", is a binary
|
|||
|
representation of SVF which is optimized for use with Xilinx devices.
|
|||
|
In a debug session using JTAG for its transport protocol, OpenOCD
|
|||
|
supports running such test files.
|
|||
|
|
|||
|
Important: Not all XSVF commands are supported.
|
|||
|
|
|||
|
-- Command: xsvf (tapname|'plain') filename ['virt2'] ['quiet']
|
|||
|
This issues a JTAG reset (Test-Logic-Reset) and then runs the XSVF
|
|||
|
script from 'filename'. When a TAPNAME is specified, the commands
|
|||
|
are directed at that TAP. When 'virt2' is specified, the XRUNTEST
|
|||
|
command counts are interpreted as TCK cycles instead of
|
|||
|
microseconds. Unless the 'quiet' option is specified, messages are
|
|||
|
logged for comments and some retries.
|
|||
|
|
|||
|
The OpenOCD sources also include two utility scripts for working with
|
|||
|
XSVF; they are not currently installed after building the software. You
|
|||
|
may find them useful:
|
|||
|
|
|||
|
* _svf2xsvf_ ... converts SVF files into the extended XSVF syntax
|
|||
|
understood by the 'xsvf' command; see notes below.
|
|||
|
* _xsvfdump_ ... converts XSVF files into a text output format;
|
|||
|
understands the OpenOCD extensions.
|
|||
|
|
|||
|
The input format accepts a handful of non-standard extensions. These
|
|||
|
include three opcodes corresponding to SVF extensions from Lattice
|
|||
|
Semiconductor (LCOUNT, LDELAY, LDSR), and two opcodes supporting a more
|
|||
|
accurate translation of SVF (XTRST, XWAITSTATE). If _xsvfdump_ shows a
|
|||
|
file is using those opcodes, it probably will not be usable with other
|
|||
|
XSVF tools.
|
|||
|
|
|||
|
18.3 IPDBG: JTAG-Host server
|
|||
|
============================
|
|||
|
|
|||
|
IPDBG is a set of tools to debug IP-Cores. It comprises, among others,
|
|||
|
a logic analyzer and an arbitrary waveform generator. These are
|
|||
|
synthesize-able hardware descriptions of logic circuits in addition to
|
|||
|
software for control, visualization and further analysis. In a session
|
|||
|
using JTAG for its transport protocol, OpenOCD supports the function of
|
|||
|
a JTAG-Host. The JTAG-Host is needed to connect the circuit over JTAG
|
|||
|
to the control-software. For more details see <http://ipdbg.org>.
|
|||
|
|
|||
|
-- Command: ipdbg ['-start|-stop'] '-tap TAPNAME' '-hub IR_VALUE
|
|||
|
[DR_LENGTH]' ['-port NUMBER'] ['-tool NUMBER'] ['-vir
|
|||
|
[VIR_VALUE [LENGTH [INSTR_CODE]]]']
|
|||
|
Starts or stops a IPDBG JTAG-Host server. Arguments can be
|
|||
|
specified in any order.
|
|||
|
|
|||
|
Command options:
|
|||
|
* '-start|-stop' starts or stops a IPDBG JTAG-Host server
|
|||
|
(default: start).
|
|||
|
* '-tap TAPNAME' targeting the TAP TAPNAME.
|
|||
|
* '-hub IR_VALUE' states that the JTAG hub is reachable with
|
|||
|
dr-scans while the JTAG instruction register has the value
|
|||
|
IR_VALUE.
|
|||
|
* '-port NUMBER' tcp port number where the JTAG-Host is
|
|||
|
listening.
|
|||
|
* '-tool NUMBER' number of the tool/feature. These corresponds
|
|||
|
to the ports "data_(up/down)_(0..6)" at the JtagHub.
|
|||
|
* '-vir [VIR_VALUE [LENGTH [INSTR_CODE]]]' On some devices, the
|
|||
|
user data-register is only reachable if there is a specific
|
|||
|
value in a second dr. This second dr is called vir (virtual
|
|||
|
ir). With this parameter given, the IPDBG satisfies this
|
|||
|
condition prior an access to the IPDBG-Hub. The value shifted
|
|||
|
into the vir is given by the first parameter VIR_VALUE
|
|||
|
(default: 0x11). The second parameter LENGTH is the length of
|
|||
|
the vir data register (default: 5). With the INSTR_CODE
|
|||
|
(default: 0x00e) parameter the ir value to shift data through
|
|||
|
vir can be configured.
|
|||
|
|
|||
|
Examples:
|
|||
|
ipdbg -start -tap xc6s.tap -hub 0x02 -port 4242 -tool 4
|
|||
|
Starts a server listening on tcp-port 4242 which connects to tool 4.
|
|||
|
The connection is through the TAP of a Xilinx Spartan 6 on USER1
|
|||
|
instruction (tested with a papillion pro board).
|
|||
|
|
|||
|
ipdbg -start -tap 10m50.tap -hub 0x00C -vir -port 60000 -tool 1
|
|||
|
Starts a server listening on tcp-port 60000 which connects to tool 1
|
|||
|
(data_up_1/data_down_1). The connection is through the TAP of a Intel
|
|||
|
MAX10 virtual jtag component (sld_instance_index is 0; sld_ir_width is
|
|||
|
smaller than 5).
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Utility Commands, Next: GDB and OpenOCD, Prev: Boundary Scan Commands, Up: Top
|
|||
|
|
|||
|
19 Utility Commands
|
|||
|
*******************
|
|||
|
|
|||
|
19.1 RAM testing
|
|||
|
================
|
|||
|
|
|||
|
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 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;
|
|||
|
consult your SoC's documentation to get the recommended list of register
|
|||
|
operations and translate them to the corresponding 'mww'/'mwb' commands.
|
|||
|
|
|||
|
Load the memory testing functions with
|
|||
|
|
|||
|
source [find tools/memtest.tcl]
|
|||
|
|
|||
|
to get access to the following facilities:
|
|||
|
|
|||
|
-- Command: memTestDataBus address
|
|||
|
Test the data bus wiring in a memory region by performing a walking
|
|||
|
1's test at a fixed address within that region.
|
|||
|
|
|||
|
-- Command: memTestAddressBus baseaddress size
|
|||
|
Perform a walking 1's test on the relevant bits of the address and
|
|||
|
check for aliasing. This test will find single-bit address
|
|||
|
failures such as stuck-high, stuck-low, and shorted pins.
|
|||
|
|
|||
|
-- Command: memTestDevice baseaddress size
|
|||
|
Test the integrity of a physical memory device by performing an
|
|||
|
increment/decrement test over the entire region. In the process
|
|||
|
every storage bit in the device is tested as zero and as one.
|
|||
|
|
|||
|
-- Command: runAllMemTests baseaddress size
|
|||
|
Run all of the above tests over a specified memory region.
|
|||
|
|
|||
|
19.2 Firmware recovery helpers
|
|||
|
==============================
|
|||
|
|
|||
|
OpenOCD includes an easy-to-use script to facilitate mass-market devices
|
|||
|
recovery with JTAG.
|
|||
|
|
|||
|
For quickstart instructions run:
|
|||
|
openocd -f tools/firmware-recovery.tcl -c firmware_help
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: GDB and OpenOCD, Next: Tcl Scripting API, Prev: Utility Commands, Up: Top
|
|||
|
|
|||
|
20 GDB and OpenOCD
|
|||
|
******************
|
|||
|
|
|||
|
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:
|
|||
|
|
|||
|
* The OpenOCD server support for GDB may need to be configured.
|
|||
|
*Note GDB Configuration: gdbconfiguration.
|
|||
|
* GDB's support for OpenOCD may need configuration, as shown in this
|
|||
|
chapter.
|
|||
|
* If you have a GUI environment like Eclipse, that also will probably
|
|||
|
need to be configured.
|
|||
|
|
|||
|
Of course, the version of GDB you use will need to be one which has been
|
|||
|
built to know about the target CPU you're using. It's probably part of
|
|||
|
the tool chain you're using. For example, if you are doing
|
|||
|
cross-development for ARM on an x86 PC, instead of using the native x86
|
|||
|
'gdb' command you might use 'arm-none-eabi-gdb' if that's the tool chain
|
|||
|
used to compile your code.
|
|||
|
|
|||
|
20.1 Connecting to GDB
|
|||
|
======================
|
|||
|
|
|||
|
Use GDB 6.7 or newer with OpenOCD if you run into trouble. For instance
|
|||
|
GDB 6.3 has a known bug that produces bogus memory access errors, which
|
|||
|
has since been fixed; see
|
|||
|
<http://osdir.com/ml/gdb.bugs.discuss/2004-12/msg00018.html>
|
|||
|
|
|||
|
OpenOCD can communicate with GDB in two ways:
|
|||
|
|
|||
|
1. A socket (TCP/IP) connection is typically started as follows:
|
|||
|
target extended-remote localhost:3333
|
|||
|
This would cause GDB to connect to the gdbserver on the local pc
|
|||
|
using port 3333.
|
|||
|
|
|||
|
The extended remote protocol is a super-set of the remote protocol
|
|||
|
and should be the preferred choice. More details are available in
|
|||
|
GDB documentation
|
|||
|
<https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html>
|
|||
|
|
|||
|
To speed-up typing, any GDB command can be abbreviated, including
|
|||
|
the extended remote command above that becomes:
|
|||
|
tar ext :3333
|
|||
|
|
|||
|
Note: If any backward compatibility issue requires using the old
|
|||
|
remote protocol in place of the extended remote one, the former
|
|||
|
protocol is still available through the command:
|
|||
|
target remote localhost:3333
|
|||
|
|
|||
|
2. A pipe connection is typically started as follows:
|
|||
|
target extended-remote | \
|
|||
|
openocd -c "gdb_port pipe; log_output openocd.log"
|
|||
|
This would cause GDB to run OpenOCD and communicate using pipes
|
|||
|
(stdin/stdout). Using this method has the advantage of GDB
|
|||
|
starting/stopping OpenOCD for the debug session. log_output sends
|
|||
|
the log output to a file to ensure that the pipe is not saturated
|
|||
|
when using higher debug level outputs.
|
|||
|
|
|||
|
To list the available OpenOCD commands type 'monitor help' on the GDB
|
|||
|
command line.
|
|||
|
|
|||
|
20.2 Sample GDB session startup
|
|||
|
===============================
|
|||
|
|
|||
|
With the remote protocol, GDB sessions start a little differently than
|
|||
|
they do when you're debugging locally. 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.
|
|||
|
|
|||
|
$ arm-none-eabi-gdb example.elf
|
|||
|
(gdb) target extended-remote localhost:3333
|
|||
|
Remote debugging using localhost:3333
|
|||
|
...
|
|||
|
(gdb) monitor reset halt
|
|||
|
...
|
|||
|
(gdb) load
|
|||
|
Loading section .vectors, size 0x100 lma 0x20000000
|
|||
|
Loading section .text, size 0x5a0 lma 0x20000100
|
|||
|
Loading section .data, size 0x18 lma 0x200006a0
|
|||
|
Start address 0x2000061c, load size 1720
|
|||
|
Transfer rate: 22 KB/sec, 573 bytes/write.
|
|||
|
(gdb) continue
|
|||
|
Continuing.
|
|||
|
...
|
|||
|
|
|||
|
You could then interrupt the GDB session to make the program break, type
|
|||
|
'where' to show the stack, 'list' to show the code around the program
|
|||
|
counter, 'step' through code, set breakpoints or watchpoints, and so on.
|
|||
|
|
|||
|
20.3 Configuring GDB for OpenOCD
|
|||
|
================================
|
|||
|
|
|||
|
OpenOCD supports the gdb 'qSupported' packet, this enables information
|
|||
|
to be sent by the GDB remote server (i.e. OpenOCD) to GDB. Typical
|
|||
|
information includes packet size and the device's memory map. You do
|
|||
|
not need to configure the packet size by hand, and the relevant parts of
|
|||
|
the memory map should be automatically set up when you declare (NOR)
|
|||
|
flash banks.
|
|||
|
|
|||
|
However, there are other things which GDB can't currently query. You
|
|||
|
may need to set those up by hand. As OpenOCD starts up, you will often
|
|||
|
see a line reporting something like:
|
|||
|
|
|||
|
Info : lm3s.cpu: hardware has 6 breakpoints, 4 watchpoints
|
|||
|
|
|||
|
You can pass that information to GDB with these commands:
|
|||
|
|
|||
|
set remote hardware-breakpoint-limit 6
|
|||
|
set remote hardware-watchpoint-limit 4
|
|||
|
|
|||
|
With that particular hardware (Cortex-M3) the hardware breakpoints only
|
|||
|
work for code running from flash memory. Most other ARM systems do not
|
|||
|
have such restrictions.
|
|||
|
|
|||
|
Rather than typing such commands interactively, you may prefer to save
|
|||
|
them in a file and have GDB execute them as it starts, perhaps using a
|
|||
|
'.gdbinit' in your project directory or starting GDB using 'gdb -x
|
|||
|
filename'.
|
|||
|
|
|||
|
20.4 Programming using GDB
|
|||
|
==========================
|
|||
|
|
|||
|
By default the target memory map is sent to GDB. This can be disabled by
|
|||
|
the following OpenOCD configuration option:
|
|||
|
gdb_memory_map disable
|
|||
|
For this to function correctly a valid flash configuration must also be
|
|||
|
set 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 flash areas of the target and use hardware breakpoints by default.
|
|||
|
This means that the OpenOCD option 'gdb_breakpoint_override' is not
|
|||
|
required when using a memory map. *Note gdb_breakpoint_override:
|
|||
|
gdbbreakpointoverride.
|
|||
|
|
|||
|
To view the configured memory map in GDB, use the GDB command '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. This can be changed to the old behaviour by using the
|
|||
|
following GDB command
|
|||
|
set mem inaccessible-by-default off
|
|||
|
|
|||
|
If 'gdb_flash_program enable' is also used, GDB will be able to program
|
|||
|
any flash memory using the vFlash interface.
|
|||
|
|
|||
|
GDB will look at the target memory map when a load command is given, if
|
|||
|
any areas to be programmed lie within the target flash area the vFlash
|
|||
|
packets will be used.
|
|||
|
|
|||
|
If the target needs configuring before GDB programming, set target event
|
|||
|
gdb-flash-erase-start:
|
|||
|
$_TARGETNAME configure -event gdb-flash-erase-start BODY
|
|||
|
*Note Target Events: targetevents, for other GDB programming related
|
|||
|
events.
|
|||
|
|
|||
|
To verify any flash programming the GDB command 'compare-sections' can
|
|||
|
be used.
|
|||
|
|
|||
|
20.5 Using GDB as a non-intrusive memory inspector
|
|||
|
==================================================
|
|||
|
|
|||
|
If your project controls more than a blinking LED, let's say a heavy
|
|||
|
industrial robot or an experimental nuclear reactor, stopping the
|
|||
|
controlling process just because you want to attach GDB is not a good
|
|||
|
option.
|
|||
|
|
|||
|
OpenOCD does not support GDB non-stop mode (might be implemented in the
|
|||
|
future). Though there is a possible setup where the target does not get
|
|||
|
stopped and GDB treats it as it were running. If the target supports
|
|||
|
background access to memory while it is running, you can use GDB in this
|
|||
|
mode to inspect memory (mainly global variables) without any intrusion
|
|||
|
of the target process.
|
|||
|
|
|||
|
Remove default setting of gdb-attach event. *Note Target Events:
|
|||
|
targetevents. Place following command after target configuration:
|
|||
|
$_TARGETNAME configure -event gdb-attach {}
|
|||
|
|
|||
|
If any of installed flash banks does not support probe on running
|
|||
|
target, switch off gdb_memory_map:
|
|||
|
gdb_memory_map disable
|
|||
|
|
|||
|
Ensure GDB is configured without interrupt-on-connect. Some GDB
|
|||
|
versions set it by default, some does not.
|
|||
|
set remote interrupt-on-connect off
|
|||
|
|
|||
|
If you switched gdb_memory_map off, you may want to setup GDB memory map
|
|||
|
manually or issue 'set mem inaccessible-by-default off'
|
|||
|
|
|||
|
Now you can issue GDB command 'target extended-remote ...' and inspect
|
|||
|
memory of a running target. Do not use GDB commands 'continue', 'step'
|
|||
|
or 'next' as they synchronize GDB with your target and GDB would require
|
|||
|
stopping the target to get the prompt back.
|
|||
|
|
|||
|
Do not use this mode under an IDE like Eclipse as it caches values of
|
|||
|
previously shown variables.
|
|||
|
|
|||
|
It's also possible to connect more than one GDB to the same target by
|
|||
|
the target's configuration option '-gdb-max-connections'. This allows,
|
|||
|
for example, one GDB to run a script that continuously polls a set of
|
|||
|
variables while other GDB can be used interactively. Be extremely
|
|||
|
careful in this case, because the two GDB can easily get out-of-sync.
|
|||
|
|
|||
|
20.6 RTOS Support
|
|||
|
=================
|
|||
|
|
|||
|
OpenOCD includes RTOS support, this will however need enabling as it
|
|||
|
defaults to disabled. It can be enabled by passing '-rtos' arg to the
|
|||
|
target. *Note RTOS Type: rtostype.
|
|||
|
|
|||
|
*Note Debugging Programs with Multiple Threads: (gdb)Threads, for
|
|||
|
details about relevant GDB commands.
|
|||
|
|
|||
|
|
|||
|
An example setup is below:
|
|||
|
|
|||
|
$_TARGETNAME configure -rtos auto
|
|||
|
|
|||
|
This will attempt to auto detect the RTOS within your application.
|
|||
|
|
|||
|
Currently supported rtos's include:
|
|||
|
* 'eCos'
|
|||
|
* 'ThreadX'
|
|||
|
* 'FreeRTOS'
|
|||
|
* 'linux'
|
|||
|
* 'ChibiOS'
|
|||
|
* 'embKernel'
|
|||
|
* 'mqx'
|
|||
|
* 'uCOS-III'
|
|||
|
* 'nuttx'
|
|||
|
* 'RIOT'
|
|||
|
* 'hwthread' (This is not an actual RTOS. *Note Using OpenOCD SMP
|
|||
|
with GDB: usingopenocdsmpwithgdb.)
|
|||
|
* 'Zephyr'
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
'eCos symbols'
|
|||
|
Cyg_Thread::thread_list, Cyg_Scheduler_Base::current_thread.
|
|||
|
'ThreadX symbols'
|
|||
|
_tx_thread_current_ptr, _tx_thread_created_ptr,
|
|||
|
_tx_thread_created_count.
|
|||
|
'FreeRTOS symbols'
|
|||
|
pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1,
|
|||
|
xDelayedTaskList2, pxDelayedTaskList, pxOverflowDelayedTaskList,
|
|||
|
xPendingReadyList, uxCurrentNumberOfTasks, uxTopUsedPriority.
|
|||
|
'linux symbols'
|
|||
|
init_task.
|
|||
|
'ChibiOS symbols'
|
|||
|
rlist, ch_debug, chSysInit.
|
|||
|
'embKernel symbols'
|
|||
|
Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep,
|
|||
|
Rtos::sListSuspended, Rtos::sMaxPriorities,
|
|||
|
Rtos::sCurrentTaskCount.
|
|||
|
'mqx symbols'
|
|||
|
_mqx_kernel_data, MQX_init_struct.
|
|||
|
'uC/OS-III symbols'
|
|||
|
OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty.
|
|||
|
'nuttx symbols'
|
|||
|
g_readytorun, g_tasklisttable.
|
|||
|
'RIOT symbols'
|
|||
|
sched_threads, sched_num_threads, sched_active_pid, max_threads,
|
|||
|
_tcb_name_offset.
|
|||
|
'Zephyr symbols'
|
|||
|
_kernel, _kernel_openocd_offsets, _kernel_openocd_size_t_size
|
|||
|
|
|||
|
For most RTOS supported the above symbols will be exported by default.
|
|||
|
However for some, eg. FreeRTOS, uC/OS-III and Zephyr, extra steps must
|
|||
|
be taken.
|
|||
|
|
|||
|
Zephyr must be compiled with the DEBUG_THREAD_INFO option. This will
|
|||
|
generate some symbols with information needed in order to build the list
|
|||
|
of threads.
|
|||
|
|
|||
|
FreeRTOS and uC/OS-III RTOSes may require additional OpenOCD-specific
|
|||
|
file to be linked along with the project:
|
|||
|
|
|||
|
'FreeRTOS'
|
|||
|
contrib/rtos-helpers/FreeRTOS-openocd.c
|
|||
|
'uC/OS-III'
|
|||
|
contrib/rtos-helpers/uCOS-III-openocd.c
|
|||
|
|
|||
|
20.7 Using OpenOCD SMP with GDB
|
|||
|
===============================
|
|||
|
|
|||
|
OpenOCD includes a pseudo RTOS called _hwthread_ that presents CPU cores
|
|||
|
("hardware threads") in an SMP system as threads to GDB. With this
|
|||
|
extension, GDB can be used to inspect the state of an SMP system in a
|
|||
|
natural way. After halting the system, using the GDB command 'info
|
|||
|
threads' will list the context of each active CPU core in the system.
|
|||
|
GDB's 'thread' command can be used to switch the view to a different CPU
|
|||
|
core. The 'step' and 'stepi' commands can be used to step a specific
|
|||
|
core while other cores are free-running or remain halted, depending on
|
|||
|
the scheduler-locking mode configured in GDB.
|
|||
|
|
|||
|
20.8 Legacy SMP core switching support
|
|||
|
======================================
|
|||
|
|
|||
|
Note: This method is deprecated in favor of the _hwthread_ pseudo
|
|||
|
RTOS.
|
|||
|
|
|||
|
For SMP support following GDB serial protocol packet have been defined :
|
|||
|
* j - smp status request
|
|||
|
* J - smp set request
|
|||
|
|
|||
|
OpenOCD implements :
|
|||
|
* 'jc' packet for reading core id displayed by GDB connection. Reply
|
|||
|
is 'XXXXXXXX' (8 hex digits giving core id) or 'E01' for target not
|
|||
|
smp.
|
|||
|
* 'JcXXXXXXXX' (8 hex digits) packet for setting core id displayed at
|
|||
|
next GDB continue (core id -1 is reserved for returning to normal
|
|||
|
resume mode). Reply 'E01' for target not smp or 'OK' on success.
|
|||
|
|
|||
|
Handling of this packet within GDB can be done :
|
|||
|
* by the creation of an internal variable (i.e '_core') by mean of
|
|||
|
function allocate_computed_value allowing following GDB command.
|
|||
|
set $_core 1
|
|||
|
#Jc01 packet is sent
|
|||
|
print $_core
|
|||
|
#jc packet is sent and result is affected in $
|
|||
|
|
|||
|
* by the usage of GDB maintenance command as described in following
|
|||
|
example (2 cpus in SMP with core id 0 and 1 *note Define CPU
|
|||
|
targets working in SMP: definecputargetsworkinginsmp.).
|
|||
|
|
|||
|
# toggle0 : force display of coreid 0
|
|||
|
define toggle0
|
|||
|
maint packet Jc0
|
|||
|
continue
|
|||
|
main packet Jc-1
|
|||
|
end
|
|||
|
# toggle1 : force display of coreid 1
|
|||
|
define toggle1
|
|||
|
maint packet Jc1
|
|||
|
continue
|
|||
|
main packet Jc-1
|
|||
|
end
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Tcl Scripting API, Next: FAQ, Prev: GDB and OpenOCD, Up: Top
|
|||
|
|
|||
|
21 Tcl Scripting API
|
|||
|
********************
|
|||
|
|
|||
|
21.1 API rules
|
|||
|
==============
|
|||
|
|
|||
|
Tcl commands are stateless; e.g. the 'telnet' command has a concept of
|
|||
|
currently active target, the Tcl API proc's take this sort of state
|
|||
|
information as an argument to each proc.
|
|||
|
|
|||
|
There are three main types of return values: single value, name value
|
|||
|
pair list and lists.
|
|||
|
|
|||
|
Name value pair. The proc 'foo' below returns a name/value pair list.
|
|||
|
|
|||
|
> set foo(me) Duane
|
|||
|
> set foo(you) Oyvind
|
|||
|
> set foo(mouse) Micky
|
|||
|
> set foo(duck) Donald
|
|||
|
|
|||
|
If one does this:
|
|||
|
|
|||
|
> set foo
|
|||
|
|
|||
|
The result is:
|
|||
|
|
|||
|
me Duane you Oyvind mouse Micky duck Donald
|
|||
|
|
|||
|
Thus, to get the names of the associative array is easy:
|
|||
|
|
|||
|
foreach { name value } [set foo] {
|
|||
|
puts "Name: $name, Value: $value"
|
|||
|
}
|
|||
|
|
|||
|
Lists returned should be relatively small. Otherwise, a range should be
|
|||
|
passed in to the proc in question.
|
|||
|
|
|||
|
21.2 Internal low-level Commands
|
|||
|
================================
|
|||
|
|
|||
|
By "low-level", we mean commands that a human would typically not invoke
|
|||
|
directly.
|
|||
|
|
|||
|
* mem2array <VARNAME> <WIDTH> <ADDR> <NELEMS>
|
|||
|
|
|||
|
Read memory and return as a Tcl array for script processing
|
|||
|
* array2mem <VARNAME> <WIDTH> <ADDR> <NELEMS>
|
|||
|
|
|||
|
Convert a Tcl array to memory locations and write the values
|
|||
|
* flash banks <DRIVER> <BASE> <SIZE> <CHIP_WIDTH> <BUS_WIDTH>
|
|||
|
<TARGET> ['driver options' ...]
|
|||
|
|
|||
|
Return information about the flash banks
|
|||
|
|
|||
|
* capture <COMMAND>
|
|||
|
|
|||
|
Run <COMMAND> and return full log output that was produced during
|
|||
|
its execution. Example:
|
|||
|
|
|||
|
> capture "reset init"
|
|||
|
|
|||
|
OpenOCD commands can consist of two words, e.g. "flash banks". The
|
|||
|
'startup.tcl' "unknown" proc will translate this into a Tcl proc called
|
|||
|
"flash_banks".
|
|||
|
|
|||
|
21.3 Tcl RPC server
|
|||
|
===================
|
|||
|
|
|||
|
OpenOCD provides a simple RPC server that allows to run arbitrary Tcl
|
|||
|
commands and receive the results.
|
|||
|
|
|||
|
To access it, your application needs to connect to a configured TCP port
|
|||
|
(see 'tcl_port'). Then it can pass any string to the interpreter
|
|||
|
terminating it with '0x1a' and wait for the return value (it will be
|
|||
|
terminated with '0x1a' as well). This can be repeated as many times as
|
|||
|
desired without reopening the connection.
|
|||
|
|
|||
|
It is not needed anymore to prefix the OpenOCD commands with 'ocd_' to
|
|||
|
get the results back. But sometimes you might need the 'capture'
|
|||
|
command.
|
|||
|
|
|||
|
See 'contrib/rpc_examples/' for specific client implementations.
|
|||
|
|
|||
|
21.4 Tcl RPC server notifications
|
|||
|
=================================
|
|||
|
|
|||
|
Notifications are sent asynchronously to other commands being executed
|
|||
|
over the RPC server, so the port must be polled continuously.
|
|||
|
|
|||
|
Target event, state and reset notifications are emitted as Tcl
|
|||
|
associative arrays in the following format.
|
|||
|
|
|||
|
type target_event event [event-name]
|
|||
|
type target_state state [state-name]
|
|||
|
type target_reset mode [reset-mode]
|
|||
|
|
|||
|
-- Command: tcl_notifications [on/off]
|
|||
|
Toggle output of target notifications to the current Tcl RPC
|
|||
|
server. Only available from the Tcl RPC server. Defaults to off.
|
|||
|
|
|||
|
21.5 Tcl RPC server trace output
|
|||
|
================================
|
|||
|
|
|||
|
Trace data is sent asynchronously to other commands being executed over
|
|||
|
the RPC server, so the port must be polled continuously.
|
|||
|
|
|||
|
Target trace data is emitted as a Tcl associative array in the following
|
|||
|
format.
|
|||
|
|
|||
|
type target_trace data [trace-data-hex-encoded]
|
|||
|
|
|||
|
-- Command: tcl_trace [on/off]
|
|||
|
Toggle output of target trace data to the current Tcl RPC server.
|
|||
|
Only available from the Tcl RPC server. Defaults to off.
|
|||
|
|
|||
|
See an example application here:
|
|||
|
<https://github.com/apmorton/OpenOcdTraceUtil> [OpenOcdTraceUtil]
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: FAQ, Next: Tcl Crash Course, Prev: Tcl Scripting API, Up: Top
|
|||
|
|
|||
|
22 FAQ
|
|||
|
******
|
|||
|
|
|||
|
1. RTCK, also known as: Adaptive Clocking - What is it?
|
|||
|
|
|||
|
In digital circuit design it is often referred to as "clock
|
|||
|
synchronisation" the JTAG interface uses one clock (TCK or TCLK)
|
|||
|
operating at some speed, your CPU target is operating at another.
|
|||
|
The two clocks are not synchronised, they are "asynchronous"
|
|||
|
|
|||
|
In order for the two to work together they must be synchronised
|
|||
|
well enough to work; JTAG can't go ten times faster than the CPU,
|
|||
|
for example. There are 2 basic options:
|
|||
|
1. Use a special "adaptive clocking" circuit to change the JTAG
|
|||
|
clock rate to match what the CPU currently supports.
|
|||
|
2. The JTAG clock must be fixed at some speed that's enough
|
|||
|
slower than the CPU clock that all TMS and TDI transitions can
|
|||
|
be detected.
|
|||
|
|
|||
|
Does this really matter? For some chips and some situations, this
|
|||
|
is a non-issue, like a 500MHz ARM926 with a 5 MHz JTAG link; the
|
|||
|
CPU has no difficulty keeping up with JTAG. Startup sequences are
|
|||
|
often problematic though, as are other situations where the CPU
|
|||
|
clock rate changes (perhaps to save power).
|
|||
|
|
|||
|
For example, Atmel AT91SAM chips start operation from reset with a
|
|||
|
32kHz system clock. Boot firmware may activate the main oscillator
|
|||
|
and PLL before switching to a faster clock (perhaps that 500 MHz
|
|||
|
ARM926 scenario). If you're using JTAG to debug that startup
|
|||
|
sequence, you must slow the JTAG clock to sometimes 1 to 4kHz.
|
|||
|
After startup completes, JTAG can use a faster clock.
|
|||
|
|
|||
|
Consider also debugging a 500MHz ARM926 hand held battery powered
|
|||
|
device that enters a low power "deep sleep" mode, at 32kHz CPU
|
|||
|
clock, between keystrokes unless it has work to do. When would
|
|||
|
that 5 MHz JTAG clock be usable?
|
|||
|
|
|||
|
Solution #1 - A special circuit
|
|||
|
|
|||
|
In order to make use of this, your CPU, board, and JTAG adapter
|
|||
|
must all support the RTCK feature. Not all of them support this;
|
|||
|
keep reading!
|
|||
|
|
|||
|
The RTCK ("Return TCK") signal in some ARM chips is used to help
|
|||
|
with this problem. ARM has a good description of the problem
|
|||
|
described at this link:
|
|||
|
<http://www.arm.com/support/faqdev/4170.html> [checked
|
|||
|
28/nov/2008]. Link title: "How does the JTAG synchronisation logic
|
|||
|
work? / how does adaptive clocking work?".
|
|||
|
|
|||
|
The nice thing about adaptive clocking is that "battery powered
|
|||
|
hand held device example" - the adaptiveness works perfectly all
|
|||
|
the time. One can set a break point or halt the system in the deep
|
|||
|
power down code, slow step out until the system speeds up.
|
|||
|
|
|||
|
Note that adaptive clocking may also need to work at the board
|
|||
|
level, when a board-level scan chain has multiple chips. Parallel
|
|||
|
clock voting schemes are good way to implement this, both within
|
|||
|
and between chips, and can easily be implemented with a CPLD. It's
|
|||
|
not difficult to have logic fan a module's input TCK signal out to
|
|||
|
each TAP in the scan chain, and then wait until each TAP's RTCK
|
|||
|
comes back with the right polarity before changing the output RTCK
|
|||
|
signal. Texas Instruments makes some clock voting logic available
|
|||
|
for free (with no support) in VHDL form; see
|
|||
|
<http://tiexpressdsp.com/index.php/Adaptive_Clocking>
|
|||
|
|
|||
|
Solution #2 - Always works - but may be slower
|
|||
|
|
|||
|
Often this is a perfectly acceptable solution.
|
|||
|
|
|||
|
In most simple terms: Often the JTAG clock must be 1/10 to 1/12 of
|
|||
|
the target clock speed. But what that "magic division" is varies
|
|||
|
depending on the chips on your board. ARM rule of thumb Most ARM
|
|||
|
based systems require an 6:1 division; ARM11 cores use an 8:1
|
|||
|
division. Xilinx rule of thumb is 1/12 the clock speed.
|
|||
|
|
|||
|
Note: most full speed FT2232 based JTAG adapters are limited to a
|
|||
|
maximum of 6MHz. The ones using USB high speed chips (FT2232H)
|
|||
|
often support faster clock rates (and adaptive clocking).
|
|||
|
|
|||
|
You can still debug the 'low power' situations - you just need to
|
|||
|
either use a fixed and very slow JTAG clock rate ... or else
|
|||
|
manually adjust the clock speed at every step. (Adjusting is
|
|||
|
painful and tedious, and is not always practical.)
|
|||
|
|
|||
|
It is however easy to "code your way around it" - i.e.: Cheat a
|
|||
|
little, have a special debug mode in your application that does a
|
|||
|
"high power sleep". If you are careful - 98% of your problems can
|
|||
|
be debugged this way.
|
|||
|
|
|||
|
Note that on ARM you may need to avoid using the _wait for
|
|||
|
interrupt_ operation in your idle loops even if you don't otherwise
|
|||
|
change the CPU clock rate. That operation gates the CPU clock, and
|
|||
|
thus the JTAG clock; which prevents JTAG access. One consequence
|
|||
|
is not being able to 'halt' cores which are executing that _wait
|
|||
|
for interrupt_ operation.
|
|||
|
|
|||
|
To set the JTAG frequency use the command:
|
|||
|
|
|||
|
# Example: 1.234MHz
|
|||
|
adapter speed 1234
|
|||
|
|
|||
|
2. 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.
|
|||
|
|
|||
|
> echo \a
|
|||
|
|
|||
|
> echo {\a}
|
|||
|
\a
|
|||
|
> echo "\a"
|
|||
|
|
|||
|
>
|
|||
|
|
|||
|
3. Missing: cygwin1.dll OpenOCD complains about a missing cygwin1.dll.
|
|||
|
|
|||
|
Make sure you have Cygwin installed, or at least a version of
|
|||
|
OpenOCD that claims to come with all the necessary DLLs. When
|
|||
|
using Cygwin, try launching OpenOCD from the Cygwin shell.
|
|||
|
|
|||
|
4. Breakpoint Issue I'm trying to set a breakpoint using GDB (or a
|
|||
|
front-end like Insight or Eclipse), but OpenOCD complains that
|
|||
|
"Info: arm7_9_common.c:213 arm7_9_add_breakpoint(): sw breakpoint
|
|||
|
requested, but software breakpoints not enabled".
|
|||
|
|
|||
|
GDB issues software breakpoints when a normal breakpoint is
|
|||
|
requested, or to implement source-line single-stepping. On ARMv4T
|
|||
|
systems, like ARM7TDMI, ARM720T or ARM920T, software breakpoints
|
|||
|
consume one of the two available hardware breakpoints.
|
|||
|
|
|||
|
5. LPC2000 Flash When erasing or writing LPC2000 on-chip flash, the
|
|||
|
operation fails at random.
|
|||
|
|
|||
|
Make sure the core frequency specified in the 'flash lpc2000' line
|
|||
|
matches the clock at the time you're programming the flash. If
|
|||
|
you've specified the crystal's frequency, make sure the PLL is
|
|||
|
disabled. If you've specified the full core speed (e.g. 60MHz),
|
|||
|
make sure the PLL is enabled.
|
|||
|
|
|||
|
6. Amontec Chameleon When debugging using an Amontec Chameleon in its
|
|||
|
JTAG Accelerator configuration, I keep getting "Error:
|
|||
|
amt_jtagaccel.c:184 amt_wait_scan_busy(): amt_jtagaccel timed out
|
|||
|
while waiting for end of scan, rtck was disabled".
|
|||
|
|
|||
|
Make sure your PC's parallel port operates in EPP mode. You might
|
|||
|
have to try several settings in your PC BIOS (ECP, EPP, and
|
|||
|
different versions of those).
|
|||
|
|
|||
|
7. 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".
|
|||
|
|
|||
|
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 a proper "initial" stack frame, if you
|
|||
|
happen to know what exactly has to be done, feel free to add this
|
|||
|
here.
|
|||
|
|
|||
|
Simple: In your startup code - push 8 registers of zeros onto the
|
|||
|
stack before calling main(). What GDB is doing is "climbing" the
|
|||
|
run time stack by reading various values on the stack using the
|
|||
|
standard call frame for the target. GDB keeps going - until one of
|
|||
|
2 things happen #1 an invalid frame is found, or #2 some huge
|
|||
|
number of stackframes have been processed. By pushing zeros on the
|
|||
|
stack, GDB gracefully stops.
|
|||
|
|
|||
|
Debugging Interrupt Service Routines - In your ISR before you call
|
|||
|
your C code, do the same - artificially push some zeros onto the
|
|||
|
stack, remember to pop them off when the ISR is done.
|
|||
|
|
|||
|
Also note: If you have a multi-threaded operating system, they
|
|||
|
often do not in the interest of saving memory waste these few
|
|||
|
bytes. Painful...
|
|||
|
|
|||
|
8. JTAG Reset Config I get the following message in the OpenOCD
|
|||
|
console (or log file): "Warning: arm7_9_common.c:679
|
|||
|
arm7_9_assert_reset(): srst resets test logic, too".
|
|||
|
|
|||
|
This warning doesn't indicate any serious problem, as long as you
|
|||
|
don't want to debug your core right out of reset. Your .cfg file
|
|||
|
specified 'reset_config trst_and_srst srst_pulls_trst' to tell
|
|||
|
OpenOCD that either your board, your debugger or your target uC
|
|||
|
(e.g. LPC2000) can't assert the two reset signals independently.
|
|||
|
With this setup, it's not possible to halt the core right out of
|
|||
|
reset, everything else should work fine.
|
|||
|
|
|||
|
9. USB Power When using OpenOCD in conjunction with Amontec JTAGkey
|
|||
|
and the Yagarto toolchain (Eclipse, arm-elf-gcc, arm-elf-gdb), the
|
|||
|
debugging seems to be unstable. When single-stepping over large
|
|||
|
blocks of code, GDB and OpenOCD quit with an error message. Is
|
|||
|
there a stability issue with OpenOCD?
|
|||
|
|
|||
|
No, this is not a stability issue concerning OpenOCD. Most users
|
|||
|
have solved this issue by simply using a self-powered USB hub,
|
|||
|
which they connect their Amontec JTAGkey to. Apparently, some
|
|||
|
computers do not provide a USB power supply stable enough for the
|
|||
|
Amontec JTAGkey to be operated.
|
|||
|
|
|||
|
Laptops running on battery have this problem too...
|
|||
|
|
|||
|
10. GDB Disconnects When using the Amontec JTAGkey, sometimes OpenOCD
|
|||
|
crashes with the following error message: "Error: gdb_server.c:101
|
|||
|
gdb_get_char(): read: 10054". What does that mean and what might
|
|||
|
be the reason for this?
|
|||
|
|
|||
|
Error code 10054 corresponds to WSAECONNRESET, which means that the
|
|||
|
debugger (GDB) has closed the connection to OpenOCD. This might be
|
|||
|
a GDB issue.
|
|||
|
|
|||
|
11. LPC2000 Flash In the configuration file in the section where flash
|
|||
|
device configurations are described, there is a parameter for
|
|||
|
specifying the clock frequency for LPC2000 internal flash devices
|
|||
|
(e.g. 'flash bank $_FLASHNAME lpc2000 0x0 0x40000 0 0 $_TARGETNAME
|
|||
|
lpc2000_v1 14746 calc_checksum'), which must be specified in
|
|||
|
kilohertz. However, I do have a quartz crystal of a frequency that
|
|||
|
contains fractions of kilohertz (e.g. 14,745,600 Hz, i.e.
|
|||
|
14,745.600 kHz). Is it possible to specify real numbers for the
|
|||
|
clock frequency?
|
|||
|
|
|||
|
No. The clock frequency specified here must be given as an
|
|||
|
integral number. However, this clock frequency is used by the
|
|||
|
In-Application-Programming (IAP) routines of the LPC2000 family
|
|||
|
only, which seems to be very tolerant concerning the given clock
|
|||
|
frequency, so a slight difference between the specified clock
|
|||
|
frequency and the actual clock frequency will not cause any
|
|||
|
trouble.
|
|||
|
|
|||
|
12. Command Order Do I have to keep a specific order for the commands
|
|||
|
in the configuration file?
|
|||
|
|
|||
|
Well, yes and no. Commands can be given in arbitrary order, yet
|
|||
|
the devices listed for the JTAG scan chain must be given in the
|
|||
|
right order (jtag newdevice), with the device closest to the
|
|||
|
TDO-Pin being listed first. In general, whenever objects of the
|
|||
|
same type exist which require an index number, then these objects
|
|||
|
must be given in the right order (jtag newtap, targets and flash
|
|||
|
banks - a target references a jtag newtap and a flash bank
|
|||
|
references a target).
|
|||
|
|
|||
|
You can use the "scan_chain" command to verify and display the tap
|
|||
|
order.
|
|||
|
|
|||
|
Also, some commands can't execute until after 'init' has been
|
|||
|
processed. Such commands include 'nand probe' and everything else
|
|||
|
that needs to write to controller registers, perhaps for setting up
|
|||
|
DRAM and loading it with code.
|
|||
|
|
|||
|
13. JTAG TAP Order Do I have to declare the TAPS in some particular
|
|||
|
order?
|
|||
|
|
|||
|
Yes; whenever you have more than one, you must declare them in the
|
|||
|
same order used by the hardware.
|
|||
|
|
|||
|
Many newer devices have multiple JTAG TAPs. For example:
|
|||
|
STMicroelectronics STM32 chips have two TAPs, a "boundary scan TAP"
|
|||
|
and "Cortex-M3" TAP. Example: The STM32 reference manual, Document
|
|||
|
ID: RM0008, Section 26.5, Figure 259, page 651/681, the "TDI" pin
|
|||
|
is connected to the boundary scan TAP, which then connects to the
|
|||
|
Cortex-M3 TAP, which then connects to the TDO pin.
|
|||
|
|
|||
|
Thus, the proper order for the STM32 chip is: (1) The Cortex-M3,
|
|||
|
then (2) The boundary scan TAP. If your board includes an
|
|||
|
additional JTAG chip in the scan chain (for example a Xilinx CPLD
|
|||
|
or FPGA) you could place it before or after the STM32 chip in the
|
|||
|
chain. For example:
|
|||
|
|
|||
|
* OpenOCD_TDI(output) -> STM32 TDI Pin (BS Input)
|
|||
|
* STM32 BS TDO (output) -> STM32 Cortex-M3 TDI (input)
|
|||
|
* STM32 Cortex-M3 TDO (output) -> SM32 TDO Pin
|
|||
|
* STM32 TDO Pin (output) -> Xilinx TDI Pin (input)
|
|||
|
* Xilinx TDO Pin -> OpenOCD TDO (input)
|
|||
|
|
|||
|
The "jtag device" commands would thus be in the order shown below.
|
|||
|
Note:
|
|||
|
|
|||
|
* jtag newtap Xilinx tap -irlen ...
|
|||
|
* jtag newtap stm32 cpu -irlen ...
|
|||
|
* jtag newtap stm32 bs -irlen ...
|
|||
|
* # Create the debug target and say where it is
|
|||
|
* target create stm32.cpu -chain-position stm32.cpu ...
|
|||
|
|
|||
|
14. SYSCOMP Sometimes my debugging session terminates with an error.
|
|||
|
When I look into the log file, I can see these error messages:
|
|||
|
Error: arm7_9_common.c:561 arm7_9_execute_sys_speed(): timeout
|
|||
|
waiting for SYSCOMP
|
|||
|
|
|||
|
TODO.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: Tcl Crash Course, Next: License, Prev: FAQ, Up: Top
|
|||
|
|
|||
|
23 Tcl Crash Course
|
|||
|
*******************
|
|||
|
|
|||
|
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 how
|
|||
|
the Tcl scripts work.
|
|||
|
|
|||
|
This chapter is written with two audiences in mind. (1) OpenOCD users
|
|||
|
who need to understand a bit more of how Jim-Tcl works so they can do
|
|||
|
something useful, and (2) those that want to add a new command to
|
|||
|
OpenOCD.
|
|||
|
|
|||
|
23.1 Tcl Rule #1
|
|||
|
================
|
|||
|
|
|||
|
There is a famous joke, it goes like this:
|
|||
|
1. Rule #1: The wife is always correct
|
|||
|
2. Rule #2: If you think otherwise, See Rule #1
|
|||
|
|
|||
|
The Tcl equal is this:
|
|||
|
|
|||
|
1. Rule #1: Everything is a string
|
|||
|
2. Rule #2: If you think otherwise, See Rule #1
|
|||
|
|
|||
|
As in the famous joke, the consequences of Rule #1 are profound. Once
|
|||
|
you understand Rule #1, you will understand Tcl.
|
|||
|
|
|||
|
23.2 Tcl Rule #1b
|
|||
|
=================
|
|||
|
|
|||
|
There is a second pair of rules.
|
|||
|
1. Rule #1: Control flow does not exist. Only commands
|
|||
|
For example: the classic FOR loop or IF statement is not a control
|
|||
|
flow item, they are commands, there is no such thing as control
|
|||
|
flow in Tcl.
|
|||
|
2. Rule #2: If you think otherwise, See Rule #1
|
|||
|
Actually what happens is this: There are commands that by
|
|||
|
convention, act like control flow key words in other languages.
|
|||
|
One of those commands is the word "for", another command is "if".
|
|||
|
|
|||
|
23.3 Per Rule #1 - All Results are strings
|
|||
|
==========================================
|
|||
|
|
|||
|
Every Tcl command results in a string. The word "result" is used
|
|||
|
deliberately. No result is just an empty string. Remember: Rule #1 -
|
|||
|
Everything is a string
|
|||
|
|
|||
|
23.4 Tcl Quoting Operators
|
|||
|
==========================
|
|||
|
|
|||
|
In life of a Tcl script, there are two important periods of time, the
|
|||
|
difference is subtle.
|
|||
|
1. Parse Time
|
|||
|
2. Evaluation Time
|
|||
|
|
|||
|
The two key items here are how "quoted things" work in Tcl. Tcl has
|
|||
|
three primary quoting constructs, the [square-brackets] the
|
|||
|
{curly-braces} and "double-quotes"
|
|||
|
|
|||
|
By now you should know $VARIABLES always start with a $DOLLAR sign.
|
|||
|
BTW: To set a variable, you actually use the command "set", as in "set
|
|||
|
VARNAME VALUE" much like the ancient BASIC language "let x = 1"
|
|||
|
statement, but without the equal sign.
|
|||
|
|
|||
|
* [square-brackets]
|
|||
|
[square-brackets] are command substitutions. It operates much like
|
|||
|
Unix Shell 'back-ticks'. The result of a [square-bracket]
|
|||
|
operation is exactly 1 string. Remember Rule #1 - Everything is a
|
|||
|
string. These two statements are roughly identical:
|
|||
|
# bash example
|
|||
|
X=`date`
|
|||
|
echo "The Date is: $X"
|
|||
|
# Tcl example
|
|||
|
set X [date]
|
|||
|
puts "The Date is: $X"
|
|||
|
* "double-quoted-things"
|
|||
|
"double-quoted-things" are just simply quoted text. $VARIABLES and
|
|||
|
[square-brackets] are expanded in place - the result however is
|
|||
|
exactly 1 string. Remember Rule #1 - Everything is a string
|
|||
|
set x "Dinner"
|
|||
|
puts "It is now \"[date]\", $x is in 1 hour"
|
|||
|
* {Curly-Braces}
|
|||
|
{Curly-Braces} are magic: $VARIABLES and [square-brackets] are
|
|||
|
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 a bad example; at this
|
|||
|
writing, Jim/OpenOCD does not have a date command.
|
|||
|
|
|||
|
23.5 Consequences of Rule 1/2/3/4
|
|||
|
=================================
|
|||
|
|
|||
|
The consequences of Rule 1 are profound.
|
|||
|
|
|||
|
23.5.1 Tokenisation & Execution.
|
|||
|
--------------------------------
|
|||
|
|
|||
|
Of course, whitespace, blank lines and #comment lines are handled in the
|
|||
|
normal way.
|
|||
|
|
|||
|
As a script is parsed, each (multi) line in the script file is tokenised
|
|||
|
and according to the quoting rules. After tokenisation, that line is
|
|||
|
immediately executed.
|
|||
|
|
|||
|
Multi line statements end with one or more "still-open" {curly-braces}
|
|||
|
which - eventually - closes a few lines later.
|
|||
|
|
|||
|
23.5.2 Command Execution
|
|||
|
------------------------
|
|||
|
|
|||
|
Remember earlier: There are no "control flow" statements in Tcl.
|
|||
|
Instead there are COMMANDS that simply act like control flow operators.
|
|||
|
|
|||
|
Commands are executed like this:
|
|||
|
|
|||
|
1. Parse the next line into (argc) and (argv[]).
|
|||
|
2. Look up (argv[0]) in a table and call its function.
|
|||
|
3. Repeat until End Of File.
|
|||
|
|
|||
|
It sort of works like this:
|
|||
|
for(;;){
|
|||
|
ReadAndParse( &argc, &argv );
|
|||
|
|
|||
|
cmdPtr = LookupCommand( argv[0] );
|
|||
|
|
|||
|
(*cmdPtr->Execute)( argc, argv );
|
|||
|
}
|
|||
|
|
|||
|
When the command "proc" is parsed (which creates a procedure function)
|
|||
|
it gets 3 parameters on the command line. 1 the name of the proc
|
|||
|
(function), 2 the list of parameters, and 3 the body of the function.
|
|||
|
Not the choice of words: LIST and BODY. The PROC command stores these
|
|||
|
items in a table somewhere so it can be found by "LookupCommand()"
|
|||
|
|
|||
|
23.5.3 The FOR command
|
|||
|
----------------------
|
|||
|
|
|||
|
The most interesting command to look at is the FOR command. In Tcl, the
|
|||
|
FOR command is normally implemented in C. Remember, FOR is a command
|
|||
|
just like any other command.
|
|||
|
|
|||
|
When the ascii text containing the FOR command is parsed, the parser
|
|||
|
produces 5 parameter strings, (If in doubt: Refer to Rule #1) they are:
|
|||
|
|
|||
|
0. The ascii text 'for'
|
|||
|
1. The start text
|
|||
|
2. The test expression
|
|||
|
3. The next text
|
|||
|
4. The body text
|
|||
|
|
|||
|
Sort of reminds you of "main( int argc, char **argv )" does it not?
|
|||
|
Remember Rule #1 - Everything is a string. The key point is this: Often
|
|||
|
many of those parameters are in {curly-braces} - thus the variables
|
|||
|
inside are not expanded or replaced until later.
|
|||
|
|
|||
|
Remember that every Tcl command looks like the classic "main( argc, argv
|
|||
|
)" function in C. In JimTCL - they actually look like this:
|
|||
|
|
|||
|
int
|
|||
|
MyCommand( Jim_Interp *interp,
|
|||
|
int *argc,
|
|||
|
Jim_Obj * const *argvs );
|
|||
|
|
|||
|
Real Tcl is nearly identical. Although the newer versions have
|
|||
|
introduced a byte-code parser and interpreter, but at the core, it still
|
|||
|
operates in the same basic way.
|
|||
|
|
|||
|
23.5.4 FOR command implementation
|
|||
|
---------------------------------
|
|||
|
|
|||
|
To understand Tcl it is perhaps most helpful to see the FOR command.
|
|||
|
Remember, it is a COMMAND not a control flow structure.
|
|||
|
|
|||
|
In Tcl there are two underlying C helper functions.
|
|||
|
|
|||
|
Remember Rule #1 - You are a string.
|
|||
|
|
|||
|
The first helper parses and executes commands found in an ascii string.
|
|||
|
Commands can be separated by semicolons, or newlines. While parsing,
|
|||
|
variables are expanded via the quoting rules.
|
|||
|
|
|||
|
The second helper evaluates an ascii string as a numerical expression
|
|||
|
and returns a value.
|
|||
|
|
|||
|
Here is an example of how the FOR command could be implemented. The
|
|||
|
pseudo code below does not show error handling.
|
|||
|
void Execute_AsciiString( void *interp, const char *string );
|
|||
|
|
|||
|
int Evaluate_AsciiExpression( void *interp, const char *string );
|
|||
|
|
|||
|
int
|
|||
|
MyForCommand( void *interp,
|
|||
|
int argc,
|
|||
|
char **argv )
|
|||
|
{
|
|||
|
if( argc != 5 ){
|
|||
|
SetResult( interp, "WRONG number of parameters");
|
|||
|
return ERROR;
|
|||
|
}
|
|||
|
|
|||
|
// argv[0] = the ascii string just like C
|
|||
|
|
|||
|
// Execute the start statement.
|
|||
|
Execute_AsciiString( interp, argv[1] );
|
|||
|
|
|||
|
// Top of loop test
|
|||
|
for(;;){
|
|||
|
i = Evaluate_AsciiExpression(interp, argv[2]);
|
|||
|
if( i == 0 )
|
|||
|
break;
|
|||
|
|
|||
|
// Execute the body
|
|||
|
Execute_AsciiString( interp, argv[3] );
|
|||
|
|
|||
|
// Execute the LOOP part
|
|||
|
Execute_AsciiString( interp, argv[4] );
|
|||
|
}
|
|||
|
|
|||
|
// Return no error
|
|||
|
SetResult( interp, "" );
|
|||
|
return SUCCESS;
|
|||
|
}
|
|||
|
|
|||
|
Every other command IF, WHILE, FORMAT, PUTS, EXPR, everything works in
|
|||
|
the same basic way.
|
|||
|
|
|||
|
23.6 OpenOCD Tcl Usage
|
|||
|
======================
|
|||
|
|
|||
|
23.6.1 source and find commands
|
|||
|
-------------------------------
|
|||
|
|
|||
|
Where: In many configuration files
|
|||
|
Example: source [find FILENAME]
|
|||
|
Remember the parsing rules
|
|||
|
1. The 'find' command is in square brackets, and is executed with the
|
|||
|
parameter FILENAME. It should find and return the full path to a
|
|||
|
file with that name; it uses an internal search path. The RESULT
|
|||
|
is a string, which is substituted into the command line in place of
|
|||
|
the bracketed 'find' command. (Don't try to use a FILENAME which
|
|||
|
includes the "#" character. That character begins Tcl comments.)
|
|||
|
2. The 'source' command is executed with the resulting filename; it
|
|||
|
reads a file and executes as a script.
|
|||
|
|
|||
|
23.6.2 format command
|
|||
|
---------------------
|
|||
|
|
|||
|
Where: Generally occurs in numerous places.
|
|||
|
Tcl has no command like printf(), instead it has format, which is really
|
|||
|
more like sprintf(). Example
|
|||
|
set x 6
|
|||
|
set y 7
|
|||
|
puts [format "The answer: %d" [expr $x * $y]]
|
|||
|
1. The SET command creates 2 variables, X and Y.
|
|||
|
2. The double [nested] EXPR command performs math
|
|||
|
The EXPR command produces numerical result as a string.
|
|||
|
Refer to Rule #1
|
|||
|
3. The format command is executed, producing a single string
|
|||
|
Refer to Rule #1.
|
|||
|
4. The PUTS command outputs the text.
|
|||
|
|
|||
|
23.6.3 Body or Inlined Text
|
|||
|
---------------------------
|
|||
|
|
|||
|
Where: Various TARGET scripts.
|
|||
|
#1 Good
|
|||
|
proc someproc {} {
|
|||
|
... multiple lines of stuff ...
|
|||
|
}
|
|||
|
$_TARGETNAME configure -event FOO someproc
|
|||
|
#2 Good - no variables
|
|||
|
$_TARGETNAME configure -event foo "this ; that;"
|
|||
|
#3 Good Curly Braces
|
|||
|
$_TARGETNAME configure -event FOO {
|
|||
|
puts "Time: [date]"
|
|||
|
}
|
|||
|
#4 DANGER DANGER DANGER
|
|||
|
$_TARGETNAME configure -event foo "puts \"Time: [date]\""
|
|||
|
1. The $_TARGETNAME is an OpenOCD variable convention.
|
|||
|
$_TARGETNAME represents the last target created, the value changes
|
|||
|
each time a new target is created. Remember the parsing rules.
|
|||
|
When the ascii text is parsed, the $_TARGETNAME becomes a simple
|
|||
|
string, the name of the target which happens to be a TARGET
|
|||
|
(object) command.
|
|||
|
2. The 2nd parameter to the '-event' parameter is a TCBODY
|
|||
|
There are 4 examples:
|
|||
|
1. The TCLBODY is a simple string that happens to be a proc name
|
|||
|
2. The TCLBODY is several simple commands separated by semicolons
|
|||
|
3. The TCLBODY is a multi-line {curly-brace} quoted string
|
|||
|
4. The TCLBODY is a string with variables that get expanded.
|
|||
|
|
|||
|
In the end, when the target event FOO occurs the TCLBODY is
|
|||
|
evaluated. Method #1 and #2 are functionally identical. For
|
|||
|
Method #3 and #4 it is more interesting. What is the TCLBODY?
|
|||
|
|
|||
|
Remember the parsing rules. In case #3, {curly-braces} mean the
|
|||
|
$VARS and [square-brackets] are expanded later, when the EVENT
|
|||
|
occurs, 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 a bad example; at this writing,
|
|||
|
Jim/OpenOCD does not have a date command}
|
|||
|
|
|||
|
23.6.4 Global Variables
|
|||
|
-----------------------
|
|||
|
|
|||
|
Where: You might discover this when writing your own procs
|
|||
|
In simple terms: Inside a PROC, if you need to access a global variable
|
|||
|
you must say so. See also "upvar". Example:
|
|||
|
proc myproc { } {
|
|||
|
set y 0 #Local variable Y
|
|||
|
global x #Global variable X
|
|||
|
puts [format "X=%d, Y=%d" $x $y]
|
|||
|
}
|
|||
|
|
|||
|
23.7 Other Tcl Hacks
|
|||
|
====================
|
|||
|
|
|||
|
Dynamic variable creation
|
|||
|
# Dynamically create a bunch of variables.
|
|||
|
for { set x 0 } { $x < 32 } { set x [expr $x + 1]} {
|
|||
|
# Create var name
|
|||
|
set vn [format "BIT%d" $x]
|
|||
|
# Make it a global
|
|||
|
global $vn
|
|||
|
# Set it.
|
|||
|
set $vn [expr (1 << $x)]
|
|||
|
}
|
|||
|
Dynamic proc/command creation
|
|||
|
# One "X" function - 5 uart functions.
|
|||
|
foreach who {A B C D E}
|
|||
|
proc [format "show_uart%c" $who] { } "show_UARTx $who"
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: License, Next: OpenOCD Concept Index, Prev: Tcl Crash Course, Up: Top
|
|||
|
|
|||
|
Appendix A The GNU Free Documentation License.
|
|||
|
**********************************************
|
|||
|
|
|||
|
Version 1.2, November 2002
|
|||
|
|
|||
|
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
|||
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
|
|||
|
|
|||
|
Everyone is permitted to copy and distribute verbatim copies
|
|||
|
of this license document, but changing it is not allowed.
|
|||
|
|
|||
|
0. PREAMBLE
|
|||
|
|
|||
|
The purpose of this License is to make a manual, textbook, or other
|
|||
|
functional and useful document "free" in the sense of freedom: to
|
|||
|
assure everyone the effective freedom to copy and redistribute it,
|
|||
|
with or without modifying it, either commercially or
|
|||
|
noncommercially. Secondarily, this License preserves for the
|
|||
|
author and publisher a way to get credit for their work, while not
|
|||
|
being considered responsible for modifications made by others.
|
|||
|
|
|||
|
This License is a kind of "copyleft", which means that derivative
|
|||
|
works of the document must themselves be free in the same sense.
|
|||
|
It complements the GNU General Public License, which is a copyleft
|
|||
|
license designed for free software.
|
|||
|
|
|||
|
We have designed this License in order to use it for manuals for
|
|||
|
free software, because free software needs free documentation: a
|
|||
|
free program should come with manuals providing the same freedoms
|
|||
|
that the software does. But this License is not limited to
|
|||
|
software manuals; it can be used for any textual work, regardless
|
|||
|
of subject matter or whether it is published as a printed book. We
|
|||
|
recommend this License principally for works whose purpose is
|
|||
|
instruction or reference.
|
|||
|
|
|||
|
1. APPLICABILITY AND DEFINITIONS
|
|||
|
|
|||
|
This License applies to any manual or other work, in any medium,
|
|||
|
that contains a notice placed by the copyright holder saying it can
|
|||
|
be distributed under the terms of this License. Such a notice
|
|||
|
grants a world-wide, royalty-free license, unlimited in duration,
|
|||
|
to use that work under the conditions stated herein. The
|
|||
|
"Document", below, refers to any such manual or work. Any member
|
|||
|
of the public is a licensee, and is addressed as "you". You accept
|
|||
|
the license if you copy, modify or distribute the work in a way
|
|||
|
requiring permission under copyright law.
|
|||
|
|
|||
|
A "Modified Version" of the Document means any work containing the
|
|||
|
Document or a portion of it, either copied verbatim, or with
|
|||
|
modifications and/or translated into another language.
|
|||
|
|
|||
|
A "Secondary Section" is a named appendix or a front-matter section
|
|||
|
of the Document that deals exclusively with the relationship of the
|
|||
|
publishers or authors of the Document to the Document's overall
|
|||
|
subject (or to related matters) and contains nothing that could
|
|||
|
fall directly within that overall subject. (Thus, if the Document
|
|||
|
is in part a textbook of mathematics, a Secondary Section may not
|
|||
|
explain any mathematics.) The relationship could be a matter of
|
|||
|
historical connection with the subject or with related matters, or
|
|||
|
of legal, commercial, philosophical, ethical or political position
|
|||
|
regarding them.
|
|||
|
|
|||
|
The "Invariant Sections" are certain Secondary Sections whose
|
|||
|
titles are designated, as being those of Invariant Sections, in the
|
|||
|
notice that says that the Document is released under this License.
|
|||
|
If a section does not fit the above definition of Secondary then it
|
|||
|
is not allowed to be designated as Invariant. The Document may
|
|||
|
contain zero Invariant Sections. If the Document does not identify
|
|||
|
any Invariant Sections then there are none.
|
|||
|
|
|||
|
The "Cover Texts" are certain short passages of text that are
|
|||
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
|
|||
|
that says that the Document is released under this License. A
|
|||
|
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
|
|||
|
be at most 25 words.
|
|||
|
|
|||
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|||
|
represented in a format whose specification is available to the
|
|||
|
general public, that is suitable for revising the document
|
|||
|
straightforwardly with generic text editors or (for images composed
|
|||
|
of pixels) generic paint programs or (for drawings) some widely
|
|||
|
available drawing editor, and that is suitable for input to text
|
|||
|
formatters or for automatic translation to a variety of formats
|
|||
|
suitable for input to text formatters. A copy made in an otherwise
|
|||
|
Transparent file format whose markup, or absence of markup, has
|
|||
|
been arranged to thwart or discourage subsequent modification by
|
|||
|
readers is not Transparent. An image format is not Transparent if
|
|||
|
used for any substantial amount of text. A copy that is not
|
|||
|
"Transparent" is called "Opaque".
|
|||
|
|
|||
|
Examples of suitable formats for Transparent copies include plain
|
|||
|
ASCII without markup, Texinfo input format, LaTeX input format,
|
|||
|
SGML or XML using a publicly available DTD, and standard-conforming
|
|||
|
simple HTML, PostScript or PDF designed for human modification.
|
|||
|
Examples of transparent image formats include PNG, XCF and JPG.
|
|||
|
Opaque formats include proprietary formats that can be read and
|
|||
|
edited only by proprietary word processors, SGML or XML for which
|
|||
|
the DTD and/or processing tools are not generally available, and
|
|||
|
the machine-generated HTML, PostScript or PDF produced by some word
|
|||
|
processors for output purposes only.
|
|||
|
|
|||
|
The "Title Page" means, for a printed book, the title page itself,
|
|||
|
plus such following pages as are needed to hold, legibly, the
|
|||
|
material this License requires to appear in the title page. For
|
|||
|
works in formats which do not have any title page as such, "Title
|
|||
|
Page" means the text near the most prominent appearance of the
|
|||
|
work's title, preceding the beginning of the body of the text.
|
|||
|
|
|||
|
A section "Entitled XYZ" means a named subunit of the Document
|
|||
|
whose title either is precisely XYZ or contains XYZ in parentheses
|
|||
|
following text that translates XYZ in another language. (Here XYZ
|
|||
|
stands for a specific section name mentioned below, such as
|
|||
|
"Acknowledgements", "Dedications", "Endorsements", or "History".)
|
|||
|
To "Preserve the Title" of such a section when you modify the
|
|||
|
Document means that it remains a section "Entitled XYZ" according
|
|||
|
to this definition.
|
|||
|
|
|||
|
The Document may include Warranty Disclaimers next to the notice
|
|||
|
which states that this License applies to the Document. These
|
|||
|
Warranty Disclaimers are considered to be included by reference in
|
|||
|
this License, but only as regards disclaiming warranties: any other
|
|||
|
implication that these Warranty Disclaimers may have is void and
|
|||
|
has no effect on the meaning of this License.
|
|||
|
|
|||
|
2. VERBATIM COPYING
|
|||
|
|
|||
|
You may copy and distribute the Document in any medium, either
|
|||
|
commercially or noncommercially, provided that this License, the
|
|||
|
copyright notices, and the license notice saying this License
|
|||
|
applies to the Document are reproduced in all copies, and that you
|
|||
|
add no other conditions whatsoever to those of this License. You
|
|||
|
may not use technical measures to obstruct or control the reading
|
|||
|
or further copying of the copies you make or distribute. However,
|
|||
|
you may accept compensation in exchange for copies. If you
|
|||
|
distribute a large enough number of copies you must also follow the
|
|||
|
conditions in section 3.
|
|||
|
|
|||
|
You may also lend copies, under the same conditions stated above,
|
|||
|
and you may publicly display copies.
|
|||
|
|
|||
|
3. COPYING IN QUANTITY
|
|||
|
|
|||
|
If you publish printed copies (or copies in media that commonly
|
|||
|
have printed covers) of the Document, numbering more than 100, and
|
|||
|
the Document's license notice requires Cover Texts, you must
|
|||
|
enclose the copies in covers that carry, clearly and legibly, all
|
|||
|
these Cover Texts: Front-Cover Texts on the front cover, and
|
|||
|
Back-Cover Texts on the back cover. Both covers must also clearly
|
|||
|
and legibly identify you as the publisher of these copies. The
|
|||
|
front cover must present the full title with all words of the title
|
|||
|
equally prominent and visible. You may add other material on the
|
|||
|
covers in addition. Copying with changes limited to the covers, as
|
|||
|
long as they preserve the title of the Document and satisfy these
|
|||
|
conditions, can be treated as verbatim copying in other respects.
|
|||
|
|
|||
|
If the required texts for either cover are too voluminous to fit
|
|||
|
legibly, you should put the first ones listed (as many as fit
|
|||
|
reasonably) on the actual cover, and continue the rest onto
|
|||
|
adjacent pages.
|
|||
|
|
|||
|
If you publish or distribute Opaque copies of the Document
|
|||
|
numbering more than 100, you must either include a machine-readable
|
|||
|
Transparent copy along with each Opaque copy, or state in or with
|
|||
|
each Opaque copy a computer-network location from which the general
|
|||
|
network-using public has access to download using public-standard
|
|||
|
network protocols a complete Transparent copy of the Document, free
|
|||
|
of added material. If you use the latter option, you must take
|
|||
|
reasonably prudent steps, when you begin distribution of Opaque
|
|||
|
copies in quantity, to ensure that this Transparent copy will
|
|||
|
remain thus accessible at the stated location until at least one
|
|||
|
year after the last time you distribute an Opaque copy (directly or
|
|||
|
through your agents or retailers) of that edition to the public.
|
|||
|
|
|||
|
It is requested, but not required, that you contact the authors of
|
|||
|
the Document well before redistributing any large number of copies,
|
|||
|
to give them a chance to provide you with an updated version of the
|
|||
|
Document.
|
|||
|
|
|||
|
4. MODIFICATIONS
|
|||
|
|
|||
|
You may copy and distribute a Modified Version of the Document
|
|||
|
under the conditions of sections 2 and 3 above, provided that you
|
|||
|
release the Modified Version under precisely this License, with the
|
|||
|
Modified Version filling the role of the Document, thus licensing
|
|||
|
distribution and modification of the Modified Version to whoever
|
|||
|
possesses a copy of it. In addition, you must do these things in
|
|||
|
the Modified Version:
|
|||
|
|
|||
|
A. Use in the Title Page (and on the covers, if any) a title
|
|||
|
distinct from that of the Document, and from those of previous
|
|||
|
versions (which should, if there were any, be listed in the
|
|||
|
History section of the Document). You may use the same title
|
|||
|
as a previous version if the original publisher of that
|
|||
|
version gives permission.
|
|||
|
|
|||
|
B. List on the Title Page, as authors, one or more persons or
|
|||
|
entities responsible for authorship of the modifications in
|
|||
|
the Modified Version, together with at least five of the
|
|||
|
principal authors of the Document (all of its principal
|
|||
|
authors, if it has fewer than five), unless they release you
|
|||
|
from this requirement.
|
|||
|
|
|||
|
C. State on the Title page the name of the publisher of the
|
|||
|
Modified Version, as the publisher.
|
|||
|
|
|||
|
D. Preserve all the copyright notices of the Document.
|
|||
|
|
|||
|
E. Add an appropriate copyright notice for your modifications
|
|||
|
adjacent to the other copyright notices.
|
|||
|
|
|||
|
F. Include, immediately after the copyright notices, a license
|
|||
|
notice giving the public permission to use the Modified
|
|||
|
Version under the terms of this License, in the form shown in
|
|||
|
the Addendum below.
|
|||
|
|
|||
|
G. Preserve in that license notice the full lists of Invariant
|
|||
|
Sections and required Cover Texts given in the Document's
|
|||
|
license notice.
|
|||
|
|
|||
|
H. Include an unaltered copy of this License.
|
|||
|
|
|||
|
I. Preserve the section Entitled "History", Preserve its Title,
|
|||
|
and add to it an item stating at least the title, year, new
|
|||
|
authors, and publisher of the Modified Version as given on the
|
|||
|
Title Page. If there is no section Entitled "History" in the
|
|||
|
Document, create one stating the title, year, authors, and
|
|||
|
publisher of the Document as given on its Title Page, then add
|
|||
|
an item describing the Modified Version as stated in the
|
|||
|
previous sentence.
|
|||
|
|
|||
|
J. Preserve the network location, if any, given in the Document
|
|||
|
for public access to a Transparent copy of the Document, and
|
|||
|
likewise the network locations given in the Document for
|
|||
|
previous versions it was based on. These may be placed in the
|
|||
|
"History" section. You may omit a network location for a work
|
|||
|
that was published at least four years before the Document
|
|||
|
itself, or if the original publisher of the version it refers
|
|||
|
to gives permission.
|
|||
|
|
|||
|
K. For any section Entitled "Acknowledgements" or "Dedications",
|
|||
|
Preserve the Title of the section, and preserve in the section
|
|||
|
all the substance and tone of each of the contributor
|
|||
|
acknowledgements and/or dedications given therein.
|
|||
|
|
|||
|
L. Preserve all the Invariant Sections of the Document, unaltered
|
|||
|
in their text and in their titles. Section numbers or the
|
|||
|
equivalent are not considered part of the section titles.
|
|||
|
|
|||
|
M. Delete any section Entitled "Endorsements". Such a section
|
|||
|
may not be included in the Modified Version.
|
|||
|
|
|||
|
N. Do not retitle any existing section to be Entitled
|
|||
|
"Endorsements" or to conflict in title with any Invariant
|
|||
|
Section.
|
|||
|
|
|||
|
O. Preserve any Warranty Disclaimers.
|
|||
|
|
|||
|
If the Modified Version includes new front-matter sections or
|
|||
|
appendices that qualify as Secondary Sections and contain no
|
|||
|
material copied from the Document, you may at your option designate
|
|||
|
some or all of these sections as invariant. To do this, add their
|
|||
|
titles to the list of Invariant Sections in the Modified Version's
|
|||
|
license notice. These titles must be distinct from any other
|
|||
|
section titles.
|
|||
|
|
|||
|
You may add a section Entitled "Endorsements", provided it contains
|
|||
|
nothing but endorsements of your Modified Version by various
|
|||
|
parties--for example, statements of peer review or that the text
|
|||
|
has been approved by an organization as the authoritative
|
|||
|
definition of a standard.
|
|||
|
|
|||
|
You may add a passage of up to five words as a Front-Cover Text,
|
|||
|
and a passage of up to 25 words as a Back-Cover Text, to the end of
|
|||
|
the list of Cover Texts in the Modified Version. Only one passage
|
|||
|
of Front-Cover Text and one of Back-Cover Text may be added by (or
|
|||
|
through arrangements made by) any one entity. If the Document
|
|||
|
already includes a cover text for the same cover, previously added
|
|||
|
by you or by arrangement made by the same entity you are acting on
|
|||
|
behalf of, you may not add another; but you may replace the old
|
|||
|
one, on explicit permission from the previous publisher that added
|
|||
|
the old one.
|
|||
|
|
|||
|
The author(s) and publisher(s) of the Document do not by this
|
|||
|
License give permission to use their names for publicity for or to
|
|||
|
assert or imply endorsement of any Modified Version.
|
|||
|
|
|||
|
5. COMBINING DOCUMENTS
|
|||
|
|
|||
|
You may combine the Document with other documents released under
|
|||
|
this License, under the terms defined in section 4 above for
|
|||
|
modified versions, provided that you include in the combination all
|
|||
|
of the Invariant Sections of all of the original documents,
|
|||
|
unmodified, and list them all as Invariant Sections of your
|
|||
|
combined work in its license notice, and that you preserve all
|
|||
|
their Warranty Disclaimers.
|
|||
|
|
|||
|
The combined work need only contain one copy of this License, and
|
|||
|
multiple identical Invariant Sections may be replaced with a single
|
|||
|
copy. If there are multiple Invariant Sections with the same name
|
|||
|
but different contents, make the title of each such section unique
|
|||
|
by adding at the end of it, in parentheses, the name of the
|
|||
|
original author or publisher of that section if known, or else a
|
|||
|
unique number. Make the same adjustment to the section titles in
|
|||
|
the list of Invariant Sections in the license notice of the
|
|||
|
combined work.
|
|||
|
|
|||
|
In the combination, you must combine any sections Entitled
|
|||
|
"History" in the various original documents, forming one section
|
|||
|
Entitled "History"; likewise combine any sections Entitled
|
|||
|
"Acknowledgements", and any sections Entitled "Dedications". You
|
|||
|
must delete all sections Entitled "Endorsements."
|
|||
|
|
|||
|
6. COLLECTIONS OF DOCUMENTS
|
|||
|
|
|||
|
You may make a collection consisting of the Document and other
|
|||
|
documents released under this License, and replace the individual
|
|||
|
copies of this License in the various documents with a single copy
|
|||
|
that is included in the collection, provided that you follow the
|
|||
|
rules of this License for verbatim copying of each of the documents
|
|||
|
in all other respects.
|
|||
|
|
|||
|
You may extract a single document from such a collection, and
|
|||
|
distribute it individually under this License, provided you insert
|
|||
|
a copy of this License into the extracted document, and follow this
|
|||
|
License in all other respects regarding verbatim copying of that
|
|||
|
document.
|
|||
|
|
|||
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|||
|
|
|||
|
A compilation of the Document or its derivatives with other
|
|||
|
separate and independent documents or works, in or on a volume of a
|
|||
|
storage or distribution medium, is called an "aggregate" if the
|
|||
|
copyright resulting from the compilation is not used to limit the
|
|||
|
legal rights of the compilation's users beyond what the individual
|
|||
|
works permit. When the Document is included in an aggregate, this
|
|||
|
License does not apply to the other works in the aggregate which
|
|||
|
are not themselves derivative works of the Document.
|
|||
|
|
|||
|
If the Cover Text requirement of section 3 is applicable to these
|
|||
|
copies of the Document, then if the Document is less than one half
|
|||
|
of the entire aggregate, the Document's Cover Texts may be placed
|
|||
|
on covers that bracket the Document within the aggregate, or the
|
|||
|
electronic equivalent of covers if the Document is in electronic
|
|||
|
form. Otherwise they must appear on printed covers that bracket
|
|||
|
the whole aggregate.
|
|||
|
|
|||
|
8. TRANSLATION
|
|||
|
|
|||
|
Translation is considered a kind of modification, so you may
|
|||
|
distribute translations of the Document under the terms of section
|
|||
|
4. Replacing Invariant Sections with translations requires special
|
|||
|
permission from their copyright holders, but you may include
|
|||
|
translations of some or all Invariant Sections in addition to the
|
|||
|
original versions of these Invariant Sections. You may include a
|
|||
|
translation of this License, and all the license notices in the
|
|||
|
Document, and any Warranty Disclaimers, provided that you also
|
|||
|
include the original English version of this License and the
|
|||
|
original versions of those notices and disclaimers. In case of a
|
|||
|
disagreement between the translation and the original version of
|
|||
|
this License or a notice or disclaimer, the original version will
|
|||
|
prevail.
|
|||
|
|
|||
|
If a section in the Document is Entitled "Acknowledgements",
|
|||
|
"Dedications", or "History", the requirement (section 4) to
|
|||
|
Preserve its Title (section 1) will typically require changing the
|
|||
|
actual title.
|
|||
|
|
|||
|
9. TERMINATION
|
|||
|
|
|||
|
You may not copy, modify, sublicense, or distribute the Document
|
|||
|
except as expressly provided for under this License. Any other
|
|||
|
attempt to copy, modify, sublicense or distribute the Document is
|
|||
|
void, and will automatically terminate your rights under this
|
|||
|
License. However, parties who have received copies, or rights,
|
|||
|
from you under this License will not have their licenses terminated
|
|||
|
so long as such parties remain in full compliance.
|
|||
|
|
|||
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|||
|
|
|||
|
The Free Software Foundation may publish new, revised versions of
|
|||
|
the GNU Free Documentation License from time to time. Such new
|
|||
|
versions will be similar in spirit to the present version, but may
|
|||
|
differ in detail to address new problems or concerns. See
|
|||
|
<https://www.gnu.org/licenses/>.
|
|||
|
|
|||
|
Each version of the License is given a distinguishing version
|
|||
|
number. If the Document specifies that a particular numbered
|
|||
|
version of this License "or any later version" applies to it, you
|
|||
|
have the option of following the terms and conditions either of
|
|||
|
that specified version or of any later version that has been
|
|||
|
published (not as a draft) by the Free Software Foundation. If the
|
|||
|
Document does not specify a version number of this License, you may
|
|||
|
choose any version ever published (not as a draft) by the Free
|
|||
|
Software Foundation.
|
|||
|
|
|||
|
ADDENDUM: How to use this License for your documents
|
|||
|
====================================================
|
|||
|
|
|||
|
To use this License in a document you have written, include a copy of
|
|||
|
the License in the document and put the following copyright and license
|
|||
|
notices just after the title page:
|
|||
|
|
|||
|
Copyright (C) YEAR YOUR NAME.
|
|||
|
Permission is granted to copy, distribute and/or modify this document
|
|||
|
under the terms of the GNU Free Documentation License, Version 1.2
|
|||
|
or any later version published by the Free Software Foundation;
|
|||
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|||
|
Texts. A copy of the license is included in the section entitled ``GNU
|
|||
|
Free Documentation License''.
|
|||
|
|
|||
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
|||
|
replace the "with...Texts." line with this:
|
|||
|
|
|||
|
with the Invariant Sections being LIST THEIR TITLES, with
|
|||
|
the Front-Cover Texts being LIST, and with the Back-Cover Texts
|
|||
|
being LIST.
|
|||
|
|
|||
|
If you have Invariant Sections without Cover Texts, or some other
|
|||
|
combination of the three, merge those two alternatives to suit the
|
|||
|
situation.
|
|||
|
|
|||
|
If your document contains nontrivial examples of program code, we
|
|||
|
recommend releasing these examples in parallel under your choice of free
|
|||
|
software license, such as the GNU General Public License, to permit
|
|||
|
their use in free software.
|
|||
|
|
|||
|
|
|||
|
File: openocd.info, Node: OpenOCD Concept Index, Next: Command and Driver Index, Prev: License, Up: Top
|
|||
|
|
|||
|
OpenOCD Concept Index
|
|||
|
*********************
|
|||
|
|
|||
|
|