OpenOCD (Open On-Chip Debugger)

Notes

Its per-target config scripts are often the only public description of a new SoC's debug topology during early bring-up.

Overview

OpenOCD, the Open On-Chip Debugger, is free, open-source software that runs on a developer's computer and talks through a debug adapter to the JTAG or SWD debug port of a chip, so that its processors can be halted, inspected and programmed. It provides debugging, flash programming and boundary-scan testing for embedded devices, and acts as the bridge between the GNU debugger GDB and the hardware. Started in 2005 as a university thesis project, it now supports a wide range of adapters, Arm cores and RISC-V cores.

How it works

A host computer has no native JTAG or SWD signals, so OpenOCD drives a debug adapter, usually a small USB dongle or a circuit built into a development board, that produces them. Configuration scripts describe three things: the adapter, the transport (JTAG, or Serial Wire Debug on many Arm cores) and the target chip, including its test access ports and cores. Scripts for many common adapters, chips and boards ship with the project, and a new chip typically gets one written during bring-up.

Once connected, OpenOCD offers several interfaces. GDB connects to it as a remote target, by default on port 3333, to set breakpoints, step code and read registers and memory. A telnet port (4444 by default) gives a person a command line, and a Tcl port (6666) lets scripts drive it, which makes it useful for automated bring-up and test. Built-in flash drivers write program images into on-chip flash or external NOR flash.

Core support runs from older Arm7 and Arm9 devices through Cortex-M and Armv7-A and Armv8 cores to RISC-V: the documentation states JTAG debug of RV32 and RV64 cores following version 0.13 of the RISC-V debug specification.

Examples

• A bring-up engineer halting a new RISC-V core on an FPGA prototype through OpenOCD and stepping its boot code from GDB.
• A firmware developer flashing an STM32 microcontroller over SWD with a low-cost USB adapter and OpenOCD's built-in flash driver.
• A test script that connects to OpenOCD's Tcl port to load firmware and read results on each board in a production test fixture.
• A boundary-scan session through a JTAG adapter to check the connections of a chip on an assembled board.

Why it matters

For a chip team, OpenOCD is often the first tool that proves a new device's debug logic works, and for customers it is a no-cost way to program and debug parts. Silicon bring-up engineers, debug tool developers, firmware engineers and debug architects use it.

Related terms

• GDB
• Debug probe
• JTAG chain
• Flash programming algorithm

Where it appears on the Hub

Used on 5 pages of the Hub. In each group, the pages that mention it most come first.