jtag general command

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 programatically, 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: 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.

Command: debug_level [n]

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.

Command: echo [-n] message

Logs a message at "user" priority. Output message to stdout. Option "-n" suppresses trailing newline.

echo "Downloading kernel -- please wait"

Command: log_output [filename]

Redirect logging to filename; the initial log output channel is stderr.

Command: add_script_search_dir [directory]

Add directory to the file/script search path.

Command: bindto [name]

Specify address by name on which to listen for incoming TCP/IP connections. By default, OpenOCD will listen on all available interfaces.

15.2 Target State handling

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.

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 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).

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. See 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.

15.3 I/O Utilities

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.

Command: append_file filename [string]*

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.

Command: cat filename

Reads and displays the text file filename.

Command: cp src_filename dest_filename

Copies contents from the file src_filename into dest_filename.

Command: ip

No description provided.

Command: ls

No description provided.

Command: mac

No description provided.

Command: meminfo

Display available RAM memory on OpenOCD host. Used in OpenOCD regression testing scripts.

Command: peek

No description provided.

Command: poke

No description provided.

Command: rm filename

Unlinks the file filename.

Command: trunc filename

Removes all data in the file filename.

15.4 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: mdw [phys] addr [count]

Command: mdh [phys] addr [count]

Command: mdb [phys] addr [count]

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.)

Command: mww [phys] addr word

Command: mwh [phys] addr halfword

Command: mwb [phys] addr byte

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.

15.5 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 preceeded 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 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
}

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.6 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.

(See arm9 vector_catch, or see xscale vector_catch, for similar mechanisms that do not consume hardware breakpoints.)

Command: rbp address

Remove the breakpoint at address.

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.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 filenameusing “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.