Next: , Previous: General Commands, Up: Top


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

17.1 ARM 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”.

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. It seems like a GDB hookup should be possible, as well as triggering trace on specific events (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.

17.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. See Trace Port Drivers.

Several of the parameters must reflect the trace port configuration. The width must be either 4, 8, or 16. The mode must be normal, multiplexted, or demultiplexted. The clocking must be half or full.

Note: You can see the ETM registers using the reg command, although not all of those possible registers are present in every ETM.

— Command: etm info

Displays information about the current target's ETM.

— Command: etm status

Displays status of the current target's ETM: 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.

— Command: etm trigger_percent percent

Buggy and effectively a NOP ... percent from 2..100

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

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

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

— Trace Port Driver: oocd_trace

This driver isn't available unless OpenOCD was explicitly configured with the --enable-oocd_trace option. You probably don't want to configure it unless you've built the appropriate prototype hardware; it's proof-of-concept software.

Use the oocd_trace driver if you are configuring an ETM that's connected to an off-chip trace connector.

— Config Command: oocd_trace config target tty

Associates the ETM for target with a trace driver which collects data through the serial port tty.

— Command: oocd_trace resync

Re-synchronizes with the capture clock.

— Command: oocd_trace status

Reports whether the capture clock is locked or not.

17.2 ARMv4 and ARMv5 Architecture

These commands are specific to ARM architecture v4 and v5, including all ARM7 or ARM9 systems and Intel XScale. They are available in addition to other core-specific commands that may be available.

— Command: armv4_5 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: armv4_5 disassemble address count [thumb]

Disassembles count instructions starting at address. If thumb is specified, Thumb (16-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.)

— Command: armv4_5 reg

Display a table 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.

17.2.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 ARMv4/5 commands, and any other core-specific commands that may be available.

— Command: arm7_9 dbgrq (enable|disable)

Control use of the EmbeddedIce DBGRQ signal to force entry into debug mode, instead of breakpoints. This should be safe for all but ARM7TDMI–S cores (like Philips LPC).

— Command: arm7_9 dcc_downloads (enable|disable)

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

Enable or disable memory writes and reads that don't check 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 very low speeds, like the 32kHz startup clock of an AT91RM9200.

— Debug Command: arm7_9 write_core_reg num mode word

This is intended for use while debugging OpenOCD; you probably shouldn't use it.

Writes a 32-bit word to register num (from 0 to 16) as used in the specified mode (where e.g. mode 16 is "user" and mode 19 is "supervisor"; the M4..M0 bits of the PSR). Registers 0..15 are the normal CPU registers such as r0(0), r1(1) ... pc(15). Register 16 is the mode-specific SPSR, unless the specified mode is 0xffffffff (32-bit all-ones) in which case register 16 is the CPSR. The write goes directly to the CPU, bypassing the register cache.

— Debug Command: arm7_9 write_xpsr word (0|1)

This is intended for use while debugging OpenOCD; you probably shouldn't use it.

If the second parameter is zero, writes word to the Current Program Status register (CPSR). Else writes word to the current mode's Saved PSR (SPSR). In both cases, this bypasses the register cache.

— Debug Command: arm7_9 write_xpsr_im8 byte rotate (0|1)

This is intended for use while debugging OpenOCD; you probably shouldn't use it.

Writes eight bits to the CPSR or SPSR, first rotating them by 2*rotate bits, and bypassing the register cache. This has lower JTAG overhead than writing the entire CPSR or SPSR with arm7_9 write_xpsr.

17.2.2 ARM720T specific commands

These commands are available to ARM720T based CPUs, which are implementations of the ARMv4T architecture based on the ARM7TDMI-S integer core. They are available in addition to the ARMv4/5 and ARM7/ARM9 commands.

— Command: arm720t cp15 regnum [value]

Display cp15 register regnum; else if a value is provided, that value is written to that register.

— Command: arm720t mdw_phys addr [count]
— Command: arm720t mdh_phys addr [count]
— Command: arm720t mdb_phys addr [count]

Display contents of physical address addr, as 32-bit words (mdw_phys), 16-bit halfwords (mdh_phys), or 8-bit bytes (mdb_phys). If count is specified, displays that many units.

— Command: arm720t mww_phys addr word
— Command: arm720t mwh_phys addr halfword
— Command: arm720t mwb_phys addr byte

Writes the specified word (32 bits), halfword (16 bits), or byte (8-bit) pattern, at the specified physical address addr.

— Command: arm720t virt2phys va

Translate a virtual address va to a physical address and display the result.

17.2.3 ARM9TDMI specific commands

Many ARM9-family CPUs are built around ARM9TDMI integer cores, or processors resembling ARM9TDMI, and can use these commands. Such cores include the ARM920T, ARM926EJ-S, and ARM966.

— Command: arm9tdmi 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 reserved irq fiq.

17.2.4 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 ARMv4/5, ARM7/ARM9, and ARM9TDMI 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.

— Command: arm920t cp15i opcode [value [address]]

Interpreted access using cp15 opcode. If no value is provided, the result is displayed. Else if that value is written using the specified address, or using zero if no other address is not provided.

— Command: arm920t mdw_phys addr [count]
— Command: arm920t mdh_phys addr [count]
— Command: arm920t mdb_phys addr [count]

Display contents of physical address addr, as 32-bit words (mdw_phys), 16-bit halfwords (mdh_phys), or 8-bit bytes (mdb_phys). If count is specified, displays that many units.

— Command: arm920t mww_phys addr word
— Command: arm920t mwh_phys addr halfword
— Command: arm920t mwb_phys addr byte

Writes the specified word (32 bits), halfword (16 bits), or byte (8-bit) pattern, at the specified physical address addr.

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

— Command: arm920t virt2phys va

Translate a virtual address va to a physical address and display the result.

17.2.5 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 ARMv4/5, ARM7/ARM9, and ARM9TDMI 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.

— Command: arm926ejs cp15 opcode1 opcode2 CRn CRm regnum [value]

Accesses cp15 register regnum using opcode1, opcode2, CRn, and CRm. If a value is provided, that value is written to that register. Else that register is read and displayed.

— Command: arm926ejs mdw_phys addr [count]
— Command: arm926ejs mdh_phys addr [count]
— Command: arm926ejs mdb_phys addr [count]

Display contents of physical address addr, as 32-bit words (mdw_phys), 16-bit halfwords (mdh_phys), or 8-bit bytes (mdb_phys). If count is specified, displays that many units.

— Command: arm926ejs mww_phys addr word
— Command: arm926ejs mwh_phys addr halfword
— Command: arm926ejs mwb_phys addr byte

Writes the specified word (32 bits), halfword (16 bits), or byte (8-bit) pattern, at the specified physical address addr.

— Command: arm926ejs virt2phys va

Translate a virtual address va to a physical address and display the result.

17.2.6 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 ARMv4/5, ARM7/ARM9, and ARM9TDMI commands.

— Command: arm966e cp15 regnum [value]

Display cp15 register regnum; else if a value is provided, that value is written to that register.

17.2.7 XScale specific commands

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]

Enables or disables the trace buffer, and controls 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.

17.3 ARMv6 Architecture

17.3.1 ARM11 specific commands

— Command: arm11 mcr p1 p2 p3 p4 p5

Read coprocessor register

— Command: arm11 memwrite burst [value]

Displays the value of the memwrite burst-enable flag, which is enabled by default. If value is defined, first assigns that.

— Command: arm11 memwrite error_fatal [value]

Displays the value of the memwrite error_fatal flag, which is enabled by default. If value is defined, first assigns that.

— Command: arm11 mrc p1 p2 p3 p4 p5 value

Write coprocessor register

— Command: arm11 no_increment [value]

Displays the value of the flag controlling whether some read or write operations increment the pointer (the default behavior) or not (acting like a FIFO). If value is defined, first assigns that.

— Command: arm11 step_irq_enable [value]

Displays the value of the flag controlling whether IRQs are enabled during single stepping; they is disabled by default. If value is defined, first assigns that.

17.4 ARMv7 Architecture

17.4.1 ARMv7 Debug Access Port (DAP) specific commands

These commands are specific to ARM architecture v7 Debug Access Port (DAP), included on cortex-m3 and cortex-a8 systems. They are available in addition to other core-specific commands that may be available.

— Command: dap info [num]

Displays dap info for ap num, defaulting to the currently selected AP.

— Command: dap apsel [num]

Select AP num, defaulting to 0.

— Command: dap apid [num]

Displays id register from AP num, defaulting to the currently selected AP.

— Command: dap baseaddr [num]

Displays debug base address from AP num, defaulting to the currently selected AP.

— Command: dap memaccess [value]

Displays the number of extra tck for mem-ap memory bus access [0-255]. If value is defined, first assigns that.

17.4.2 Cortex-M3 specific commands

— Command: cortex_m3 maskisr (on|off)

Control masking (disabling) interrupts during target step/resume.

17.5 Target DCC Requests

OpenOCD can handle certain target requests; currently debugmsgs target_request debugmsgs are only supported for arm7_9 and cortex_m3.

See libdcc in the contrib dir for more details. 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.

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