Next: , Previous: Debug Adapter Configuration, Up: Top

9 Reset Configuration

Every system configuration may require a different reset configuration. This can also be quite confusing. Resets also interact with reset-init event handlers, which do things like setting up clocks and DRAM, and JTAG clock rates. (See JTAG Speed.) They can also interact with JTAG routers. Please see the various board files for examples.

Note: To maintainers and integrators: Reset configuration touches several things at once. Normally the board configuration file should define it and assume that the JTAG adapter supports everything that's wired up to the board's JTAG connector.

However, the target configuration file could also make note of something the silicon vendor has done inside the chip, which will be true for most (or all) boards using that chip. And when the JTAG adapter doesn't support everything, the user configuration file will need to override parts of the reset configuration provided by other files.

9.1 Types of Reset

There are many kinds of reset possible through JTAG, but they may not all work with a given board and adapter. That's part of why reset configuration can be error prone.

In the best case, OpenOCD can hold SRST, then reset the TAPs via TRST and send commands through JTAG to halt the CPU at the reset vector before the 1st instruction is executed. Then when it finally releases the SRST signal, the system is halted under debugger control before any code has executed. This is the behavior required to support the reset halt and reset init commands; after reset init a board-specific script might do things like setting up DRAM. (See Reset Command.)

9.2 SRST and TRST Issues

Because SRST and TRST are hardware signals, they can have a variety of system-specific constraints. Some of the most common issues are:

There can also be other issues. Some devices don't fully conform to the JTAG specifications. Trivial system-specific differences are common, such as SRST and TRST using slightly different names. There are also vendors who distribute key JTAG documentation for their chips only to developers who have signed a Non-Disclosure Agreement (NDA).

Sometimes there are chip-specific extensions like a requirement to use the normally-optional TRST signal (precluding use of JTAG adapters which don't pass TRST through), or needing extra steps to complete a TAP reset.

In short, SRST and especially TRST handling may be very finicky, needing to cope with both architecture and board specific constraints.

9.3 Commands for Handling Resets

— Command: adapter_nsrst_assert_width milliseconds

Minimum amount of time (in milliseconds) OpenOCD should wait after asserting nSRST (active-low system reset) before allowing it to be deasserted.

— Command: adapter_nsrst_delay milliseconds

How long (in milliseconds) OpenOCD should wait after deasserting nSRST (active-low system reset) before starting new JTAG operations. When a board has a reset button connected to SRST line it will probably have hardware debouncing, implying you should use this.

— Command: jtag_ntrst_assert_width milliseconds

Minimum amount of time (in milliseconds) OpenOCD should wait after asserting nTRST (active-low JTAG TAP reset) before allowing it to be deasserted.

— Command: jtag_ntrst_delay milliseconds

How long (in milliseconds) OpenOCD should wait after deasserting nTRST (active-low JTAG TAP reset) before starting new JTAG operations.

— Command: reset_config mode_flag ...

This command displays or modifies the reset configuration of your combination of JTAG board and target in target configuration scripts.

Information earlier in this section describes the kind of problems the command is intended to address (see SRST and TRST Issues). As a rule this command belongs only in board config files, describing issues like board doesn't connect TRST; or in user config files, addressing limitations derived from a particular combination of interface and board. (An unlikely example would be using a TRST-only adapter with a board that only wires up SRST.)

The mode_flag options can be specified in any order, but only one of each type – signals, combination, gates, trst_type, srst_type and connect_type – may be specified at a time. If you don't provide a new value for a given type, its previous value (perhaps the default) is unchanged. For example, this means that you don't need to say anything at all about TRST just to declare that if the JTAG adapter should want to drive SRST, it must explicitly be driven high (srst_push_pull).

The optional trst_type and srst_type parameters allow the driver mode of each reset line to be specified. These values only affect JTAG interfaces with support for different driver modes, like the Amontec JTAGkey and JTAG Accelerator. Also, they are necessarily ignored if the relevant signal (TRST or SRST) is not connected.

9.4 Custom Reset Handling

OpenOCD has several ways to help support the various reset mechanisms provided by chip and board vendors. The commands shown in the previous section give standard parameters. There are also event handlers associated with TAPs or Targets. Those handlers are Tcl procedures you can provide, which are invoked at particular points in the reset sequence.

When SRST is not an option you must set up a reset-assert event handler for your target. For example, some JTAG adapters don't include the SRST signal; and some boards have multiple targets, and you won't always want to reset everything at once.

After configuring those mechanisms, you might still find your board doesn't start up or reset correctly. For example, maybe it needs a slightly different sequence of SRST and/or TRST manipulations, because of quirks that the reset_config mechanism doesn't address; or asserting both might trigger a stronger reset, which needs special attention.

Experiment with lower level operations, such as jtag_reset and the jtag arp_* operations shown here, to find a sequence of operations that works. See JTAG Commands. When you find a working sequence, it can be used to override jtag_init, which fires during OpenOCD startup (see Configuration Stage); or init_reset, which fires during reset processing.

You might also want to provide some project-specific reset schemes. For example, on a multi-target board the standard reset command would reset all targets, but you may need the ability to reset only one target at time and thus want to avoid using the board-wide SRST signal.

— Overridable Procedure: init_reset mode

This is invoked near the beginning of the reset command, usually to provide as much of a cold (power-up) reset as practical. By default it is also invoked from jtag_init if the scan chain does not respond to pure JTAG operations. The mode parameter is the parameter given to the low level reset command (halt, init, or run), setup, or potentially some other value.

The default implementation just invokes jtag arp_init-reset. Replacements will normally build on low level JTAG operations such as jtag_reset. Operations here must not address individual TAPs (or their associated targets) until the JTAG scan chain has first been verified to work.

Implementations must have verified the JTAG scan chain before they return. This is done by calling jtag arp_init (or jtag arp_init-reset).

— Command: jtag arp_init

This validates the scan chain using just the four standard JTAG signals (TMS, TCK, TDI, TDO). It starts by issuing a JTAG-only reset. Then it performs checks to verify that the scan chain configuration matches the TAPs it can observe. Those checks include checking IDCODE values for each active TAP, and verifying the length of their instruction registers using TAP -ircapture and -irmask values. If these tests all pass, TAP setup events are issued to all TAPs with handlers for that event.

— Command: jtag arp_init-reset

This uses TRST and SRST to try resetting everything on the JTAG scan chain (and anything else connected to SRST). It then invokes the logic of jtag arp_init.