Next: Architecture and Core Commands, Previous: PLD/FPGA Commands, Up: Top [Contents][Index]
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:
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.
Exits the current telnet session.
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.
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).
Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).
Display debug level. If n (from 0..3) 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; and level 3 adds debugging messages. The default is level 2, but that can be overridden on the command line along with the location of that log file (which is normally the server’s standard output). See Running.
Logs a message at "user" priority. Output message to stdout. Option "-n" suppresses trailing newline.
echo "Downloading kernel -- please wait"
Redirect logging to filename; the initial log output channel is stderr.
Add directory to the file/script search path.
Specify address by name on which to listen for incoming TCP/IP connections. By default, OpenOCD will listen on the loopback interface only.
In this section “target” refers to a CPU configured as
shown earlier (see 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.
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) >
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
haltcommand. 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 generaly 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).
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.
Single-step the target at its current code position, or the optional address if it is provided.
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.
See Reset Configuration.
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.
These commands are available when OpenOCD is built with --enable-ioutil. They are mainly useful on embedded targets, notably the ZY1000. Hosts with operating systems have complementary tools.
Note: there are several more such commands.
Appends the string parameters to the text file filename. Each string except the last one is followed by one space. The last string is followed by a newline.
Reads and displays the text file filename.
Copies contents from the file src_filename into dest_filename.
No description provided.
No description provided.
No description provided.
Display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts.
No description provided.
No description provided.
Unlinks the file filename.
Removes all data in the file filename.
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.
targets (plural) command
to change the current target.
Display contents of address addr, as
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.)
Writes the specified 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.
Dump size bytes of target memory starting at address to the binary file named filename.
Loads an image stored in memory by fast_load_image to the
current target. Must be preceeded by fast_load_image.
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.
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 specifed: 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
}
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)
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.
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.
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.
(See arm9 vector_catch, or see xscale vector_catch, for similar mechanisms that do not consume hardware breakpoints.)
Remove the breakpoint at address.
Remove data watchpoint on address
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.
Profiling samples the CPU’s program counter as quickly as possible, which is useful for non-intrusive stochastic profiling. Saves up to 10000 sampines in filename using “gmon.out” format.
Displays a string identifying the version of this OpenOCD server.
Requests the current target to map the specified virtual_address to its corresponding physical address, and displays the result.
Next: Architecture and Core Commands, Previous: PLD/FPGA Commands, Up: Top [Contents][Index]