11 CPU Configuration

This chapter discusses how to set up GDB debug targets for CPUs. You can also access these targets without GDB (see Architecture and Core Commands, and Target State handling) and through various kinds of NAND and NOR flash commands. If you have multiple CPUs you can have multiple such targets.

We’ll start by looking at how to examine the targets you have, then look at how to add one more target and how to configure it.

11.1 Target List

All targets that have been set up are part of a list, where each member has a name. That name should normally be the same as the TAP name. You can display the list with the targets (plural!) command. This display often has only one CPU; here’s what it might look like with more than one:

    TargetName         Type       Endian TapName            State
--  ------------------ ---------- ------ ------------------ ------------
 0* at91rm9200.cpu     arm920t    little at91rm9200.cpu     running
 1  MyTarget           cortex_m   little mychip.foo         tap-disabled

One member of that list is the current target, which is implicitly referenced by many commands. It’s the one marked with a * near the target name. In particular, memory addresses often refer to the address space seen by that current target. Commands like mdw (memory display words) and flash erase_address (erase NOR flash blocks) are examples; and there are many more.

Several commands let you examine the list of targets:

Command: target current

Returns the name of the current target.

Command: target names

Lists the names of all current targets in the list.

foreach t [target names] {
    puts [format "Target: %s\n" $t]
}

Command: targets [name]

Note: the name of this command is plural. Other target command names are singular.

With no parameter, this command displays a table of all known targets in a user friendly form.

With a parameter, this command sets the current target to the given target with the given name; this is only relevant on boards which have more than one target.

11.2 Target CPU Types

Each target has a CPU type, as shown in the output of the targets command. You need to specify that type when calling target create. The CPU type indicates more than just the instruction set. It also indicates how that instruction set is implemented, what kind of debug support it integrates, whether it has an MMU (and if so, what kind), what core-specific commands may be available (see Architecture and Core Commands), and more.

It’s easy to see what target types are supported, since there’s a command to list them.

Command: target types

Lists all supported target types. At this writing, the supported CPU types are:

• aarch64 – this is an ARMv8-A core with an MMU.
• arm11 – this is a generation of ARMv6 cores.
• arm720t – this is an ARMv4 core with an MMU.
• arm7tdmi – this is an ARMv4 core.
• arm920t – this is an ARMv4 core with an MMU.
• arm926ejs – this is an ARMv5 core with an MMU.
• arm946e – this is an ARMv5 core with an MMU.
• arm966e – this is an ARMv5 core.
• arm9tdmi – this is an ARMv4 core.
• avr – implements Atmel’s 8-bit AVR instruction set. (Support for this is preliminary and incomplete.)
• avr32_ap7k – this an AVR32 core.
• cortex_a – this is an ARMv7-A core with an MMU.
• cortex_m – this is an ARMv7-M core, supporting only the compact Thumb2 instruction set. Supports also ARMv6-M and ARMv8-M cores
• cortex_r4 – this is an ARMv7-R core.
• dragonite – resembles arm966e.
• dsp563xx – implements Freescale’s 24-bit DSP. (Support for this is still incomplete.)
• dsp5680xx – implements Freescale’s 5680x DSP.
• esirisc – this is an EnSilica eSi-RISC core. The current implementation supports eSi-32xx cores.
• esp32 – this is an Espressif SoC with dual Xtensa cores.
• esp32s2 – this is an Espressif SoC with single Xtensa core.
• esp32s3 – this is an Espressif SoC with dual Xtensa cores.
• fa526 – resembles arm920 (w/o Thumb).
• feroceon – resembles arm926.
• hla_target – a Cortex-M alternative to work with HL adapters like ST-Link.
• ls1_sap – this is the SAP on NXP LS102x CPUs, allowing access to physical memory addresses independently of CPU cores.
• mem_ap – this is an ARM debug infrastructure Access Port without a CPU, through which bus read and write cycles can be generated; it may be useful for working with non-CPU hardware behind an AP or during development of support for new CPUs. It’s possible to connect a GDB client to this target (the GDB port has to be specified, See option -gdb-port.), and a fake ARM core will be emulated to comply to GDB remote protocol.
• mips_m4k – a MIPS core.
• mips_mips64 – a MIPS64 core.
• nds32_v2 – this is an Andes NDS32 v2 core (deprecated; would be removed in v0.13.0).
• nds32_v3 – this is an Andes NDS32 v3 core (deprecated; would be removed in v0.13.0).
• nds32_v3m – this is an Andes NDS32 v3m core (deprecated; would be removed in v0.13.0).
• or1k – this is an OpenRISC 1000 core. The current implementation supports three JTAG TAP cores:
  • - OpenCores TAP (See: http://opencores.org/project,jtag)
  • - Altera Virtual JTAG TAP (See: http://www.altera.com/literature/ug/ug_virtualjtag.pdf)
  • - Xilinx BSCAN_* virtual JTAG interface (See: http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf)

  And two debug interfaces cores:

  • - Advanced debug interface
    (See: http://opencores.org/project,adv_debug_sys)
  • - SoC Debug Interface
    (See: http://opencores.org/project,dbg_interface)
• quark_d20xx – an Intel Quark D20xx core.
• quark_x10xx – an Intel Quark X10xx core.
• riscv – a RISC-V core.
• stm8 – implements an STM8 core.
• testee – a dummy target for cases without a real CPU, e.g. CPLD.
• xscale – this is actually an architecture, not a CPU type. It is based on the ARMv5 architecture.
• xtensa – this is a generic Cadence/Tensilica Xtensa core.

To avoid being confused by the variety of ARM based cores, remember this key point: ARM is a technology licencing company. (See: http://www.arm.com.) The CPU name used by OpenOCD will reflect the CPU design that was licensed, not a vendor brand which incorporates that design. Name prefixes like arm7, arm9, arm11, and cortex reflect design generations; while names like ARMv4, ARMv5, ARMv6, ARMv7 and ARMv8 reflect an architecture version implemented by a CPU design.

11.3 Target Configuration

Before creating a “target”, you must have added its TAP to the scan chain. When you’ve added that TAP, you will have a dotted.name which is used to set up the CPU support. The chip-specific configuration file will normally configure its CPU(s) right after it adds all of the chip’s TAPs to the scan chain.

Although you can set up a target in one step, it’s often clearer if you use shorter commands and do it in two steps: create it, then configure optional parts. All operations on the target after it’s created will use a new command, created as part of target creation.

The two main things to configure after target creation are a work area, which usually has target-specific defaults even if the board setup code overrides them later; and event handlers (see Target Events), which tend to be much more board-specific. The key steps you use might look something like this

dap create mychip.dap -chain-position mychip.cpu
target create MyTarget cortex_m -dap mychip.dap
MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
MyTarget configure -event reset-deassert-pre { jtag_rclk 5 }
MyTarget configure -event reset-init { myboard_reinit }

You should specify a working area if you can; typically it uses some on-chip SRAM. Such a working area can speed up many things, including bulk writes to target memory; flash operations like checking to see if memory needs to be erased; GDB memory checksumming; and more.

Warning: On more complex chips, the work area can become inaccessible when application code (such as an operating system) enables or disables the MMU. For example, the particular MMU context used to access the virtual address will probably matter ... and that context might not have easy access to other addresses needed. At this writing, OpenOCD doesn’t have much MMU intelligence.

It’s often very useful to define a reset-init event handler. For systems that are normally used with a boot loader, common tasks include updating clocks and initializing memory controllers. That may be needed to let you write the boot loader into flash, in order to “de-brick” your board; or to load programs into external DDR memory without having run the boot loader.

Config Command: target create target_name type configparams...

This command creates a GDB debug target that refers to a specific JTAG tap. It enters that target into a list, and creates a new command (target_name) which is used for various purposes including additional configuration.

• target_name ... is the name of the debug target. By convention this should be the same as the dotted.name of the TAP associated with this target, which must be specified here using the -chain-position dotted.name configparam.

  This name is also used to create the target object command, referred to here as $target_name, and in other places the target needs to be identified.

• type ... specifies the target type. See target types.
• configparams ... all parameters accepted by $target_name configure are permitted. If the target is big-endian, set it here with -endian big.

  You must set the -chain-position dotted.name or -dap dap_name here.

Command: $target_name configure configparams...

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

Warning: changing some of these after setup is dangerous. For example, moving a target from one TAP to another; and changing its endianness.

• -chain-position dotted.name – names the TAP used to access this target.
• -dap dap_name – names the DAP used to access this target. See DAP declaration, on how to create and manage DAP instances.
• -endian (big|little) – specifies whether the CPU uses big or little endian conventions
• -event event_name event_body – See Target Events. Note that this updates a list of named event handlers. Calling this twice with two different event names assigns two different handlers, but calling it twice with the same event name assigns only one handler.

  Current target is temporarily overridden to the event issuing target before handler code starts and switched back after handler is done.

• -work-area-backup (0|1) – says whether the work area gets backed up; by default, it is not backed up. When possible, use a working_area that doesn’t need to be backed up, since performing a backup slows down operations. For example, the beginning of an SRAM block is likely to be used by most build systems, but the end is often unused.
• -work-area-size size – specify work are size, in bytes. The same size applies regardless of whether its physical or virtual address is being used.
• -work-area-phys address – set the work area base address to be used when no MMU is active.
• -work-area-virt address – set the work area base address to be used when an MMU is active. Do not specify a value for this except on targets with an MMU. The value should normally correspond to a static mapping for the -work-area-phys address, set up by the current operating system.
• -rtos rtos_type – enable rtos support for target, rtos_type can be one of auto, none, eCos, ThreadX, FreeRTOS, linux, ChibiOS, embKernel, mqx, uCOS-III, nuttx, RIOT, Zephyr See RTOS Support.
• -defer-examine – skip target examination at initial JTAG chain scan and after a reset. A manual call to arp_examine is required to access the target for debugging.
• -ap-num ap_number – set DAP access port for target. On ADIv5 DAP ap_number is the numeric index of the DAP AP the target is connected to. On ADIv6 DAP ap_number is the base address of the DAP AP the target is connected to. Use this option with systems where multiple, independent cores are connected to separate access ports of the same DAP.
• -cti cti_name – set Cross-Trigger Interface (CTI) connected to the target. Currently, only the aarch64 target makes use of this option, where it is a mandatory configuration for the target run control. See ARM Cross-Trigger Interface, for instruction on how to declare and control a CTI instance.
• -gdb-port number – see command gdb_port for the possible values of the parameter number, which are not only numeric values. Use this option to override, for this target only, the global parameter set with command gdb_port. See command gdb_port.
• -gdb-max-connections number – EXPERIMENTAL: set the maximum number of GDB connections that are allowed for the target. Default is 1. A negative value for number means unlimited connections. See See Using GDB as a non-intrusive memory inspector.

11.4 Other $target_name Commands

The Tcl/Tk language has the concept of object commands, and OpenOCD adopts that same model for targets.

A good Tk example is a on screen button. Once a button is created a button has a name (a path in Tk terms) and that name is useable as a first class command. For example in Tk, one can create a button and later configure it like this:

# Create
button .foobar -background red -command { foo }
# Modify
.foobar configure -foreground blue
# Query
set x [.foobar cget -background]
# Report
puts [format "The button is %s" $x]

In OpenOCD’s terms, the “target” is an object just like a Tcl/Tk button, and its object commands are invoked the same way.

str912.cpu    mww 0x1234 0x42
omap3530.cpu  mww 0x5555 123

The commands supported by OpenOCD target objects are:

Command: $target_name arp_examine allow-defer

Command: $target_name arp_halt

Command: $target_name arp_poll

Command: $target_name arp_reset

Command: $target_name arp_waitstate

Internal OpenOCD scripts (most notably startup.tcl) use these to deal with specific reset cases. They are not otherwise documented here.

Command: $target_name set_reg dict

Set register values of the target.

• dict ... Tcl dictionary with pairs of register names and values.

For example, the following command sets the value 0 to the program counter (pc) register and 0x1000 to the stack pointer (sp) register:

set_reg {pc 0 sp 0x1000}

Command: $target_name get_reg [-force] list

Get register values from the target and return them as Tcl dictionary with pairs of register names and values. If option "-force" is set, the register values are read directly from the target, bypassing any caching.

• list ... List of register names

For example, the following command retrieves the values from the program counter (pc) and stack pointer (sp) register:

get_reg {pc sp}

Command: $target_name write_memory address width data ['phys']

This function provides an efficient way to write to the target memory from a Tcl script.

• address ... target memory address
• width ... memory access bit size, can be 8, 16, 32 or 64
• data ... Tcl list with the elements to write
• [’phys’] ... treat the memory address as physical instead of virtual address

For example, the following command writes two 32 bit words into the target memory at address 0x20000000:

write_memory 0x20000000 32 {0xdeadbeef 0x00230500}

Command: $target_name read_memory address width count ['phys']

This function provides an efficient way to read the target memory from a Tcl script. A Tcl list containing the requested memory elements is returned by this function.

• address ... target memory address
• width ... memory access bit size, can be 8, 16, 32 or 64
• count ... number of elements to read
• [’phys’] ... treat the memory address as physical instead of virtual address

For example, the following command reads two 32 bit words from the target memory at address 0x20000000:

read_memory 0x20000000 32 2

Command: $target_name cget queryparm

Each configuration parameter accepted by $target_name configure can be individually queried, to return its current value. The queryparm is a parameter name accepted by that command, such as -work-area-phys. There are a few special cases:

• -event event_name – returns the handler for the event named event_name. This is a special case because setting a handler requires two parameters.
• -type – returns the target type. This is a special case because this is set using target create and can’t be changed using $target_name configure.

For example, if you wanted to summarize information about all the targets you might use something like this:

foreach name [target names] {
    set y [$name cget -endian]
    set z [$name cget -type]
    puts [format "Chip %d is %s, Endian: %s, type: %s" \
                 $x $name $y $z]
}

Command: $target_name curstate

Displays the current target state: debug-running, halted, reset, running, or unknown. (Also, see Event Polling.)

Command: $target_name eventlist

Displays a table listing all event handlers currently associated with this target. See Target Events.

Command: $target_name invoke-event event_name

Invokes the handler for the event named event_name. (This is primarily intended for use by OpenOCD framework code, for example by the reset code in startup.tcl.)

Command: $target_name mdd [phys] addr [count]

Command: $target_name mdw [phys] addr [count]

Command: $target_name mdh [phys] addr [count]

Command: $target_name mdb [phys] addr [count]

Display contents of address addr, as 64-bit doublewords (mdd), 32-bit words (mdw), 16-bit halfwords (mdh), or 8-bit bytes (mdb). When the current target has an MMU which is present and active, addr is interpreted as a virtual address. Otherwise, or if the optional phys flag is specified, addr is interpreted as a physical address. If count is specified, displays that many units. (If you want to process the data instead of displaying it, see the read_memory primitives.)

Command: $target_name mwd [phys] addr doubleword [count]

Command: $target_name mww [phys] addr word [count]

Command: $target_name mwh [phys] addr halfword [count]

Command: $target_name mwb [phys] addr byte [count]

Writes the specified doubleword (64 bits), word (32 bits), halfword (16 bits), or byte (8-bit) value, at the specified address addr. When the current target has an MMU which is present and active, addr is interpreted as a virtual address. Otherwise, or if the optional phys flag is specified, addr is interpreted as a physical address. If count is specified, fills that many units of consecutive address.

11.5 Target Events

At various times, certain things can happen, or you want them to happen. For example:

• What should happen when GDB connects? Should your target reset?
• When GDB tries to flash the target, do you need to enable the flash via a special command?
• Is using SRST appropriate (and possible) on your system? Or instead of that, do you need to issue JTAG commands to trigger reset? SRST usually resets everything on the scan chain, which can be inappropriate.
• During reset, do you need to write to certain memory locations to set up system clocks or to reconfigure the SDRAM? How about configuring the watchdog timer, or other peripherals, to stop running while you hold the core stopped for debugging?

All of the above items can be addressed by target event handlers. These are set up by $target_name configure -event or target create ... -event.

The programmer’s model matches the -command option used in Tcl/Tk buttons and events. The two examples below act the same, but one creates and invokes a small procedure while the other inlines it.

proc my_init_proc { } {
    echo "Disabling watchdog..."
    mww 0xfffffd44 0x00008000
}
mychip.cpu configure -event reset-init my_init_proc
mychip.cpu configure -event reset-init {
    echo "Disabling watchdog..."
    mww 0xfffffd44 0x00008000
}

The following target events are defined:

• debug-halted
  The target has halted for debug reasons (i.e.: breakpoint)
• debug-resumed
  The target has resumed (i.e.: GDB said run)
• early-halted
  Occurs early in the halt process
• examine-start
  Before target examine is called.
• examine-end
  After target examine is called with no errors.
• examine-fail
  After target examine fails.
• gdb-attach
  When GDB connects. Issued before any GDB communication with the target starts. GDB expects the target is halted during attachment. See GDB as a non-intrusive memory inspector, how to connect GDB to running target. The event can be also used to set up the target so it is possible to probe flash. Probing flash is necessary during GDB connect if you want to use see programming using GDB. Another use of the flash memory map is for GDB to automatically choose hardware or software breakpoints depending on whether the breakpoint is in RAM or read only memory. Default is halt
• gdb-detach
  When GDB disconnects
• gdb-end
  When the target has halted and GDB is not doing anything (see early halt)
• gdb-flash-erase-start
  Before the GDB flash process tries to erase the flash (default is reset init)
• gdb-flash-erase-end
  After the GDB flash process has finished erasing the flash
• gdb-flash-write-start
  Before GDB writes to the flash
• gdb-flash-write-end
  After GDB writes to the flash (default is reset halt)
• gdb-start
  Before the target steps, GDB is trying to start/resume the target
• halted
  The target has halted
• reset-assert-pre
  Issued as part of reset processing after reset-start was triggered but before either SRST alone is asserted on the scan chain, or reset-assert is triggered.
• reset-assert
  Issued as part of reset processing after reset-assert-pre was triggered. When such a handler is present, cores which support this event will use it instead of asserting SRST. This support is essential for debugging with JTAG interfaces which don’t include an SRST line (JTAG doesn’t require SRST), and for selective reset on scan chains that have multiple targets.
• reset-assert-post
  Issued as part of reset processing after reset-assert has been triggered. or the target asserted SRST on the entire scan chain.
• reset-deassert-pre
  Issued as part of reset processing after reset-assert-post has been triggered.
• reset-deassert-post
  Issued as part of reset processing after reset-deassert-pre has been triggered and (if the target is using it) after SRST has been released on the scan chain.
• reset-end
  Issued as the final step in reset processing.
• reset-init
  Used by reset init command for board-specific initialization. This event fires after reset-deassert-post.

  This is where you would configure PLLs and clocking, set up DRAM so you can download programs that don’t fit in on-chip SRAM, set up pin multiplexing, and so on. (You may be able to switch to a fast JTAG clock rate here, after the target clocks are fully set up.)

• reset-start
  Issued as the first step in reset processing before reset-assert-pre is called.

  This is the most robust place to use jtag_rclk or adapter speed to switch to a low JTAG clock rate, when reset disables PLLs needed to use a fast clock.

• resume-start
  Before any target is resumed
• resume-end
  After all targets have resumed
• resumed
  Target has resumed
• step-start
  Before a target is single-stepped
• step-end
  After single-step has completed
• trace-config
  After target hardware trace configuration was changed
• semihosting-user-cmd-0x100
  The target made a semihosting call with user-defined operation number 0x100
• semihosting-user-cmd-0x101
  The target made a semihosting call with user-defined operation number 0x101
• semihosting-user-cmd-0x102
  The target made a semihosting call with user-defined operation number 0x102
• semihosting-user-cmd-0x103
  The target made a semihosting call with user-defined operation number 0x103
• semihosting-user-cmd-0x104
  The target made a semihosting call with user-defined operation number 0x104
• semihosting-user-cmd-0x105
  The target made a semihosting call with user-defined operation number 0x105
• semihosting-user-cmd-0x106
  The target made a semihosting call with user-defined operation number 0x106
• semihosting-user-cmd-0x107
  The target made a semihosting call with user-defined operation number 0x107

Note: OpenOCD events are not supposed to be preempt by another event, but this is not enforced in current code. Only the target event resumed is executed with polling disabled; this avoids polling to trigger the event halted, reversing the logical order of execution of their handlers. Future versions of OpenOCD will prevent the event preemption and will disable the schedule of polling during the event execution. Do not rely on polling in any event handler; this means, don’t expect the status of a core to change during the execution of the handler. The event handler will have to enable polling or use $target_name arp_poll to check if the core has changed status.