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

### 16.1 ARM Hardware 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”.

- Development-oriented boards will sometimes provide a high speed trace connector for collecting that data, when the particular CPU supports such an interface. (The standard connector is a 38-pin Mictor, with both JTAG and trace port support.) Those trace connectors are supported by higher end JTAG adapters and some logic analyzer modules; frequently those modules can buffer several megabytes of trace data. Configuring an ETM coupled to such an external trace port belongs in the board-specific configuration file.
- If the CPU doesn’t provide an external interface, it probably has an “Embedded Trace Buffer” (ETB) on the chip, which is a dedicated SRAM. 4KBytes is one common ETB size. Configuring an ETM coupled only to an ETB belongs in the CPU-specific (target) configuration file, since it works the same on all boards.

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.

> ETM trigger events could also implement a kind of complex hardware breakpoint, much more powerful than the simple watchpoint hardware exported by EmbeddedICE modules. Such breakpoints can be triggered even when using the dummy trace port driver.

> It seems like a GDB hookup should be possible, as well as tracing only during specific states (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.

> At this writing (November 2009) only ARM7, ARM9, and ARM11 support for ETM modules is available. The code should be able to work with some newer cores; but not all of them support this original style of JTAG access.

#### 16.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 capabilities, which are a function of silicon capabilities (exposed later using `etm info`) and of what hardware is connected to that port (such as an external pod, or ETB). The width must be either 4, 8, or 16, except with ETMv3.0 and newer modules which may also support 1, 2, 24, 32, 48, and 64 bit widths. (With those versions, `etm info` also shows whether the selected port width and mode are supported.)

  The mode must be `normal`, `multiplexed`, or `demultiplexed`. The clocking must be `half` or `full`.

  > Warning: With ETMv3.0 and newer, the bits set with the mode and clocking parameters both control the mode. This modified mode does not map to the values supported by previous ETM modules, so this syntax is subject to change.

  > Note: You can see the ETM registers using the `reg` command. Not all possible registers are present in every ETM. Most of the registers are write-only, and are used to configure what CPU activities are traced.

Command: etm info ¶

  Displays information about the current target’s ETM. This includes resource counts from the `ETM_CONFIG` register, as well as silicon capabilities (except on rather old modules). from the `ETM_SYS_CONFIG` register.

Command: etm status ¶

  Displays status of the current target’s ETM and trace port driver: 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.

  - type ... describing how data accesses are traced, when they pass any ViewData filtering that was set up. The value is one of `none` (save nothing), `data` (save data), `address` (save addresses), `all` (save data and addresses)
  - context_id_bits ... 0, 8, 16, or 32
  - cycle_accurate ... `enable` or `disable` cycle-accurate instruction tracing. Before ETMv3, enabling this causes much extra data to be recorded.
  - branch_output ... `enable` or `disable`. Disable this unless you need to try reconstructing the instruction trace stream without an image of the code.

Command: etm trigger_debug (`enable`|`disable`) ¶

  Displays whether ETM triggering debug entry (like a breakpoint) is enabled or disabled, after optionally modifying that configuration. The default behaviour is `disable`. Any change takes effect after the next `etm start`.

  By using script commands to configure ETM registers, you can make the processor enter debug state automatically when certain conditions, more complex than supported by the breakpoint hardware, happen.

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

To configure what is being traced, you will need to write various trace registers using `reg ETM_*` commands. For the definitions of these registers, read ARM publication IHI 0014, “Embedded Trace Macrocell, Architecture Specification”. Be aware that most of the relevant registers are write-only, and that ETM resources are limited. There are only a handful of address comparators, data comparators, counters, and so on.

Examples of scenarios you might arrange to trace include:

- Code flow within a function, excluding subroutines it calls. Use address range comparators to enable tracing for instruction access within that function’s body.
- Code flow within a function, including subroutines it calls. Use the sequencer and address comparators to activate tracing on an “entered function” state, then deactivate it by exiting that state when the function’s exit code is invoked.
- Code flow starting at the fifth invocation of a function, combining one of the above models with a counter.
- CPU data accesses to the registers for a particular device, using address range comparators and the ViewData logic.
- Such data accesses only during IRQ handling, combining the above model with sequencer triggers which on entry and exit to the IRQ handler.
- ... more

At this writing, September 2009, there are no Tcl utility procedures to help set up any common tracing scenarios.

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.

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

  Command: etb trigger_percent [percent] ¶

    This displays, or optionally changes, ETB behavior after the ETM’s configured trigger event fires. It controls how much more trace data is saved after the (single) trace trigger becomes active.

    - The default corresponds to trace around usage, recording 50 percent data before the event and the rest afterwards.
    - The minimum value of percent is 2 percent, recording almost exclusively data before the trigger. Such extreme trace before usage can help figure out what caused that event to happen.
    - The maximum value of percent is 100 percent, recording data almost exclusively after the event. This extreme trace after usage might help sort out how the event caused trouble.

### 16.2 ARM Cross-Trigger Interface ¶

The ARM Cross-Trigger Interface (CTI) is a generic CoreSight component that connects event sources like tracing components or CPU cores with each other through a common trigger matrix (CTM). For ARMv8 architecture, a CTI is mandatory for core run control and each core has an individual CTI instance attached to it. OpenOCD has limited support for CTI using the cti group of commands.

Command: cti create cti_name `-dap` dap_name `-ap-num` apn `-baseaddr` base_address ¶

  Creates a CTI instance cti_name on the DAP instance dap_name on MEM-AP apn. On ADIv5 DAP apn is the numeric index of the DAP AP the CTI is connected to. On ADIv6 DAP apn is the base address of the DAP AP the CTI is connected to. The base_address must match the base address of the CTI on the respective MEM-AP. All arguments are mandatory. This creates a new command `$cti_name` which is used for various purposes including additional configuration.

Command: $cti_name enable `on|off` ¶

  Enable (`on`) or disable (`off`) the CTI.

Command: $cti_name dump ¶

  Displays a register dump of the CTI.

Command: $cti_name write reg_name value ¶

  Write value to the CTI register with the symbolic name reg_name.

Command: $cti_name read reg_name ¶

  Print the value read from the CTI register with the symbolic name reg_name.

Command: $cti_name ack event ¶

  Acknowledge a CTI event.

Command: $cti_name channel channel_number operation ¶

  Perform a specific channel operation, the possible operations are: gate, ungate, set, clear and pulse

Command: $cti_name testmode `on|off` ¶

  Enable (`on`) or disable (`off`) the integration test mode of the CTI.

Command: cti names ¶

  Prints a list of names of all CTI objects created. This command is mainly useful in TCL scripting.

### 16.3 Generic ARM ¶

These commands should be available on all ARM processors. They are available in addition to other core-specific commands that may be available.

Command: arm 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: arm disassemble address [count [`thumb`]] ¶

  Disassembles count instructions starting at address. If count is not specified, a single instruction is disassembled. If `thumb` is specified, or the low bit of the address is set, Thumb2 (mixed 16/32-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.)

  Note that all Thumb instructions are Thumb2 instructions, so older processors (without Thumb2 support) will still see correct disassembly of Thumb code. Also, ThumbEE opcodes are the same as Thumb2, with a handful of exceptions. ThumbEE disassembly currently has no explicit support.

Command: arm mcr pX op1 CRn CRm op2 value ¶

  Write value to a coprocessor pX register passing parameters CRn, CRm, opcodes opc1 and opc2, and using the MCR instruction. (Parameter sequence matches the ARM instruction, but omits an ARM register.)

Command: arm mrc pX coproc op1 CRn CRm op2 ¶

  Read a coprocessor pX register passing parameters CRn, CRm, opcodes opc1 and opc2, and the MRC instruction. Returns the result so it can be manipulated by Jim scripts. (Parameter sequence matches the ARM instruction, but omits an ARM register.)

Command: arm reg ¶

  Display a table of all banked core registers, fetching the current value from every core mode if necessary.

Command: arm semihosting [`enable`|`disable`] ¶

  Display status of semihosting, after optionally changing that status.

  Semihosting allows for code executing on an ARM target to use the I/O facilities on the host computer i.e. the system where OpenOCD is running. The target application must be linked against a library implementing the ARM semihosting convention that forwards operation requests by using a special SVC instruction that is trapped at the Supervisor Call vector by OpenOCD.

Command: arm semihosting_redirect (`disable` | `tcp` <port> [`debug`|`stdio`|`all`]) ¶

  Redirect semihosting messages to a specified TCP port.

  This command redirects debug (READC, WRITEC and WRITE0) and stdio (READ, WRITE) semihosting operations to the specified TCP port. The command allows to select which type of operations to redirect (debug, stdio, all (default)).

  Note: for stdio operations, only I/O from/to ’:tt’ file descriptors are redirected.

Command: arm semihosting_cmdline [`enable`|`disable`] ¶

  Set the command line to be passed to the debugger.

      arm semihosting_cmdline argv0 argv1 argv2 ...

  This option lets one set the command line arguments to be passed to the program. The first argument (argv0) is the program name in a standard C environment (argv[0]). Depending on the program (not much programs look at argv[0]), argv0 is ignored and can be any string.

Command: arm semihosting_fileio [`enable`|`disable`] ¶

  Display status of semihosting fileio, after optionally changing that status.

  Enabling this option forwards semihosting I/O to GDB process using the File-I/O remote protocol extension. This is especially useful for interacting with remote files or displaying console messages in the debugger.

Command: arm semihosting_resexit [`enable`|`disable`] ¶

  Enable resumable SEMIHOSTING_SYS_EXIT.

  When SEMIHOSTING_SYS_EXIT is called outside a debug session, things are simple, the openocd process calls exit() and passes the value returned by the target.

  When SEMIHOSTING_SYS_EXIT is called during a debug session, by default execution returns to the debugger, leaving the debugger in a HALT state, similar to the state entered when encountering a break.

  In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT return normally, as any semihosting call, and do not break to the debugger. The standard allows this to happen, but the condition to trigger it is a bit obscure ("by performing an RDI_Execute request or equivalent").

  To make the SEMIHOSTING_SYS_EXIT call return normally, enable this option (default: disabled).

Command: arm semihosting_read_user_param ¶

  Read parameter of the semihosting call from the target. Usable in semihosting-user-cmd-0x10* event handlers, returning a string.

  When the target makes semihosting call with operation number from range 0x100- 0x107, an optional string parameter can be passed to the server. This parameter is valid during the run of the event handlers and is accessible with this command.

Command: arm semihosting_basedir [dir] ¶

  Set the base directory for semihosting I/O, either an absolute path or a path relative to OpenOCD working directory. Use "." for the current directory.

### 16.4 ARMv4 and ARMv5 Architecture ¶

The ARMv4 and ARMv5 architectures are widely used in embedded systems, and introduced core parts of the instruction set in use today. That includes the Thumb instruction set, introduced in the ARMv4T variant.

#### 16.4.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 ARM commands, and any other core-specific commands that may be available.

Command: arm7_9 dbgrq [`enable`|`disable`] ¶

  Displays the value of the flag controlling use of the EmbeddedIce DBGRQ signal to force entry into debug mode, instead of breakpoints. If a boolean parameter is provided, first assigns that flag.

  This should be safe for all but ARM7TDMI-S cores (like NXP LPC). This feature is enabled by default on most ARM9 cores, including ARM9TDMI, ARM920T, and ARM926EJ-S.

Command: arm7_9 dcc_downloads [`enable`|`disable`] ¶

  Displays the value of the flag controlling use of the debug communications channel (DCC) to write larger (>128 byte) amounts of memory. If a boolean parameter is provided, first assigns that flag.

  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`] ¶

  Displays the value of the flag controlling use of memory writes and reads that don’t check completion of the operation. If a boolean parameter is provided, first assigns that flag.

  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.

#### 16.4.2 ARM9 specific commands ¶

ARM9-family cores are built around ARM9TDMI or ARM9E (including ARM9EJS) integer processors. Such cores include the ARM920T, ARM926EJ-S, and ARM966.

Command: arm9 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` `irq` `fiq`.

#### 16.4.3 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 ARM, ARM7/ARM9, and ARM9 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. This uses "physical access" and the register number is as shown in bits 38..33 of table 9-9 in the ARM920T TRM. (Not all registers can be written.)

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

#### 16.4.4 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 ARM, ARM7/ARM9, and ARM9 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.

#### 16.4.5 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 ARM, ARM7/ARM9, and ARM9 commands.

Command: arm966e cp15 regnum [value] ¶

  Display cp15 register regnum; else if a value is provided, that value is written to that register. The six bit regnum values are bits 37..32 from table 7-2 of the ARM966E-S TRM. There is no current control over bits 31..30 from that table, as required for BIST support.

#### 16.4.6 XScale specific commands ¶

Some notes about the debug implementation on the XScale CPUs:

The XScale CPU provides a special debug-only mini-instruction cache (mini-IC) in which exception vectors and target-resident debug handler code are placed by OpenOCD. In order to get access to the CPU, OpenOCD must point vector 0 (the reset vector) to the entry of the debug handler. However, this means that the complete first cacheline in the mini-IC is marked valid, which makes the CPU fetch all exception handlers from the mini-IC, ignoring the code in RAM.

To address this situation, OpenOCD provides the `xscale vector_table` command, which allows the user to explicitly write individual entries to either the high or low vector table stored in the mini-IC.

It is recommended to place a pc-relative indirect branch in the vector table, and put the branch destination somewhere in memory. Doing so makes sure the code in the vector table stays constant regardless of code layout in memory:

    _vectors:
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            ldr     pc,[pc,#0x100-8]
            .org 0x100
            .long real_reset_vector
            .long real_ui_handler
            .long real_swi_handler
            .long real_pf_abort
            .long real_data_abort
            .long 0 /* unused */
            .long real_irq_handler
            .long real_fiq_handler

Alternatively, you may choose to keep some or all of the mini-IC vector table entries synced with those written to memory by your system software. The mini-IC can not be modified while the processor is executing, but for each vector table entry not previously defined using the `xscale vector_table` command, OpenOCD will copy the value from memory to the mini-IC every time execution resumes from a halt. This is done for both high and low vector tables (although the table not in use may not be mapped to valid memory, and in this case that copy operation will silently fail). This means that you will need to briefly halt execution at some strategic point during system start-up; e.g., after the software has initialized the vector table, but before exceptions are enabled. A breakpoint can be used to accomplish this once the appropriate location in the start-up code has been identified. A watchpoint over the vector table region is helpful in finding the location if you’re not sure. Note that the same situation exists any time the vector table is modified by the system software.

The debug handler must be placed somewhere in the address space using the `xscale debug_handler` command. The allowed locations for the debug handler are either (0x800 - 0x1fef800) or (0xfe000800 - 0xfffff800). The default value is 0xfe000800.

XScale has resources to support two hardware breakpoints and two watchpoints. However, the following restrictions on watchpoint functionality apply: (1) the value and mask arguments to the `wp` command are not supported, (2) the watchpoint length must be a power of two and not less than four, and can not be greater than the watchpoint address, and (3) a watchpoint with a length greater than four consumes all the watchpoint hardware resources. This means that at any one time, you can have enabled either two watchpoints with a length of four, or one watchpoint with a length greater than four.

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`]] ¶

  Displays the trace buffer status, after optionally enabling or disabling the trace buffer and modifying 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.

  The mask bits correspond with bit 16..23 in the DCSR:

      0x01    Trap Reset
      0x02    Trap Undefined Instructions
      0x04    Trap Software Interrupt
      0x08    Trap Prefetch Abort
      0x10    Trap Data Abort
      0x20    reserved
      0x40    Trap IRQ
      0x80    Trap FIQ

Command: xscale vector_table [(`low`|`high`) index value] ¶

  Set an entry in the mini-IC vector table. There are two tables: one for low vectors (at 0x00000000), and one for high vectors (0xFFFF0000), each holding the 8 exception vectors. index can be 1-7, because vector 0 points to the debug handler entry and can not be overwritten. value holds the 32-bit opcode that is placed in the mini-IC.

  Without arguments, the current settings are displayed.

### 16.5 ARMv6 Architecture ¶

#### 16.5.1 ARM11 specific commands ¶

Command: arm11 memwrite burst [`enable`|`disable`] ¶

  Displays the value of the memwrite burst-enable flag, which is enabled by default. If a boolean parameter is provided, first assigns that flag. Burst writes are only used for memory writes larger than 1 word. They improve performance by assuming that the CPU has read each data word over JTAG and completed its write before the next word arrives, instead of polling for a status flag to verify that completion. This is usually safe, because JTAG runs much slower than the CPU.

Command: arm11 memwrite error_fatal [`enable`|`disable`] ¶

  Displays the value of the memwrite error_fatal flag, which is enabled by default. If a boolean parameter is provided, first assigns that flag. When set, certain memory write errors cause earlier transfer termination.

Command: arm11 step_irq_enable [`enable`|`disable`] ¶

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

Command: arm11 vcr [value] ¶

  Displays the value of the Vector Catch Register (VCR), coprocessor 14 register 7. If value is defined, first assigns that.

  Vector Catch hardware provides dedicated breakpoints for certain hardware events. The specific bit values are core-specific (as in fact is using coprocessor 14 register 7 itself) but all current ARM11 cores except the ARM1176 use the same six bits.

### 16.6 ARMv7 and ARMv8 Architecture ¶

#### 16.6.1 ARMv7-A specific commands ¶

Command: cortex_a cache_info ¶

  display information about target caches

Command: cortex_a dacrfixup [`on`|`off`] ¶

  Work around issues with software breakpoints when the program text is mapped read-only by the operating system. This option sets the CP15 DACR to "all-manager" to bypass MMU permission checks on memory access. Defaults to ’off’.

Command: cortex_a dbginit ¶

  Initialize core debug Enables debug by unlocking the Software Lock and clearing sticky powerdown indications

Command: cortex_a smp [on|off] ¶

  Display/set the current SMP mode

Command: cortex_a smp_gdb [core_id] ¶

  Display/set the current core displayed in GDB

Command: cortex_a maskisr [`on`|`off`] ¶

  Selects whether interrupts will be processed when single stepping

Command: cache_config l2x [base way] ¶

  configure l2x cache

Command: cortex_a mmu dump [`0`|`1`|`addr` address [`num_entries`]] ¶

  Dump the MMU translation table from TTB0 or TTB1 register, or from physical memory location address. When dumping the table from address, print at most num_entries page table entries. num_entries is optional, if omitted, the maximum possible (4096) entries are printed.

#### 16.6.2 ARMv7-R specific commands ¶

Command: cortex_r4 dbginit ¶

  Initialize core debug Enables debug by unlocking the Software Lock and clearing sticky powerdown indications

Command: cortex_r4 maskisr [`on`|`off`] ¶

  Selects whether interrupts will be processed when single stepping

#### 16.6.3 ARM CoreSight TPIU and SWO specific commands ¶

ARM CoreSight provides several modules to generate debugging information internally (ITM, DWT and ETM). Their output is directed through TPIU or SWO modules to be captured externally either on an SWO pin (this configuration is called SWV) or on a synchronous parallel trace port.

ARM CoreSight provides independent HW blocks named TPIU and SWO each with its own functionality. Embedded in Cortex-M3 and M4, ARM provides an optional HW block that includes both TPIU and SWO functionalities and is again named TPIU, which causes quite some confusion. The registers map of all the TPIU and SWO implementations allows using a single driver that detects at runtime the features available.

The `tpiu` is used for either TPIU or SWO. A convenient alias `swo` is available to help distinguish, in scripts, the commands for SWO from the commands for TPIU.

Command: swo ... ¶

  Alias of `tpiu ...`. Can be used in scripts to distinguish the commands for SWO from the commands for TPIU.

Command: tpiu create tpiu_name configparams... ¶

  Creates a TPIU or a SWO object. The two commands are equivalent. Add the object in a list and add new commands (`tpiu_name`) which are used for various purposes including additional configuration.

  - tpiu_name – the name of the TPIU or SWO object. This name is also used to create the object’s command, referred to here as `$tpiu_name`, and in other places where the TPIU or SWO needs to be identified.
  - configparams – all parameters accepted by `$tpiu_name configure` are permitted.

    You must set here the AP and MEM_AP base_address through `-dap dap_name`, `-ap-num ap_number` and `-baseaddr base_address`.

Command: tpiu names ¶

  Lists all the TPIU or SWO objects created so far. The two commands are equivalent.

Command: tpiu init ¶

  Initialize all registered TPIU and SWO. The two commands are equivalent. These commands are used internally during initialization. They can be issued at any time after the initialization, too.

Command: $tpiu_name cget queryparm ¶

  Each configuration parameter accepted by `$tpiu_name configure` can be individually queried, to return its current value. The queryparm is a parameter name accepted by that command, such as `-dap`.

Command: $tpiu_name configure configparams... ¶

  The options accepted by this command may also be specified as parameters to `tpiu create`. Their values can later be queried one at a time by using the `$tpiu_name cget` command.

  - `-dap` dap_name – names the DAP used to access this TPIU. See DAP declaration, on how to create and manage DAP instances.
  - `-ap-num` ap_number – sets DAP access port for TPIU. On ADIv5 DAP ap_number is the numeric index of the DAP AP the TPIU is connected to. On ADIv6 DAP ap_number is the base address of the DAP AP the TPIU is connected to.
  - `-baseaddr` base_address – sets the TPIU base_address where to access the TPIU in the DAP AP memory space.
  - `-protocol` (`sync`|`uart`|`manchester`) – sets the protocol used for trace data:
    - `sync` – synchronous parallel trace output mode, using port_width data bits (default);
    - `uart` – use asynchronous SWO mode with NRZ (same as regular UART 8N1) coding;
    - `manchester` – use asynchronous SWO mode with Manchester coding.
  - `-event` event_name event_body – assigns an event handler, a TCL string which is evaluated when the event is triggered. The events `pre-enable`, `post-enable`, `pre-disable` and `post-disable` are defined for TPIU/SWO. A typical use case for the event `pre-enable` is to enable the trace clock of the TPIU.
  - `-output` (`external`|`:`port|filename|`-`) – specifies the destination of the trace data:
    - `external` – configure TPIU/SWO to let user capture trace output externally, either with an additional UART or with a logic analyzer (default);
    - `-` – configure TPIU/SWO and debug adapter to gather trace data and forward it to `tcl_trace` command;
    - `:`port – configure TPIU/SWO and debug adapter to gather trace data, open a TCP server at port port and send the trace data to each connected client;
    - filename – configure TPIU/SWO and debug adapter to gather trace data and append it to filename, which can be either a regular file or a named pipe.
  - `-traceclk` TRACECLKIN_freq – mandatory parameter. Specifies the frequency in Hz of the trace clock. For the TPIU embedded in Cortex-M3 or M4, this is usually the same frequency as HCLK. For protocol `sync` this is twice the frequency of the pin data rate.
  - `-pin-freq` trace_freq – specifies the expected data rate in Hz of the SWO pin. Parameter used only on protocols `uart` and `manchester`. Can be omitted to let the adapter driver select the maximum supported rate automatically.
  - `-port-width` port_width – sets to port_width the width of the synchronous parallel port used for trace output. Parameter used only on protocol `sync`. If not specified, default value is 1.
  - `-formatter` (`0`|`1`) – specifies if the formatter should be enabled. Parameter used only on protocol `sync`. If not specified, default value is 0.

Command: $tpiu_name enable ¶

  Uses the parameters specified by the previous `$tpiu_name configure` to configure and enable the TPIU or the SWO. If required, the adapter is also configured and enabled to receive the trace data. This command can be used before `init`, but it will take effect only after the `init`.

Command: $tpiu_name disable ¶

  Disable the TPIU or the SWO, terminating the receiving of the trace data.

Example usage:

1. STM32L152 board is programmed with an application that configures PLL to provide core clock with 24MHz frequency; to use ITM output it’s enough to:

       #include <libopencm3/cm3/itm.h>
           ...
           	ITM_STIM8(0) = c;
           ...

   (the most obvious way is to use the first stimulus port for printf, for that this ITM_STIM8 assignment can be used inside _write(); to make it blocking to avoid data loss, add `while (!(ITM_STIM8(0) & ITM_STIM_FIFOREADY));`);

2. An FT2232H UART is connected to the SWO pin of the board;
3. Commands to configure UART for 12MHz baud rate:

       $ setserial /dev/ttyUSB1 spd_cust divisor 5
       $ stty -F /dev/ttyUSB1 38400

   (FT2232H’s base frequency is 60MHz, spd_cust allows to alias 38400 baud with our custom divisor to get 12MHz)

4. `itmdump -f /dev/ttyUSB1 -d1`
5. OpenOCD invocation line:

       openocd -f interface/stlink.cfg \
       -c "transport select hla_swd" \
       -f target/stm32l1.cfg \
       -c "stm32l1.tpiu configure -protocol uart" \
       -c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \
       -c "stm32l1.tpiu enable"

#### 16.6.4 ARMv7-M specific commands ¶

Command: itm port port (`0`|`1`|`on`|`off`) ¶

  Enable or disable trace output for ITM stimulus port (counting from 0). Port 0 is enabled on target creation automatically.

Command: itm ports (`0`|`1`|`on`|`off`) ¶

  Enable or disable trace output for all ITM stimulus ports.

#### 16.6.5 Cortex-M specific commands ¶

Command: cortex_m maskisr (`auto`|`on`|`off`|`steponly`) ¶

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

  The `auto` option handles interrupts during stepping in a way that they get served but don’t disturb the program flow. The step command first allows pending interrupt handlers to execute, then disables interrupts and steps over the next instruction where the core was halted. After the step interrupts are enabled again. If the interrupt handlers don’t complete within 500ms, the step command leaves with the core running.

  The `steponly` option disables interrupts during single-stepping but enables them during normal execution. This can be used as a partial workaround for 702596 erratum in Cortex-M7 r0p1. See "Cortex-M7 (AT610) and Cortex-M7 with FPU (AT611) Software Developer Errata Notice" from ARM for further details.

  Note that a free hardware (FPB) breakpoint is required for the `auto` option. If no breakpoint is available at the time of the step, then the step is taken with interrupts enabled, i.e. the same way the `off` option does.

  Default is `auto`.

Command: cortex_m vector_catch [`all`|`none`|list] ¶

  Vector Catch hardware provides dedicated breakpoints for certain hardware events.

  Parameters request interception of `all` of these hardware event vectors, `none` of them, or one or more of the following: `hard_err` for a HardFault exception; `mm_err` for a MemManage exception; `bus_err` for a BusFault exception; `irq_err`, `state_err`, `chk_err`, or `nocp_err` for various UsageFault exceptions; or `reset`. If NVIC setup code does not enable them, MemManage, BusFault, and UsageFault exceptions are mapped to HardFault. UsageFault checks for divide-by-zero and unaligned access must also be explicitly enabled.

  This finishes by listing the current vector catch configuration.

Command: cortex_m reset_config (`sysresetreq`|`vectreset`) ¶

  Control reset handling if hardware srst is not fitted See reset_config.

  - `sysresetreq` use AIRCR SYSRESETREQ to reset system.
  - `vectreset` use AIRCR VECTRESET to reset system (default).

  Using `vectreset` is a safe option for Cortex-M3, M4 and M7 cores. This however has the disadvantage of only resetting the core, all peripherals are unaffected. A solution would be to use a `reset-init` event handler to manually reset the peripherals. See Target Events.

  Cortex-M0, M0+ and M1 do not support `vectreset`, use `sysresetreq` instead.

#### 16.6.6 ARMv8-A specific commands ¶

Command: aarch64 cache_info ¶

  Display information about target caches

Command: aarch64 dbginit ¶

  This command enables debugging by clearing the OS Lock and sticky power-down and reset indications. It also establishes the expected, basic cross-trigger configuration the aarch64 target code relies on. In a configuration file, the command would typically be called from a `reset-end` or `reset-deassert-post` handler, to re-enable debugging after a system reset. However, normally it is not necessary to use the command at all.

Command: aarch64 disassemble address [count] ¶

  Disassembles count instructions starting at address. If count is not specified, a single instruction is disassembled.

Command: aarch64 smp [on|off] ¶

  Display, enable or disable SMP handling mode. The state of SMP handling influences the way targets in an SMP group are handled by the run control. With SMP handling enabled, issuing halt or resume to one core will trigger halting or resuming of all cores in the group. The command `target smp` defines which targets are in the SMP group. With SMP handling disabled, all targets need to be treated individually.

Command: aarch64 maskisr [`on`|`off`] ¶

  Selects whether interrupts will be processed when single stepping. The default configuration is `on`.

Command: $target_name catch_exc [`off`|`sec_el1`|`sec_el3`|`nsec_el1`|`nsec_el2`]+ ¶

  Cause `$target_name` to halt when an exception is taken. Any combination of Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is valid. The target `$target_name` will halt before taking the exception. In order to resume the target, the exception catch must be disabled again with `$target_name catch_exc off`. Issuing the command without options prints the current configuration.

### 16.7 EnSilica eSi-RISC Architecture ¶

eSi-RISC is a highly configurable microprocessor architecture for embedded systems provided by EnSilica. (See: http://www.ensilica.com/risc-ip/.)

#### 16.7.1 eSi-RISC Configuration ¶

Command: esirisc cache_arch (`harvard`|`von_neumann`) ¶

  Configure the caching architecture. Targets with the `UNIFIED_ADDRESS_SPACE` option disabled employ a Harvard architecture. By default, `von_neumann` is assumed.

Command: esirisc hwdc (`all`|`none`|mask ...) ¶

  Configure hardware debug control. The HWDC register controls which exceptions return control back to the debugger. Possible masks are `all`, `none`, `reset`, `interrupt`, `syscall`, `error`, and `debug`. By default, `reset`, `error`, and `debug` are enabled.

#### 16.7.2 eSi-RISC Operation ¶

Command: esirisc flush_caches ¶

  Flush instruction and data caches. This command requires that the target is halted when the command is issued and configured with an instruction or data cache.

#### 16.7.3 eSi-Trace Configuration ¶

eSi-RISC targets may be configured with support for instruction tracing. Trace data may be written to an in-memory buffer or FIFO. If a FIFO is configured, DMA is typically employed to move trace data off-device using a high-speed peripheral (eg. SPI). Collected trace data is encoded in one of three different formats. At a minimum, `esirisc trace buffer` or `esirisc trace fifo` must be issued along with `esirisc trace format` before trace data can be collected.

OpenOCD provides rudimentary analysis of collected trace data. If more detail is needed, collected trace data can be dumped to a file and processed by external tooling.

> Issues: OpenOCD is unable to process trace data sent to a FIFO. A potential workaround for this issue is to configure DMA to copy trace data to an in-memory buffer, which can then be passed to the `esirisc trace analyze` and `esirisc trace dump` commands.

> It is possible to corrupt trace data when using a FIFO if the peripheral responsible for draining data from the FIFO is not fast enough. This can be managed by enabling flow control, however this can impact timing-sensitive software operation on the CPU.

Command: esirisc trace buffer address size [`wrap`] ¶

  Configure trace buffer using the provided address and size. If the `wrap` option is specified, trace collection will continue once the end of the buffer is reached. By default, wrap is disabled.

Command: esirisc trace fifo address ¶

  Configure trace FIFO using the provided address.

Command: esirisc trace flow_control (`enable`|`disable`) ¶

  Enable or disable stalling the CPU to collect trace data. By default, flow control is disabled.

Command: esirisc trace format (`full`|`branch`|`icache`) pc_bits ¶

  Configure trace format and number of PC bits to be captured. `pc_bits` must be within 1 and 31 as the LSB is not collected. If external tooling is used to analyze collected trace data, these values must match.

  Supported trace formats:

  - `full` capture full trace data, allowing execution history and timing to be determined.
  - `branch` capture taken branch instructions and branch target addresses.
  - `icache` capture instruction cache misses.

Command: esirisc trace trigger start (`condition`) [start_data start_mask] ¶

  Configure trigger start condition using the provided start data and mask. A brief description of each condition is provided below; for more detail on how these values are used, see the eSi-RISC Architecture Manual.

  Supported conditions:

  - `none` manual tracing (see `esirisc trace start`).
  - `pc` start tracing if the PC matches start data and mask.
  - `load` start tracing if the effective address of a load instruction matches start data and mask.
  - `store` start tracing if the effective address of a store instruction matches start data and mask.
  - `exception` start tracing if the EID of an exception matches start data and mask.
  - `eret` start tracing when an `ERET` instruction is executed.
  - `wait` start tracing when a `WAIT` instruction is executed.
  - `stop` start tracing when a `STOP` instruction is executed.
  - `high` start tracing when an external signal is a logical high.
  - `low` start tracing when an external signal is a logical low.

Command: esirisc trace trigger stop (`condition`) [stop_data stop_mask] ¶

  Configure trigger stop condition using the provided stop data and mask. A brief description of each condition is provided below; for more detail on how these values are used, see the eSi-RISC Architecture Manual.

  Supported conditions:

  - `none` manual tracing (see `esirisc trace stop`).
  - `pc` stop tracing if the PC matches stop data and mask.
  - `load` stop tracing if the effective address of a load instruction matches stop data and mask.
  - `store` stop tracing if the effective address of a store instruction matches stop data and mask.
  - `exception` stop tracing if the EID of an exception matches stop data and mask.
  - `eret` stop tracing when an `ERET` instruction is executed.
  - `wait` stop tracing when a `WAIT` instruction is executed.
  - `stop` stop tracing when a `STOP` instruction is executed.

Command: esirisc trace trigger delay (`trigger`) [cycles] ¶

  Configure trigger start/stop delay in clock cycles.

  Supported triggers:

  - `none` no delay to start or stop collection.
  - `start` delay `cycles` after trigger to start collection.
  - `stop` delay `cycles` after trigger to stop collection.
  - `both` delay `cycles` after both triggers to start or stop collection.

#### 16.7.4 eSi-Trace Operation ¶

Command: esirisc trace init ¶

  Initialize trace collection. This command must be called any time the configuration changes. If a trace buffer has been configured, the contents will be overwritten when trace collection starts.

Command: esirisc trace info ¶

  Display trace configuration.

Command: esirisc trace status ¶

  Display trace collection status.

Command: esirisc trace start ¶

  Start manual trace collection.

Command: esirisc trace stop ¶

  Stop manual trace collection.

Command: esirisc trace analyze [address size] ¶

  Analyze collected trace data. This command may only be used if a trace buffer has been configured. If a trace FIFO has been configured, trace data must be copied to an in-memory buffer identified by the `address` and `size` options using DMA.

Command: esirisc trace dump [address size] `filename` ¶

  Dump collected trace data to file. This command may only be used if a trace buffer has been configured. If a trace FIFO has been configured, trace data must be copied to an in-memory buffer identified by the `address` and `size` options using DMA.

### 16.8 Intel Architecture ¶

Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32 (Pentium x86 ISA) compatible SoC. The core CPU in the X10xx is codenamed Lakemont. Lakemont version 1 (LMT1) is used in X10xx. The CPU TAP (Lakemont TAP) is used for software debug and the CLTAP is used for SoC level operations. Useful docs are here: https://communities.intel.com/community/makers/documentation

- Intel Quark SoC X1000 OpenOCD/GDB/Eclipse App Note (web search for doc num 330015)
- Intel Quark SoC X1000 Debug Operations User Guide (web search for doc num 329866)
- Intel Quark SoC X1000 Datasheet (web search for doc num 329676)

#### 16.8.1 x86 32-bit specific commands ¶

The three main address spaces for x86 are memory, I/O and configuration space. These commands allow a user to read and write to the 64Kbyte I/O address space.

Command: x86_32 idw address ¶

  Display the contents of a 32-bit I/O port from address range 0x0000 - 0xffff.

Command: x86_32 idh address ¶

  Display the contents of a 16-bit I/O port from address range 0x0000 - 0xffff.

Command: x86_32 idb address ¶

  Display the contents of a 8-bit I/O port from address range 0x0000 - 0xffff.

Command: x86_32 iww address ¶

  Write the contents of a 32-bit I/O port to address range 0x0000 - 0xffff.

Command: x86_32 iwh address ¶

  Write the contents of a 16-bit I/O port to address range 0x0000 - 0xffff.

Command: x86_32 iwb address ¶

  Write the contents of a 8-bit I/O port to address range 0x0000 - 0xffff.

### 16.9 OpenRISC Architecture ¶

The OpenRISC CPU is a soft core. It is used in a programmable SoC which can be configured with any of the TAP / Debug Unit available.

#### 16.9.1 TAP and Debug Unit selection commands ¶

Command: tap_select (`vjtag`|`mohor`|`xilinx_bscan`) ¶

  Select between the Altera Virtual JTAG , Xilinx Virtual JTAG and Mohor TAP.

Command: du_select (`adv`|`mohor`) [option] ¶

  Select between the Advanced Debug Interface and the classic one.

  An option can be passed as a second argument to the debug unit.

  When using the Advanced Debug Interface, option = 1 means the RTL core is configured with ADBG_USE_HISPEED = 1. This configuration skips status checking between bytes while doing read or write bursts.

#### 16.9.2 Registers commands ¶

Command: addreg [name] [address] [feature] [reg_group] ¶

  Add a new register in the cpu register list. This register will be included in the generated target descriptor file.

  [feature] must be "org.gnu.gdb.or1k.group[0..10]".

  [reg_group] can be anything. The default register list defines "system", "dmmu", "immu", "dcache", "icache", "mac", "debug", "perf", "power", "pic" and "timer" groups.

  example:

      addreg rtest 0x1234 org.gnu.gdb.or1k.group0 system

### 16.10 RISC-V Architecture ¶

RISC-V is a free and open ISA. OpenOCD supports JTAG debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 32 harts. (It’s possible to increase this limit to 1024 by changing RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the RISC-V Debug Specification, but there is also support for legacy targets that implement version 0.11.

#### 16.10.1 RISC-V Terminology ¶

A hart is a hardware thread. A hart may share resources (eg. FPU) with another hart, or may be a separate core. RISC-V treats those the same, and OpenOCD exposes each hart as a separate core.

#### 16.10.2 Vector Registers ¶

For harts that implement the vector extension, OpenOCD provides access to the relevant CSRs, as well as the vector registers (v0-v31). The size of each vector register is dependent on the value of vlenb. RISC-V allows each vector register to be divided into selected-width elements, and this division can be changed at run-time. Because OpenOCD cannot update register definitions at run-time, it exposes each vector register to gdb as a union of fields of vectors so that users can easily access individual bytes, shorts, words, longs, and quads inside each vector register. It is left to gdb or higher-level debuggers to present this data in a more intuitive format.

In the XML register description, the vector registers (when vlenb=16) look as follows:

    <feature name="org.gnu.gdb.riscv.vector">
    <vector id="bytes" type="uint8" count="16"/>
    <vector id="shorts" type="uint16" count="8"/>
    <vector id="words" type="uint32" count="4"/>
    <vector id="longs" type="uint64" count="2"/>
    <vector id="quads" type="uint128" count="1"/>
    <union id="riscv_vector">
    <field name="b" type="bytes"/>
    <field name="s" type="shorts"/>
    <field name="w" type="words"/>
    <field name="l" type="longs"/>
    <field name="q" type="quads"/>
    </union>
    <reg name="v0" bitsize="128" regnum="4162" save-restore="no"
            type="riscv_vector" group="vector"/>
    ...
    <reg name="v31" bitsize="128" regnum="4193" save-restore="no"
            type="riscv_vector" group="vector"/>
    </feature>

#### 16.10.3 RISC-V Debug Configuration Commands ¶

Config Command: riscv expose_csrs n[-m|=name] [...] ¶

  Configure which CSRs to expose in addition to the standard ones. The CSRs to expose can be specified as individual register numbers or register ranges (inclusive). For the individually listed CSRs, a human-readable name can optionally be set using the `n=name` syntax, which will get `csr_` prepended to it. If no name is provided, the register will be named `csr<n>`.

  By default OpenOCD attempts to expose only CSRs that are mentioned in a spec, and then only if the corresponding extension appears to be implemented. This command can be used if OpenOCD gets this wrong, or if the target implements custom CSRs.

      # Expose a single RISC-V CSR number 128 under the name "csr128":
      $_TARGETNAME expose_csrs 128

      # Expose multiple RISC-V CSRs 128..132 under names "csr128" through "csr132":
      $_TARGETNAME expose_csrs 128-132

      # Expose a single RISC-V CSR number 1996 under custom name "csr_myregister":
      $_TARGETNAME expose_csrs 1996=myregister

Config Command: riscv expose_custom n[-m|=name] [...] ¶

  The RISC-V Debug Specification allows targets to expose custom registers through abstract commands. (See Section 3.5.1.1 in that document.) This command configures individual registers or register ranges (inclusive) that shall be exposed. Number 0 indicates the first custom register, whose abstract command number is 0xc000. For individually listed registers, a human-readable name can be optionally provided using the `n=name` syntax, which will get `custom_` prepended to it. If no name is provided, the register will be named `custom<n>`.

      # Expose one RISC-V custom register with number 0xc010 (0xc000 + 16)
      # under the name "custom16":
      $_TARGETNAME expose_custom 16

      # Expose a range of RISC-V custom registers with numbers 0xc010 .. 0xc018
      # (0xc000+16 .. 0xc000+24) under the names "custom16" through "custom24":
      $_TARGETNAME expose_custom 16-24

      # Expose one RISC-V custom register with number 0xc020 (0xc000 + 32) under
      # user-defined name "custom_myregister":
      $_TARGETNAME expose_custom 32=myregister

Command: riscv info ¶

  Displays some information OpenOCD detected about the target.

Command: riscv reset_delays [wait] ¶

  OpenOCD learns how many Run-Test/Idle cycles are required between scans to avoid encountering the target being busy. This command resets those learned values after ‘wait‘ scans. It’s only useful for testing OpenOCD itself.

Command: riscv set_command_timeout_sec [seconds] ¶

  Set the wall-clock timeout (in seconds) for individual commands. The default should work fine for all but the slowest targets (eg. simulators).

Command: riscv set_reset_timeout_sec [seconds] ¶

  Set the maximum time to wait for a hart to come out of reset after reset is deasserted.

Command: riscv set_mem_access method1 [method2] [method3] ¶

  Specify which RISC-V memory access method(s) shall be used, and in which order of priority. At least one method must be specified.

  Available methods are:

  - `progbuf` - Use RISC-V Debug Program Buffer to access memory.
  - `sysbus` - Access memory via RISC-V Debug System Bus interface.
  - `abstract` - Access memory via RISC-V Debug abstract commands.

  By default, all memory access methods are enabled in the following order: `progbuf sysbus abstract`.

  This command can be used to change the memory access methods if the default behavior is not suitable for a particular target.

Command: riscv set_enable_virtual on|off ¶

  When on, memory accesses are performed on physical or virtual memory depending on the current system configuration. When off (default), all memory accessses are performed on physical memory.

Command: riscv set_enable_virt2phys on|off ¶

  When on (default), memory accesses are performed on physical or virtual memory depending on the current satp configuration. When off, all memory accessses are performed on physical memory.

Command: riscv resume_order normal|reversed ¶

  Some software assumes all harts are executing nearly continuously. Such software may be sensitive to the order that harts are resumed in. On harts that don’t support hasel, this option allows the user to choose the order the harts are resumed in. If you are using this option, it’s probably masking a race condition problem in your code.

  Normal order is from lowest hart index to highest. This is the default behavior. Reversed order is from highest hart index to lowest.

Command: riscv set_ir (`idcode`|`dtmcs`|`dmi`) [value] ¶

  Set the IR value for the specified JTAG register. This is useful, for example, when using the existing JTAG interface on a Xilinx FPGA by way of BSCANE2 primitives that only permit a limited selection of IR values.

  When utilizing version 0.11 of the RISC-V Debug Specification, `dtmcs` and `dmi` set the IR values for the DTMCONTROL and DBUS registers, respectively.

Command: riscv use_bscan_tunnel value ¶

  Enable or disable use of a BSCAN tunnel to reach DM. Supply the width of the DM transport TAP’s instruction register to enable. Supply a value of 0 to disable.

Command: riscv set_ebreakm on|off ¶

  Control dcsr.ebreakm. When on (default), M-mode ebreak instructions trap to OpenOCD. When off, they generate a breakpoint exception handled internally.

Command: riscv set_ebreaks on|off ¶

  Control dcsr.ebreaks. When on (default), S-mode ebreak instructions trap to OpenOCD. When off, they generate a breakpoint exception handled internally.

Command: riscv set_ebreaku on|off ¶

  Control dcsr.ebreaku. When on (default), U-mode ebreak instructions trap to OpenOCD. When off, they generate a breakpoint exception handled internally.

#### 16.10.4 RISC-V Authentication Commands ¶

The following commands can be used to authenticate to a RISC-V system. Eg. a trivial challenge-response protocol could be implemented as follows in a configuration file, immediately following `init`:

    set challenge [riscv authdata_read]
    riscv authdata_write [expr {$challenge + 1}]

Command: riscv authdata_read ¶

  Return the 32-bit value read from authdata.

Command: riscv authdata_write value ¶

  Write the 32-bit value to authdata.

#### 16.10.5 RISC-V DMI Commands ¶

The following commands allow direct access to the Debug Module Interface, which can be used to interact with custom debug features.

Command: riscv dmi_read address ¶

  Perform a 32-bit DMI read at address, returning the value.

Command: riscv dmi_write address value ¶

  Perform a 32-bit DMI write of value at address.

### 16.11 ARC Architecture ¶

Synopsys DesignWare ARC Processors are a family of 32-bit CPUs that SoC designers can optimize for a wide range of uses, from deeply embedded to high-performance host applications in a variety of market segments. See more at: http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx. OpenOCD currently supports ARC EM processors. There is a set ARC-specific OpenOCD commands that allow low-level access to the core and provide necessary support for ARC extensibility and configurability capabilities. ARC processors has much more configuration capabilities than most of the other processors and in addition there is an extension interface that allows SoC designers to add custom registers and instructions. For the OpenOCD that mostly means that set of core and AUX registers in target will vary and is not fixed for a particular processor model. To enable extensibility several TCL commands are provided that allow to describe those optional registers in OpenOCD configuration files. Moreover those commands allow for a dynamic target features discovery.

#### 16.11.1 General ARC commands ¶

Config Command: arc add-reg configparams ¶

  Add a new register to processor target. By default newly created register is marked as not existing. configparams must have following required arguments:

  - `-name` name
    Name of a register.
  - `-num` number
    Architectural register number: core register number or AUX register number.
  - `-feature` XML_feature
    Name of GDB XML target description feature.

  configparams may have following optional arguments:

  - `-gdbnum` number
    GDB register number. It is recommended to not assign GDB register number manually, because there would be a risk that two register will have same number. When register GDB number is not set with this option, then register will get a previous register number + 1. This option is required only for those registers that must be at particular address expected by GDB.
  - `-core`
    This option specifies that register is a core registers. If not - this is an AUX register. AUX registers and core registers reside in different address spaces.
  - `-bcr`
    This options specifies that register is a BCR register. BCR means Build Configuration Registers - this is a special type of AUX registers that are read only and non-volatile, that is - they never change their value. Therefore OpenOCD never invalidates values of those registers in internal caches. Because BCR is a type of AUX registers, this option cannot be used with `-core`.
  - `-type` type_name
    Name of type of this register. This can be either one of the basic GDB types, or a custom types described with `arc add-reg-type-[flags|struct]`.
  - `-g`
    If specified then this is a "general" register. General registers are always read by OpenOCD on context save (when core has just been halted) and is always transferred to GDB client in a response to g-packet. Contrary to this, non-general registers are read and sent to GDB client on-demand. In general it is not recommended to apply this option to custom registers.

Config Command: arc add-reg-type-flags -name name flags... ¶

  Adds new register type of “flags” class. “Flags” types can contain only one-bit fields. Each flag definition looks like `-flag name bit-position`.

Config Command: arc add-reg-type-struct -name name structs... ¶

  Adds new register type of “struct” class. “Struct” types can contain either bit-fields or fields of other types, however at the moment only bit fields are supported. Structure bit field definition looks like `-bitfield name startbit endbit`.

Command: arc get-reg-field reg-name field-name ¶

  Returns value of bit-field in a register. Register must be “struct” register type, See add-reg-type-struct. command definition.

Command: arc set-reg-exists reg-names... ¶

  Specify that some register exists. Any amount of names can be passed as an argument for a single command invocation.

#### 16.11.2 ARC JTAG commands ¶

Command: arc jtag set-aux-reg regnum value ¶

  This command writes value to AUX register via its number. This command access register in target directly via JTAG, bypassing any OpenOCD internal caches, therefore it is unsafe to use if that register can be operated by other means.

Command: arc jtag set-core-reg regnum value ¶

  This command is similar to `arc jtag set-aux-reg` but is for core registers.

Command: arc jtag get-aux-reg regnum ¶

  This command returns the value storded in AUX register via its number. This commands access register in target directly via JTAG, bypassing any OpenOCD internal caches, therefore it is unsafe to use if that register can be operated by other means.

Command: arc jtag get-core-reg regnum ¶

  This command is similar to `arc jtag get-aux-reg` but is for core registers.

### 16.12 STM8 Architecture ¶

STM8 is a 8-bit microcontroller platform from STMicroelectronics, based on a proprietary 8-bit core architecture.

OpenOCD supports debugging STM8 through the STMicroelectronics debug protocol SWIM, see SWIM.

### 16.13 Xtensa Architecture ¶

Xtensa is a highly-customizable, user-extensible microprocessor and DSP architecture for complex embedded systems provided by Cadence Design Systems, Inc. See the Tensilica IP website for additional information and documentation.

OpenOCD supports generic Xtensa processor implementations which can be customized by providing a core-specific configuration file which describes every enabled Xtensa architecture option, e.g. number of address registers, exceptions, reduced size instructions support, memory banks configuration etc. OpenOCD also supports SMP configurations for Xtensa processors with any number of cores and allows configuring their debug interconnect (termed "break/stall networks"), which control how debug signals are distributed among cores. Xtensa "break networks" are compatible with ARM’s Cross Trigger Interface (CTI). OpenOCD implements both generic Xtensa targets as well as several Espressif Xtensa-based chips from the ESP32 family.

OCD sessions for Xtensa processor and DSP targets are accessed via the Xtensa Debug Module (XDM), which provides external connectivity either through a traditional JTAG interface or an ARM DAP interface. If used, the DAP interface can control Xtensa targets through JTAG or SWD probes.

#### 16.13.1 Xtensa Core Configuration ¶

Due to the high level of configurability in Xtensa cores, the Xtensa target configuration comprises two categories:

1. Base Xtensa support common to all core configurations, and
2. Core-specific support as configured for individual cores.

All common Xtensa support is built into the OpenOCD Xtensa target layer and is enabled through a combination of TCL scripts: the target-specific `target/xtensa.cfg` and a board-specific `board/xtensa-*.cfg`, similar to other target architectures.

Importantly, core-specific configuration information must be provided by the user, and takes the form of an `xtensa-core-XXX.cfg` TCL script that defines the core’s configurable features through a series of Xtensa configuration commands (detailed below).

This core-specific `xtensa-core-XXX.cfg` file is typically either:

- Located within the Xtensa core configuration build as `src/config/xtensa-core-openocd.cfg`, or
- Generated by running the command `xt-gdb --dump-oocd-config` from the Xtensa processor tool-chain’s command-line tools.

NOTE: `xtensa-core-XXX.cfg` must match the target Xtensa hardware connected to OpenOCD.

Some example Xtensa configurations are bundled with OpenOCD for reference:

- Cadence Palladium VDebug emulation target. The user can combine their `xtensa-core-XXX.cfg` with the provided `board/xtensa-palladium-vdebug.cfg` to debug an emulated Xtensa RTL design.
- NXP MIMXRT685-EVK evaluation kit. The relevant configuration files are `board/xtensa-rt685-jlink.cfg` and `board/xtensa-core-nxp_rt600.cfg`. Additional information is provided by NXP.

#### 16.13.2 Xtensa Configuration Commands ¶

Config Command: xtensa xtdef (`LX`|`NX`) ¶

  Configure the Xtensa target architecture. Currently, Xtensa support is limited to LX6, LX7, and NX cores.

Config Command: xtensa xtopt option value ¶

  Configure Xtensa target options that are relevant to the debug subsystem. option is one of: `arnum`, `windowed`, `cpenable`, `exceptions`, `intnum`, `hipriints`, `excmlevel`, `intlevels`, `debuglevel`, `ibreaknum`, or `dbreaknum`. value is an integer with the exact range determined by each particular option.

  NOTE: Some options are specific to Xtensa LX or Xtensa NX architecture, while others may be common to both but have different valid ranges.

Config Command: xtensa xtmem (`iram`|`dram`|`sram`|`irom`|`drom`|`srom`) baseaddr bytes ¶

  Configure Xtensa target memory. Memory type determines access rights, where RAMs are read/write while ROMs are read-only. baseaddr and bytes are both integers, typically hexadecimal and decimal, respectively.

Config Command: xtensa xtmem (`icache`|`dcache`) linebytes cachebytes ways [writeback] ¶

  Configure Xtensa processor cache. All parameters are required except for the optional `writeback` parameter; all are integers.

Config Command: xtensa xtmpu numfgseg minsegsz lockable execonly ¶

  Configure an Xtensa Memory Protection Unit (MPU). MPUs can restrict access and/or control cacheability of specific address ranges, but are lighter-weight than a full traditional MMU. All parameters are required; all are integers.

Config Command: xtensa xtmmu numirefillentries numdrefillentries ¶

  (Xtensa-LX only) Configure an Xtensa Memory Management Unit (MMU). Both parameters are required; both are integers.

Config Command: xtensa xtregs numregs ¶

  Configure the total number of registers for the Xtensa core. Configuration logic expects to subsequently process this number of `xtensa xtreg` definitions. numregs is an integer.

Config Command: xtensa xtregfmt (`sparse`|`contiguous`) [general] ¶

  Configure the type of register map used by GDB to access the Xtensa core. Generic Xtensa tools (e.g. xt-gdb) require `sparse` mapping (default) while Espressif tools expect `contiguous` mapping. Contiguous mapping takes an additional, optional integer parameter `numgregs`, which specifies the number of general registers used in handling g/G packets.

Config Command: xtensa xtreg name offset ¶

  Configure an Xtensa core register. All core registers are 32 bits wide, while TIE and user registers may have variable widths. name is a character string identifier while offset is a hexadecimal integer.

#### 16.13.3 Xtensa Operation Commands ¶

Command: xtensa maskisr (`on`|`off`) ¶

  (Xtensa-LX only) Mask or unmask Xtensa interrupts during instruction step. When masked, an interrupt that occurs during a step operation is handled and its ISR is executed, with the user’s debug session returning after potentially executing many instructions. When unmasked, a triggered interrupt will result in execution progressing the requested number of instructions into the relevant vector/ISR code.

Command: xtensa set_permissive (0|1) ¶

  By default accessing memory beyond defined regions is forbidden. This commnd controls memory access address check. When set to (1), skips access controls and address range check before read/write memory.

Command: xtensa smpbreak [none|breakinout|runstall] | [BreakIn] [BreakOut] [RunStallIn] [DebugModeOut] ¶

  Configures debug signals connection ("break network") for currently selected core.

  - `none` - Core’s "break/stall network" is disconnected. Core is not affected by any debug signal from other cores.
  - `breakinout` - Core’s "break network" is fully connected (break inputs and outputs are enabled). Core will receive debug break signals from other cores and send such signals to them. For example when another core is stopped due to breakpoint hit this core will be stopped too and vice versa.
  - `runstall` - Core’s "stall network" is fully connected (stall inputs and outputs are enabled). This feature is not well implemented and tested yet.
  - `BreakIn` - Core’s "break-in" signal is enabled. Core will receive debug break signals from other cores. For example when another core is stopped due to breakpoint hit this core will be stopped too.
  - `BreakOut` - Core’s "break-out" signal is enabled. Core will send debug break signal to other cores. For example when this core is stopped due to breakpoint hit other cores with enabled break-in signals will be stopped too.
  - `RunStallIn` - Core’s "runstall-in" signal is enabled. This feature is not well implemented and tested yet.
  - `DebugModeOut` - Core’s "debugmode-out" signal is enabled. This feature is not well implemented and tested yet.

Command: xtensa exe <ascii-encoded hexadecimal instruction bytes> ¶

  Execute arbitrary instruction(s) provided as an ascii string. The string represents an integer number of instruction bytes, thus its length must be even.

#### 16.13.4 Xtensa Performance Monitor Configuration ¶

Command: xtensa perfmon_enable <counter_id> <select> [mask] [kernelcnt] [tracelevel] ¶

  Enable and start performance counter.

  - `counter_id` - Counter ID (0-1).
  - `select` - Selects performance metric to be counted by the counter, e.g. 0 - CPU cycles, 2 - retired instructions.
  - `mask` - Selects input subsets to be counted (counter will increment only once even if more than one condition corresponding to a mask bit occurs).
  - `kernelcnt` - 0 - count events with "CINTLEVEL <= tracelevel", 1 - count events with "CINTLEVEL > tracelevel".
  - `tracelevel` - Compares this value to "CINTLEVEL" when deciding whether to count.

Command: xtensa perfmon_dump (counter_id) ¶

  Dump performance counter value. If no argument specified, dumps all counters.

#### 16.13.5 Xtensa Trace Configuration ¶

Command: xtensa tracestart [pc <pcval>/[<maskbitcount>]] [after <n> [ins|words]] ¶

  Set up and start a HW trace. Optionally set PC address range to trigger tracing stop when reached during program execution. This command also allows to specify the amount of data to capture after stop trigger activation.

  - `pcval` - PC value which will trigger trace data collection stop.
  - `maskbitcount` - PC value mask.
  - `n` - Maximum number of instructions/words to capture after trace stop trigger.

Command: xtensa tracestop ¶

  Stop current trace as started by the tracestart command.

Command: xtensa tracedump <outfile> ¶

  Dump trace memory to a file.

### 16.14 Software Debug Messages and Tracing ¶

OpenOCD can process certain requests from target software, when the target uses appropriate libraries. The most powerful mechanism is semihosting, but there is also a lighter weight mechanism using only the DCC channel.

Currently `target_request debugmsgs` is supported only for `arm7_9` and `cortex_m` cores. These messages are received as part of target polling, so you need to have `poll on` active to receive them. They are intrusive in that they will affect program execution times. If that is a problem, see ARM Hardware Tracing.

See `libdcc` in the contrib dir for more details. In addition to sending strings, characters, and arrays of various size integers from the target, `libdcc` also exports a software trace point mechanism. The target being debugged may issue trace messages which include a 24-bit trace point number. Trace point support includes two distinct mechanisms, each supported by a command:

- History ... A circular buffer of trace points can be set up, and then displayed at any time. This tracks where code has been, which can be invaluable in finding out how some fault was triggered.

  The buffer may overflow, since it collects records continuously. It may be useful to use some of the 24 bits to represent a particular event, and other bits to hold data.

- Counting ... An array of counters can be set up, and then displayed at any time. This can help establish code coverage and identify hot spots.

  The array of counters is directly indexed by the trace point number, so trace points with higher numbers are not counted.

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. This is not the same format used by `libdcc`. Other software, such as the U-Boot boot loader, sometimes does the same thing.

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.

Command: trace history [`clear`|count] ¶

  With no parameter, displays all the trace points that have triggered in the order they triggered. With the parameter `clear`, erases all current trace history records. With a count parameter, allocates space for that many history records.

Command: trace point [`clear`|identifier] ¶

  With no parameter, displays all trace point identifiers and how many times they have been triggered. With the parameter `clear`, erases all current trace point counters. With a numeric identifier parameter, creates a new a trace point counter and associates it with that identifier.

  Important: The identifier and the trace point number are not related except by this command. These trace point numbers always start at zero (from server startup, or after `trace point clear`) and count up from there.