# openocd-org/openocd architecture

> Architecture diagram of the GitHub repository openocd-org/openocd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openocd-org/openocd
- Repository: https://github.com/openocd-org/openocd

## Overview

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: [`src/target/target.c`](https://github.com/openocd-org/openocd/blob/master/src/target/target.c) (Target core), [`src/helper/command.c`](https://github.com/openocd-org/openocd/blob/master/src/helper/command.c) (Commands), [`src/openocd.c`](https://github.com/openocd-org/openocd/blob/master/src/openocd.c) (OpenOCD core), [`src/flash/common.c`](https://github.com/openocd-org/openocd/blob/master/src/flash/common.c) (Flash core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_main["Main<br/>daemon entry<br/>[main.c]"]
  node_src_openocd["OpenOCD core<br/>daemon core<br/>[openocd.c]"]
  node_src_command["Commands<br/>control plane<br/>[command.c]"]
  node_src_tcl_server["Tcl server<br/>server endpoint<br/>[tcl_server.c]"]
  node_src_gdb_server["GDB server<br/>server endpoint<br/>[gdb_server.c]"]
  node_src_telnet_server["Telnet server<br/>server endpoint<br/>[telnet_server.c]"]
end

subgraph group_transport["Transport"]
  node_src_transport["Transport<br/>protocol boundary<br/>[transport.c]"]
  node_src_jtag_interfaces["Interfaces<br/>mode select<br/>[interfaces.c]"]
  node_src_jtag_core["JTAG core<br/>state engine<br/>[core.c]"]
  node_src_jtag_adapter["Adapter layer<br/>signal engine<br/>[adapter.c]"]
  node_src_jtag_drivers["Probe drivers<br/>hardware drivers<br/>[driver.c]"]
end

subgraph group_target["Targets"]
  node_src_target["Target core<br/>target abstraction<br/>[target.c]"]
  node_src_target_arm["ARM<br/>arch support<br/>[armv7m.c]"]
  node_src_target_riscv["RISC-V<br/>arch support<br/>[riscv.c]"]
  node_src_target_other["Other targets<br/>arch support<br/>[mips32.c]"]
end

subgraph group_flash["Flash"]
  node_src_flash_core["Flash core<br/>flash manager<br/>[common.c]"]
  node_src_flash_nor["NOR flash<br/>flash drivers<br/>[core.c]"]
  node_src_flash_nand["NAND flash<br/>flash drivers<br/>[core.c]"]
  node_src_flash_loaders["Loaders<br/>target-side code"]
end

subgraph group_scripts["Scripts"]
  node_tcl_root["Tcl model<br/>runtime config"]
end

subgraph group_support["Support"]
  node_src_helper["Helpers<br/>shared support"]
  node_jimtcl["Jim Tcl<br/>embedded interpreter"]
  node_doc["Docs<br/>documentation"]
  node_testing["Testing<br/>collateral"]
end

node_src_main -->|"starts"| node_src_openocd
node_src_openocd -->|"uses"| node_src_helper
node_src_openocd -->|"embeds"| node_jimtcl
node_src_openocd -->|"loads"| node_tcl_root
node_src_openocd -->|"registers"| node_src_command
node_src_command -->|"feeds"| node_src_tcl_server
node_src_command -->|"feeds"| node_src_telnet_server
node_src_command -->|"coordinates"| node_src_gdb_server
node_src_tcl_server -->|"executes"| node_tcl_root
node_tcl_root -->|"defines"| node_src_target
node_tcl_root -->|"selects"| node_src_jtag_interfaces
node_src_jtag_interfaces -->|"binds"| node_src_transport
node_src_transport -->|"drives"| node_src_jtag_core
node_src_jtag_core -->|"dispatches"| node_src_jtag_adapter
node_src_jtag_adapter -->|"controls"| node_src_jtag_drivers
node_src_jtag_drivers -->|"serves"| node_src_target
node_src_target -->|"includes"| node_src_target_arm
node_src_target -->|"includes"| node_src_target_riscv
node_src_target -->|"includes"| node_src_target_other
node_src_target -->|"enables"| node_src_flash_core
node_src_flash_core -->|"routes"| node_src_flash_nor
node_src_flash_core -->|"routes"| node_src_flash_nand
node_src_flash_core -->|"uses"| node_src_flash_loaders
node_src_gdb_server -->|"controls"| node_src_target
node_src_gdb_server -->|"invokes"| node_src_flash_core
node_src_target_arm -.->|"exposes"| node_src_command
node_src_target_riscv -.->|"exposes"| node_src_command
node_doc -.->|"describes"| node_tcl_root
node_testing -.->|"exercises"| node_src_gdb_server

click node_src_main "https://github.com/openocd-org/openocd/blob/master/src/main.c"
click node_src_openocd "https://github.com/openocd-org/openocd/blob/master/src/openocd.c"
click node_src_command "https://github.com/openocd-org/openocd/blob/master/src/helper/command.c"
click node_src_tcl_server "https://github.com/openocd-org/openocd/blob/master/src/server/tcl_server.c"
click node_src_gdb_server "https://github.com/openocd-org/openocd/blob/master/src/server/gdb_server.c"
click node_src_telnet_server "https://github.com/openocd-org/openocd/blob/master/src/server/telnet_server.c"
click node_src_transport "https://github.com/openocd-org/openocd/blob/master/src/transport/transport.c"
click node_src_jtag_interfaces "https://github.com/openocd-org/openocd/blob/master/src/jtag/interfaces.c"
click node_src_jtag_core "https://github.com/openocd-org/openocd/blob/master/src/jtag/core.c"
click node_src_jtag_adapter "https://github.com/openocd-org/openocd/blob/master/src/jtag/adapter.c"
click node_src_jtag_drivers "https://github.com/openocd-org/openocd/blob/master/src/jtag/drivers/driver.c"
click node_src_target "https://github.com/openocd-org/openocd/blob/master/src/target/target.c"
click node_src_target_arm "https://github.com/openocd-org/openocd/blob/master/src/target/armv7m.c"
click node_src_target_riscv "https://github.com/openocd-org/openocd/blob/master/src/target/riscv/riscv.c"
click node_src_target_other "https://github.com/openocd-org/openocd/blob/master/src/target/mips32.c"
click node_src_flash_core "https://github.com/openocd-org/openocd/blob/master/src/flash/common.c"
click node_src_flash_nor "https://github.com/openocd-org/openocd/blob/master/src/flash/nor/core.c"
click node_src_flash_nand "https://github.com/openocd-org/openocd/blob/master/src/flash/nand/core.c"
click node_src_flash_loaders "https://github.com/openocd-org/openocd/tree/master/contrib/loaders"
click node_tcl_root "https://github.com/openocd-org/openocd/tree/master/tcl"
click node_src_helper "https://github.com/openocd-org/openocd/tree/master/src/helper"
click node_jimtcl "https://github.com/openocd-org/openocd/tree/master/jimtcl"
click node_doc "https://github.com/openocd-org/openocd/tree/master/doc"
click node_testing "https://github.com/openocd-org/openocd/tree/master/testing"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main,node_src_openocd,node_src_command,node_src_tcl_server,node_src_gdb_server,node_src_telnet_server toneBlue
class node_src_transport,node_src_jtag_interfaces,node_src_jtag_core,node_src_jtag_adapter,node_src_jtag_drivers toneAmber
class node_src_target,node_src_target_arm,node_src_target_riscv,node_src_target_other toneMint
class node_src_flash_core,node_src_flash_nor,node_src_flash_nand,node_src_flash_loaders toneRose
class node_tcl_root toneIndigo
class node_src_helper,node_jimtcl,node_doc,node_testing toneTeal
```

## Components

### Runtime

Daemon startup, command handling, servers, and Tcl-driven orchestration.

- [Main](https://github.com/openocd-org/openocd/blob/master/src/main.c): daemon entry · Process entry point and top-level initialization. · `src/main.c`
- [OpenOCD core](https://github.com/openocd-org/openocd/blob/master/src/openocd.c): daemon core · Primary startup and orchestration logic. · `src/openocd.c`
- [Commands](https://github.com/openocd-org/openocd/blob/master/src/helper/command.c): control plane · Command parser and shared command infrastructure. · `src/helper/command.c`
- [Tcl server](https://github.com/openocd-org/openocd/blob/master/src/server/tcl_server.c): server endpoint · Network Tcl control interface. · `src/server/tcl_server.c`
- [GDB server](https://github.com/openocd-org/openocd/blob/master/src/server/gdb_server.c): server endpoint · GDB remote protocol bridge to targets. · `src/server/gdb_server.c`
- [Telnet server](https://github.com/openocd-org/openocd/blob/master/src/server/telnet_server.c): server endpoint · Interactive CLI socket interface. · `src/server/telnet_server.c`

### Transport

Protocol selection and probe-facing signaling layers.

- [Transport](https://github.com/openocd-org/openocd/blob/master/src/transport/transport.c): protocol boundary · Abstracts the link between OpenOCD and the debug adapter. · `src/transport/transport.c`
- [Interfaces](https://github.com/openocd-org/openocd/blob/master/src/jtag/interfaces.c): mode select · Selects and configures JTAG, SWD, cJTAG, and related pathways. · `src/jtag/interfaces.c`
- [JTAG core](https://github.com/openocd-org/openocd/blob/master/src/jtag/core.c): state engine · Low-level TAP sequencing and scan-chain operations. · `src/jtag/core.c`
- [Adapter layer](https://github.com/openocd-org/openocd/blob/master/src/jtag/adapter.c): signal engine · Bit-level adapter control and transaction dispatch. · `src/jtag/adapter.c`
- [Probe drivers](https://github.com/openocd-org/openocd/blob/master/src/jtag/drivers/driver.c): hardware drivers · Concrete USB, GPIO, and remote probe backends. · `src/jtag/drivers/driver.c`

### Targets

CPU/architecture support and target abstractions.

- [Target core](https://github.com/openocd-org/openocd/blob/master/src/target/target.c): target abstraction · Common target model and execution services. · `src/target/target.c`
- [ARM](https://github.com/openocd-org/openocd/blob/master/src/target/armv7m.c): arch support · ARM, Cortex-M/A/R, debug, trace, and semihosting support. · `src/target/armv7m.c`
- [RISC-V](https://github.com/openocd-org/openocd/blob/master/src/target/riscv/riscv.c): arch support · RISC-V registers, program/debug, and GDB integration. · `src/target/riscv/riscv.c`
- [Other targets](https://github.com/openocd-org/openocd/blob/master/src/target/mips32.c): arch support · 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](https://github.com/openocd-org/openocd/blob/master/src/flash/common.c): flash manager · Common flash orchestration and device-independent services. · `src/flash/common.c`
- [NOR flash](https://github.com/openocd-org/openocd/blob/master/src/flash/nor/core.c): flash drivers · NOR flash framework and chip-family drivers. · `src/flash/nor/core.c`
- [NAND flash](https://github.com/openocd-org/openocd/blob/master/src/flash/nand/core.c): flash drivers · NAND flash framework and device-specific implementations. · `src/flash/nand/core.c`
- [Loaders](https://github.com/openocd-org/openocd/tree/master/contrib/loaders): target-side code · Target-resident flash/debug helper images and algorithms. · `contrib/loaders`

### Scripts

Declarative Tcl hardware models and startup scripts.

- [Tcl model](https://github.com/openocd-org/openocd/tree/master/tcl): runtime config · Declarative startup scripts and hardware descriptions. · `tcl`

### Support

Shared utilities, embedded interpreter, documentation, and collateral.

- [Helpers](https://github.com/openocd-org/openocd/tree/master/src/helper): shared support · Logging, buffers, file I/O, configuration, and utility code. · `src/helper`
- [Jim Tcl](https://github.com/openocd-org/openocd/tree/master/jimtcl): embedded interpreter · Embedded Tcl interpreter used for configuration and automation. · `jimtcl`
- [Docs](https://github.com/openocd-org/openocd/tree/master/doc): documentation · User guide, manuals, and reference material. · `doc`
- [Testing](https://github.com/openocd-org/openocd/tree/master/testing): collateral · Example projects, smoke tests, and regression assets. · `testing`

## Connections

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