## 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 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 Daemon 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

> Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, other).

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

### 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]]

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

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

### 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

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

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