14 General Commands

The commands documented in this chapter here are common commands that you 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 intent is to be a machine interface. The default TCL port is 5555.

14.1 Daemon Commands

14.1.1 sleep [msec]

Wait for n milliseconds before resuming. Useful in connection with script files (script command and target_script configuration).

14.1.2 shutdown

Close the OpenOCD daemon, disconnecting all clients (GDB, Telnet, Other).

14.1.3 debug_level [n]

Display or adjust debug level to n<0-3>

14.1.4 fast [enable|disable]

Default disabled. Set default behaviour of OpenOCD to be "fast and dangerous". For instance ARM7/9 DCC memory downloads and fast memory access will work if the JTAG interface isn't too fast and the core doesn't run at a too low frequency. Note that this option only changes the default and that the indvidual options, like DCC memory downloads, can be enabled and disabled individually.

The target specific "dangerous" optimisation tweaking options may come and go as more robust and user friendly ways are found to ensure maximum throughput and robustness with a minimum of configuration.

Typically the "fast enable" is specified first on the command line:

     openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg

14.1.5 log_output <file>

Redirect logging to <file> (default: stderr)

14.1.6 script <file>

Execute commands from <file> Also see: “source [find FILENAME]”

14.2 Target state handling

14.2.1 power <on|off>

Turn power switch to target on/off. No arguments: print status. Not all interfaces support this.

14.2.2 reg [#|name] [value]

Access a single register by its number[#] or by its [name]. No arguments: list all available registers for the current target. Number or name argument: display a register Number or name and value arguments: set register value

14.2.3 poll [on|off]

Poll the target for its current state. If the target is in debug mode, architecture specific information about the current state is printed. An optional parameter allows continuous polling to be enabled and disabled.

14.2.4 halt [ms]

Send a halt request to the target and wait for it to halt for up to [ms] milliseconds. Default [ms] is 5 seconds if no arg given. Optional arg ms is a timeout in milliseconds. Using 0 as the [ms] will stop OpenOCD from waiting.

14.2.5 wait_halt [ms]

Wait for the target to enter debug mode. Optional [ms] is a timeout in milliseconds. Default [ms] is 5 seconds if no arg given.

14.2.6 resume [address]

Resume the target at its current code position, or at an optional address. OpenOCD will wait 5 seconds for the target to resume.

14.2.7 step [address]

Single-step the target at its current code position, or at an optional address.

14.2.8 reset [run|halt|init]

Perform a hard-reset. The optional parameter specifies what should happen after the reset.

With no arguments a "reset run" is executed

• run
  Let the target run.
• halt
  Immediately halt the target (works only with certain configurations).
• init
  Immediately halt the target, and execute the reset script (works only with certain configurations)

14.2.9 soft_reset_halt

Requesting target halt and executing a soft reset. This 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 at the reset vector. Unfortunatlly that code that was executed may have left hardware in an unknown state.

14.3 Memory access commands

14.3.1 meminfo

display available ram memory.

14.3.2 Memory Peek/Poke type 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 certian values to the SDRAM controller to enable SDRAM.

1. To change the current target see the “targets” (plural) command
2. In system level scripts these commands are depricated, please use the TARGET object versions.

• mdw <addr> [count]
  display memory words (32bit)
• mdh <addr> [count]
  display memory half-words (16bit)
• mdb <addr> [count]
  display memory bytes (8bit)
• mww <addr> <value>
  write memory word (32bit)
• mwh <addr> <value>
  write memory half-word (16bit)
• mwb <addr> <value>
  write memory byte (8bit)

14.4 Image Loading Commands

14.4.1 load_image

load_image <file> <address> [bin|ihex|elf]
Load image <file> to target memory at <address>

14.4.2 fast_load_image

fast_load_image <file> <address> [bin|ihex|elf]
Normally you should be using load_image or GDB load. However, for testing purposes or when IO overhead is significant(OpenOCD running on embedded host), then 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 as load_image, but image is stored in OpenOCD host memory, i.e. does not affect target. This approach is also useful when profiling target programming performance as IO and target programming can easily be profiled seperately.

14.4.3 fast_load

fast_load
Loads image stored in memory by fast_load_image to current target. Must be preceeded by fast_load_image.

14.4.4 dump_image

dump_image <file> <address> <size>
Dump <size> bytes of target memory starting at <address> to a (binary) <file>.

14.4.5 verify_image

verify_image <file> <address> [bin|ihex|elf]
Verify <file> against target memory starting at <address>. This will first attempt comparison using a crc checksum, if this fails it will try a binary compare.

14.5 Breakpoint commands

• bp <addr> <len> [hw]
  set breakpoint <address> <length> [hw]
• rbp <addr>
  remove breakpoint <adress>
• wp <addr> <len> <r|w|a> [value] [mask]
  set watchpoint <address> <length> <r/w/a> [value] [mask]
• rwp <addr>
  remove watchpoint <adress>

14.6 Misc Commands

• profile <seconds> <gmon.out>

  Profiling samples the CPU PC as quickly as OpenOCD is able, which will be used as a random sampling of PC.

14.7 Target Specific Commands

14.8 Architecture Specific Commands

14.8.1 ARMV4/5 specific commands

These commands are specific to ARM architecture v4 and v5, like all ARM7/9 systems or Intel XScale (XScale isn't supported yet).

• armv4_5 reg
  Display a list of all banked core registers, fetching the current value from every core mode if necessary. OpenOCD versions before rev. 60 didn't fetch the current register value.
• armv4_5 core_mode [arm|thumb]
  Displays the core_mode, optionally changing it to either ARM or Thumb mode. The target is resumed in the currently set core_mode.

14.8.2 ARM7/9 specific commands

These commands are specific to ARM7 and ARM9 targets, like ARM7TDMI, ARM720t, ARM920t or ARM926EJ-S.

• arm7_9 dbgrq <enable|disable>
  Enable use of the DBGRQ bit to force entry into debug mode. This should be safe for all but ARM7TDMI–S cores (like Philips LPC).
• arm7_9 fast_memory_access <enable|disable>
  Allow OpenOCD to read and write memory without checking completion of the operation. This provides a huge speed increase, especially with USB JTAG cables (FT2232), but might be unsafe if used with targets running at a very low speed, like the 32kHz startup clock of an AT91RM9200.
• arm7_9 dcc_downloads <enable|disable>
  Enable the use of the debug communications channel (DCC) to write larger (>128 byte) amounts of memory. DCC downloads offer a huge speed increase, but might be potentially unsafe, especially with targets running at a very low speed. This command was introduced with OpenOCD rev. 60.

14.8.3 ARM720T specific commands

• arm720t cp15 <num> [value]
  display/modify cp15 register <num> [value].
• arm720t md<bhw>_phys <addr> [count]
  Display memory at physical address addr.
• arm720t mw<bhw>_phys <addr> <value>
  Write memory at physical address addr.
• arm720t virt2phys <va>
  Translate a virtual address to a physical address.

14.8.4 ARM9TDMI specific commands

• arm9tdmi vector_catch <all|none>
  Catch arm9 interrupt vectors, can be all none or any of the following: reset undef swi pabt dabt reserved irq fiq.

  Can also be used on other arm9 based cores, arm966, arm920t and arm926ejs.

14.8.5 ARM966E specific commands

• arm966e cp15 <num> [value]
  display/modify cp15 register <num> [value].

14.8.6 ARM920T specific commands

• arm920t cp15 <num> [value]
  display/modify cp15 register <num> [value].
• arm920t cp15i <num> [value] [address]
  display/modify cp15 (interpreted access) <opcode> [value] [address]
• arm920t cache_info
  Print information about the caches found. This allows you to see if your target is a ARM920T (2x16kByte cache) or ARM922T (2x8kByte cache).
• arm920t md<bhw>_phys <addr> [count]
  Display memory at physical address addr.
• arm920t mw<bhw>_phys <addr> <value>
  Write memory at physical address addr.
• arm920t read_cache <filename>
  Dump the content of ICache and DCache to a file.
• arm920t read_mmu <filename>
  Dump the content of the ITLB and DTLB to a file.
• arm920t virt2phys <va>
  Translate a virtual address to a physical address.

14.8.7 ARM926EJS specific commands

• arm926ejs cp15 <num> [value]
  display/modify cp15 register <num> [value].
• arm926ejs cache_info
  Print information about the caches found.
• arm926ejs md<bhw>_phys <addr> [count]
  Display memory at physical address addr.
• arm926ejs mw<bhw>_phys <addr> <value>
  Write memory at physical address addr.
• arm926ejs virt2phys <va>
  Translate a virtual address to a physical address.

14.8.8 CORTEX_M3 specific commands

• cortex_m3 maskisr <on|off>
  Enable masking (disabling) interrupts during target step/resume.

14.9 Debug commands

The following commands give direct access to the core, and are most likely only useful while debugging OpenOCD.

• arm7_9 write_xpsr <32-bit value> <0=cpsr, 1=spsr>
  Immediately write either the current program status register (CPSR) or the saved program status register (SPSR), without changing the register cache (as displayed by the reg and armv4_5 reg commands).
• arm7_9 write_xpsr_im8 <8-bit value> <rotate 4-bit> <0=cpsr,1=spsr>
  Write the 8-bit value rotated right by 2*rotate bits, using an immediate write operation (similar to write_xpsr).
• arm7_9 write_core_reg <num> <mode> <value>
  Write a core register, without changing the register cache (as displayed by the reg and armv4_5 reg commands). The <mode> argument takes the encoding of the [M4:M0] bits of the PSR.

14.10 Target Requests

OpenOCD can handle certain target requests, currently debugmsg are only supported for arm7_9 and cortex_m3. See libdcc in the contrib dir for more details.

• target_request debugmsgs <enable|disable>
  Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running.