How openocd-org/openocd works
1. What the repository is
- OpenOCD is a long-running host-side debugging/programming daemon.
- It sits between developer tools like GDB and the physical target hardware, translating high-level debug/flash commands into JTAG/SWD/SPI/GPIO-style operations.
2. Top-level execution flow
- The program starts in src/openocd.c / src/main.c, initializes logging, configuration, transport selection, and the embedded Tcl interpreter.
- It then loads startup and board/interface/target scripts from tcl/ to assemble the runtime topology for the selected hardware.
3. Command and scripting layer
- src/helper/command.c, src/server/tcl_server.c, and the tcl/ tree form the user/control plane.
- Tcl is a first-class configuration and automation interface, not just a convenience layer: board setup, target definitions, flash helpers, and test scripts are all driven by Tcl.
4. Transport and connection boundary
- src/transport/ abstracts the protocol used between OpenOCD and the debug adapter.
- src/jtag/ and src/jtag/interfaces.c select and configure the active transport mode, such as JTAG, SWD, cJTAG, or adapter-specific pathways.
5. Adapter driver subsystem
- src/jtag/drivers/ is the hardware-facing layer for probe adapters and native GPIO backends.
- It contains many concrete drivers for USB probes and host I/O mechanisms such as FTDI, ST-Link, J-Link, CMSIS-DAP, XDS110, Linux GPIO, remote bitbang, and various vendor-specific adapters.
- This is the main boundary between host software and external debug hardware.
6. Core debug protocol engine
- src/jtag/core.c, src/jtag/adapter.c, src/jtag/bitbang.c, and related files implement the bit-level and transaction-level state machines.
- This layer handles TAP sequencing, scan chains, register access, and low-level signaling, independent of the target CPU architecture.
7. Target architecture subsystem
- src/target/ is the largest functional area and contains per-architecture support for ARM, Cortex-M/A/R, RISC-V, MIPS, Xtensa, ARC, AVR32, ESP32-family, STM8, OpenRISC, and others.
- It implements register models, memory access, breakpoints/watchpoints, semihosting, trace, SMP, and architecture-specific debug protocols.
- The target layer consumes JTAG/SWD transactions from the transport layer and exposes a uniform target abstraction to the command/server layers.
8. Flash programming subsystem
- src/flash/ provides NOR and NAND flash support, including common core logic and many chip-family drivers.
- src/flash/nor/, src/flash/nand/, and the loader code under contrib/loaders/ show the split between generic flash orchestration and target-specific in-circuit algorithms.
- Flash operations often flow from Tcl/GDB commands into the target layer, then into flash drivers, and finally into target-resident or adapter-assisted routines.
9. Server interfaces exposed to external tools
- src/server/ contains the network-facing endpoints: GDB server, Telnet server, Tcl server, RTT server, and IPDBG support.
- These servers are the main public runtime interfaces for IDEs, scripts, and debuggers; they translate incoming protocol messages into target/flash/jtag operations.
10. Ancillary debugging features
- src/rtos/ provides RTOS thread awareness for several kernels.
- src/rtt/ supports SEGGER RTT-style host communication.
- src/svf/ and src/xsvf/ implement boundary-scan playback for FPGA/CPLD programming.
- src/pld/ contains FPGA/CPLD-specific programming logic and bitstream handling.
11. Reusable support code
- src/helper/ holds shared infrastructure: logging, file I/O, buffers, CRC/base64, configuration, lists, utility routines, and numeric helpers.
- jimtcl/ is the embedded Tcl interpreter dependency that powers scripting and configuration.
12. Configuration/data assets
- The tcl/interface/, tcl/target/, tcl/board/, tcl/chip/, and tcl/cpu/ trees are the declarative hardware model database.
- These scripts define how adapters, boards, targets, memories, and quirks are composed at runtime.
13. Build, packaging, and external dependencies
- The project is autotools-based (configure.ac, Makefile.am, bootstrap) and builds a C daemon.
- Material optional dependencies include libusb, libftdi, HIDAPI, libgpiod, libjaylink, and capstone; these enable specific adapter backends or disassembly features.
- Documentation is generated from the doc/ tree, including the user guide and developer manual.
14. Firmware, loaders, and test collateral
- contrib/firmware/ contains firmware for some adapter hardware, while contrib/loaders/ contains target-side flash/debug helper images.
- testing/ and testing/examples/ provide sample target projects and regression inputs, showing OpenOCD as part of a hardware validation workflow rather than just a standalone binary.
Main entry points: target.c Target core · command.c Commands · openocd.c OpenOCD core · common.c Flash core
Components 24
Runtime
Daemon startup, command handling, servers, and Tcl-driven orchestration.
- Main · Process entry point and top-level initialization.
src/main.c - OpenOCD core · Primary startup and orchestration logic.
src/openocd.c - Commands · Command parser and shared command infrastructure.
src/helper/command.c - Tcl server · Network Tcl control interface.
src/server/tcl_server.c - GDB server · GDB remote protocol bridge to targets.
src/server/gdb_server.c - Telnet server · Interactive CLI socket interface.
src/server/telnet_server.c
Transport
Protocol selection and probe-facing signaling layers.
- Transport · Abstracts the link between OpenOCD and the debug adapter.
src/transport/transport.c - Interfaces · Selects and configures JTAG, SWD, cJTAG, and related pathways.
src/jtag/interfaces.c - JTAG core · Low-level TAP sequencing and scan-chain operations.
src/jtag/core.c - Adapter layer · Bit-level adapter control and transaction dispatch.
src/jtag/adapter.c - Probe drivers · Concrete USB, GPIO, and remote probe backends.
src/jtag/drivers/driver.c
Targets
CPU/architecture support and target abstractions.
- Target core · Common target model and execution services.
src/target/target.c - ARM · ARM, Cortex-M/A/R, debug, trace, and semihosting support.
src/target/armv7m.c - RISC-V · RISC-V registers, program/debug, and GDB integration.
src/target/riscv/riscv.c - Other targets · MIPS, Xtensa, ARC, ESP, AVR, STM8, x86, and other architectures.
src/target/mips32.c
Flash
NOR/NAND flashing and target-side loader support.
- Flash core · Common flash orchestration and device-independent services.
src/flash/common.c - NOR flash · NOR flash framework and chip-family drivers.
src/flash/nor/core.c - NAND flash · NAND flash framework and device-specific implementations.
src/flash/nand/core.c - Loaders · Target-resident flash/debug helper images and algorithms.
contrib/loaders
Scripts
Declarative Tcl hardware models and startup scripts.
- Tcl model · Declarative startup scripts and hardware descriptions.
tcl
Support
Shared utilities, embedded interpreter, documentation, and collateral.
Connections 29
- Main → OpenOCD core: starts · Program entry hands off to daemon initialization.
- OpenOCD core → Helpers: uses · Initialization relies on shared infrastructure and utilities.
- OpenOCD core → Jim Tcl: embeds · Startup initializes the Tcl interpreter.
- OpenOCD core → Tcl model: loads · Startup scripts assemble the runtime topology.
- OpenOCD core → Commands: registers · Core wires command handling into the runtime.
- Commands → Tcl server: feeds · Commands are exposed through the Tcl control interface.
- Commands → Telnet server: feeds · Interactive command handling is served over telnet.
- Commands → GDB server: coordinates · Commands are available to protocol servers.
- Tcl server → Tcl model: executes · Tcl server runs user scripts and configuration commands.
- Tcl model → Target core: defines · Scripts describe boards, targets, memories, and quirks.
- Tcl model → Interfaces: selects · Configuration chooses adapter transport and signaling mode.
- Interfaces → Transport: binds · Interfaces connect logical modes to transport plumbing.
- Transport → JTAG core: drives · Transport requests are executed through core JTAG sequencing.
- JTAG core → Adapter layer: dispatches · Core transactions are lowered to adapter operations.
- Adapter layer → Probe drivers: controls · Adapter layer talks to concrete probe backends.
- Probe drivers → Target core: serves · Hardware access is consumed by target debug logic.
- Target core → ARM: includes · ARM family support is a major target subsystem.
- Target core → RISC-V: includes · RISC-V support is a major target subsystem.
- Target core → Other targets: includes · Other architecture families are handled here.
- Target core → Flash core: enables · Targets provide the execution context for flash operations.
- Flash core → NOR flash: routes · NOR flashing is handled by family drivers.
- Flash core → NAND flash: routes · NAND flashing is handled by family drivers.
- Flash core → Loaders: uses · Some flash operations rely on target-side helper images.
- GDB server → Target core: controls · GDB remote commands manipulate targets.
- GDB server → Flash core: invokes · Flash programming is exposed through the server interface.
- ARM → Commands: exposes · Architecture-specific commands surface through the command plane.
- RISC-V → Commands: exposes · Architecture-specific commands surface through the command plane.
- Docs → Tcl model: describes · Documentation explains the script-driven configuration model.
- Testing → GDB server: exercises · Example projects and smoke tests validate server workflows.