# espressif/openocd-esp32 architecture

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

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

## Overview

1. This repository is OpenOCD, a host-side daemon for on-chip debugging and programming. Its central role is to translate high-level debugger commands from GDB, Tcl, telnet, and script files into adapter-level JTAG/SWD/SPI operations against an embedded target.

2. The top-level runtime is in `src/`. `src/main.c` and `src/openocd.c` bootstrap the process, load configuration, initialize transports and drivers, then start the network services. The code is organized as a layered stack: command/configuration handling, transport selection, adapter drivers, target-specific logic, and flash/programming services.

3. Configuration is script-driven and forms a major architectural boundary. The large `tcl/` tree contains reusable Tcl modules plus per-board, per-interface, per-target, and per-chip configuration files. Startup scripts in `src/*/startup.tcl` and `tcl/startup` files wire these definitions into the runtime, so the same binary can be adapted to many hardware setups without recompilation.

4. The adapter layer lives mainly under `src/jtag/`. It contains the core JTAG/SWD abstractions, plus a wide set of concrete transport drivers in `src/jtag/drivers/` for FTDI, CMSIS-DAP, ST-LINK, J-Link, XDS110, USB-Blaster, Raspberry Pi GPIO, Linux gpiod, remote bitbang, and many others. This layer is the hardware-facing edge of the host application, talking to USB, GPIO, parallel port, or remote protocol endpoints.

5. The target layer is in `src/target/`. It models CPU families and debug access mechanisms: ARM/Thumb/Cortex, RISC-V, Xtensa, MIPS, ARC, OpenRISC, AVR32, STM8, and vendor-specific variants. This layer owns halt/resume, register access, breakpoints/watchpoints, semihosting, memory access, SMP, and architecture-specific debug state handling.

6. Flash programming is a separate subsystem under `src/flash/`. `src/flash/common.c` and the NOR/NAND subtrees provide generic flash command handling and chip-family drivers. The flow is typically: OpenOCD receives a flash operation, the target layer provides memory access or stub execution, and the flash driver performs erase/program/verify using either direct register access or a downloaded algorithm.

7. There is a large “downloaded algorithm” model for performance-sensitive flash and debug tasks. `contrib/loaders/` contains prebuilt target-side loader sources and assembly stubs, while `contrib/firmware/` includes adapter firmware such as OpenULINK/Angie. For some targets, OpenOCD uploads a small RAM-resident stub, then uses that stub to accelerate flash writes, checksums, erase checks, or special debug operations.

8. OpenOCD exposes several front-end services in `src/server/`: a GDB remote protocol server, a Tcl server, a telnet server, and RTT/IPDBG-related services. These are the main external interfaces into the daemon. GDB is the most important for source-level debugging; Tcl and telnet are the scripting/control paths; RTT provides low-overhead target-to-host logging and data exchange.

9. The repository has notable vendor-specific specialization for Espressif devices. `src/target/espressif/` and `src/flash/nor/esp*.c` implement ESP32-family debugging and flash support, including Xtensa/RISC-V variations, apptrace, semihosting, SMP helpers, and target-side trampolines. The `contrib/loaders/flash/espressif/` tree contains generated stub images and linker scripts for multiple ESP variants, and `testing/esp/` contains a dedicated test harness and device/app scenarios.

10. Trace and streaming features are represented as first-class subsystems. `src/rtt/` and `src/server/rtt_server.c` handle Real Time Transfer; `src/target/trace.c`, `src/target/arm_tpiu_swo.c`, and architecture-specific trace code support SWO/ETM-style capture; Espressif apptrace/sysview support is implemented in both target-side and host-side code. These features form a separate data path from the normal debug register/memory flow.

11. FPGA/CPLD and serial protocol support are also part of the architecture. `src/svf/` and `src/xsvf/` implement playback of scan-chain programming files, while `src/pld/` handles device-specific FPGA bitstream and configuration flows. This is a parallel use case to CPU debugging, but it still uses the same adapter/transport layer underneath.

12. The build system is split between Autotools and CMake, with supporting scripts under `cmake/`, `configure.ac`, and `Makefile.am` files throughout `src/`. External dependencies matter structurally: libjim provides the embedded Tcl interpreter, libusb/libftdi/libjaylink/HIDAPI/libgpiod enable adapter backends, and optional capstone supports disassembly. Cross-compilation is a first-class concern, reflected in `contrib/cross-build.sh` and multiple CI matrices.

13. Validation and release engineering are extensive. `testing/` contains Tcl command tests, protocol tests, and hardware-oriented regression suites; `testing/esp/` adds Python-based backend and target tests. CI is split across GitHub Actions and GitLab pipelines, and the `tools/` directory contains release, log filtering, config validation, and generated-report utilities. This indicates a project architecture optimized for broad hardware coverage and long-tail regression control.

Main entry points: [`src/openocd.c`](https://github.com/espressif/openocd-esp32/blob/master/src/openocd.c) (Core), [`src/target/target.c`](https://github.com/espressif/openocd-esp32/blob/master/src/target/target.c) (Target Core), [`src/flash/common.c`](https://github.com/espressif/openocd-esp32/blob/master/src/flash/common.c) (Flash Core), [`src/server/server.c`](https://github.com/espressif/openocd-esp32/blob/master/src/server/server.c) (Servers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_n_main["Main<br/>bootstrap/entry<br/>[main.c]"]
  node_n_openocd["Core<br/>[openocd.c]"]
  node_n_helper["Helpers<br/>shared runtime utils"]
end

subgraph group_grp_transport["Transport"]
  node_n_transport["Transport<br/>bus/selection<br/>[transport.c]"]
  node_n_jtag_core["JTAG Core<br/>adapter core<br/>[core.c]"]
  node_n_jtag_api["Adapter API<br/>[adapter.c]"]
  node_n_jtag_drivers["Drivers<br/>hardware backends"]
  node_n_hla["HLA<br/>high-level adapter"]
end

subgraph group_grp_target["Targets"]
  node_n_target_core["Target Core<br/>target framework<br/>[target.c]"]
  node_n_arm["ARM<br/>architecture family<br/>[armv7m.c]"]
  node_n_riscv["RISC-V<br/>architecture family<br/>[riscv.c]"]
  node_n_xtensa["Xtensa<br/>architecture family<br/>[xtensa.c]"]
end

subgraph group_grp_programming["Programming"]
  node_n_flash_core["Flash Core<br/>flash framework<br/>[common.c]"]
  node_n_nor["NOR Flash<br/>flash drivers"]
  node_n_nand["NAND Flash<br/>flash drivers"]
  node_n_pld["PLD/SVF<br/>scan-chain programming"]
end

subgraph group_grp_frontends["Frontends"]
  node_n_server["Servers<br/>front-end services<br/>[server.c]"]
  node_n_gdb["GDB<br/>remote protocol<br/>[gdb_server.c]"]
  node_n_tcl_telnet["Tcl/Telnet<br/>command shell<br/>[tcl_server.c]"]
end

subgraph group_grp_esp["Espressif"]
  node_n_esp_target["ESP Targets<br/>vendor target stack"]
  node_n_rtt_trace["RTT/Trace<br/>streaming path"]
end

subgraph group_grp_scripts["Scripts"]
  node_n_tcl_cfg["Tcl Config<br/>configuration scripts"]
end

subgraph group_grp_quality["Quality"]
  node_n_testing["Testing<br/>regression suite"]
  node_n_tools["Tools<br/>release/validation"]
end

node_n_main -->|"starts"| node_n_openocd
node_n_openocd -->|"uses"| node_n_helper
node_n_openocd -->|"selects"| node_n_transport
node_n_openocd -->|"starts"| node_n_server
node_n_openocd -->|"loads"| node_n_tcl_cfg
node_n_transport -->|"binds"| node_n_jtag_core
node_n_jtag_core -->|"defines"| node_n_jtag_api
node_n_jtag_core -->|"dispatches"| node_n_jtag_drivers
node_n_jtag_core -->|"supports"| node_n_hla
node_n_jtag_drivers -->|"talks to"| node_n_target_core
node_n_hla -->|"bridges"| node_n_target_core
node_n_target_core -->|"specializes"| node_n_arm
node_n_target_core -->|"specializes"| node_n_riscv
node_n_target_core -->|"specializes"| node_n_xtensa
node_n_target_core -->|"extends"| node_n_esp_target
node_n_openocd -->|"invokes"| node_n_flash_core
node_n_flash_core -->|"routes"| node_n_nor
node_n_flash_core -->|"routes"| node_n_nand
node_n_flash_core -->|"routes"| node_n_pld
node_n_openocd -->|"serves"| node_n_gdb
node_n_openocd -->|"serves"| node_n_tcl_telnet
node_n_server -->|"hosts"| node_n_gdb
node_n_server -->|"hosts"| node_n_tcl_telnet
node_n_server -->|"hosts"| node_n_rtt_trace
node_n_tcl_cfg -->|"configures"| node_n_jtag_drivers
node_n_tcl_cfg -->|"configures"| node_n_target_core
node_n_tcl_cfg -->|"specializes"| node_n_esp_target
node_n_esp_target -->|"adds"| node_n_rtt_trace
node_n_esp_target -->|"extends"| node_n_flash_core
node_n_testing -->|"exercises"| node_n_server
node_n_testing -->|"validates"| node_n_tcl_cfg
node_n_tools -->|"supports"| node_n_testing

click node_n_main "https://github.com/espressif/openocd-esp32/blob/master/src/main.c"
click node_n_openocd "https://github.com/espressif/openocd-esp32/blob/master/src/openocd.c"
click node_n_helper "https://github.com/espressif/openocd-esp32/tree/master/src/helper"
click node_n_transport "https://github.com/espressif/openocd-esp32/blob/master/src/transport/transport.c"
click node_n_jtag_core "https://github.com/espressif/openocd-esp32/blob/master/src/jtag/core.c"
click node_n_jtag_api "https://github.com/espressif/openocd-esp32/blob/master/src/jtag/adapter.c"
click node_n_jtag_drivers "https://github.com/espressif/openocd-esp32/tree/master/src/jtag/drivers"
click node_n_hla "https://github.com/espressif/openocd-esp32/tree/master/src/jtag/hla"
click node_n_target_core "https://github.com/espressif/openocd-esp32/blob/master/src/target/target.c"
click node_n_arm "https://github.com/espressif/openocd-esp32/blob/master/src/target/armv7m.c"
click node_n_riscv "https://github.com/espressif/openocd-esp32/blob/master/src/target/riscv/riscv.c"
click node_n_xtensa "https://github.com/espressif/openocd-esp32/blob/master/src/target/xtensa/xtensa.c"
click node_n_esp_target "https://github.com/espressif/openocd-esp32/tree/master/src/target/espressif"
click node_n_flash_core "https://github.com/espressif/openocd-esp32/blob/master/src/flash/common.c"
click node_n_nor "https://github.com/espressif/openocd-esp32/tree/master/src/flash/nor"
click node_n_nand "https://github.com/espressif/openocd-esp32/tree/master/src/flash/nand"
click node_n_pld "https://github.com/espressif/openocd-esp32/tree/master/src/pld"
click node_n_server "https://github.com/espressif/openocd-esp32/blob/master/src/server/server.c"
click node_n_gdb "https://github.com/espressif/openocd-esp32/blob/master/src/server/gdb_server.c"
click node_n_tcl_telnet "https://github.com/espressif/openocd-esp32/blob/master/src/server/tcl_server.c"
click node_n_rtt_trace "https://github.com/espressif/openocd-esp32/tree/master/src/rtt"
click node_n_tcl_cfg "https://github.com/espressif/openocd-esp32/tree/master/tcl"
click node_n_testing "https://github.com/espressif/openocd-esp32/tree/master/testing"
click node_n_tools "https://github.com/espressif/openocd-esp32/tree/master/tools"

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_n_main,node_n_openocd,node_n_helper,node_n_tcl_cfg toneBlue
class node_n_transport,node_n_jtag_core,node_n_jtag_api,node_n_jtag_drivers,node_n_hla,node_n_testing,node_n_tools toneAmber
class node_n_target_core,node_n_arm,node_n_riscv,node_n_xtensa toneMint
class node_n_flash_core,node_n_nor,node_n_nand,node_n_pld toneRose
class node_n_server,node_n_gdb,node_n_tcl_telnet toneIndigo
class node_n_esp_target,node_n_rtt_trace toneTeal
```

## Components

### Runtime

Process bootstrap, command handling, and service startup

- [Main](https://github.com/espressif/openocd-esp32/blob/master/src/main.c): bootstrap/entry · Process entrypoint and top-level startup flow · `src/main.c`
- [Core](https://github.com/espressif/openocd-esp32/blob/master/src/openocd.c): daemon core · Central daemon orchestration and runtime control · `src/openocd.c`
- [Helpers](https://github.com/espressif/openocd-esp32/tree/master/src/helper): shared runtime utils · Common command, logging, config, and utility support · `src/helper`

### Transport

Adapter selection and hardware-facing JTAG/SWD backends

- [Transport](https://github.com/espressif/openocd-esp32/blob/master/src/transport/transport.c): bus/selection · Transport abstraction that routes requests to adapter backends · `src/transport/transport.c`
- [JTAG Core](https://github.com/espressif/openocd-esp32/blob/master/src/jtag/core.c): adapter core · Core JTAG/SWD adapter layer and command handling · `src/jtag/core.c`
- [Adapter API](https://github.com/espressif/openocd-esp32/blob/master/src/jtag/adapter.c): adapter API · Adapter interface and high-level JTAG command glue · `src/jtag/adapter.c`
- [Drivers](https://github.com/espressif/openocd-esp32/tree/master/src/jtag/drivers): hardware backends · Concrete adapter drivers for USB, GPIO, remote, and vendor probes · `src/jtag/drivers`
- [HLA](https://github.com/espressif/openocd-esp32/tree/master/src/jtag/hla): high-level adapter · High-level adapter transport and layout support · `src/jtag/hla`

### Targets

CPU and debug-state modeling across architectures

- [Target Core](https://github.com/espressif/openocd-esp32/blob/master/src/target/target.c): target framework · Target model, registers, breakpoints, SMP, and request handling · `src/target/target.c`
- [ARM](https://github.com/espressif/openocd-esp32/blob/master/src/target/armv7m.c): architecture family · ARM and Cortex debug, trace, and semihosting support · `src/target/armv7m.c`
- [RISC-V](https://github.com/espressif/openocd-esp32/blob/master/src/target/riscv/riscv.c): architecture family · RISC-V register, program, and debug-module support · `src/target/riscv/riscv.c`
- [Xtensa](https://github.com/espressif/openocd-esp32/blob/master/src/target/xtensa/xtensa.c): architecture family · Xtensa target support and debug module integration · `src/target/xtensa/xtensa.c`

### Programming

Flash, PLD, and scan-chain programming subsystems

- [Flash Core](https://github.com/espressif/openocd-esp32/blob/master/src/flash/common.c): flash framework · Common flash command handling and driver coordination · `src/flash/common.c`
- [NOR Flash](https://github.com/espressif/openocd-esp32/tree/master/src/flash/nor): flash drivers · NOR flash family drivers and SPI/CFI helpers · `src/flash/nor`
- [NAND Flash](https://github.com/espressif/openocd-esp32/tree/master/src/flash/nand): flash drivers · NAND flash core, ECC, file I/O, and board-specific support · `src/flash/nand`
- [PLD/SVF](https://github.com/espressif/openocd-esp32/tree/master/src/pld): scan-chain programming · FPGA/CPLD configuration flows and SVF/XSVF playback · `src/pld`

### Frontends

Network and command interfaces into the daemon

- [Servers](https://github.com/espressif/openocd-esp32/blob/master/src/server/server.c): front-end services · Network services exposed by the daemon · `src/server/server.c`
- [GDB](https://github.com/espressif/openocd-esp32/blob/master/src/server/gdb_server.c): remote protocol · GDB remote server interface for source-level debugging · `src/server/gdb_server.c`
- [Tcl/Telnet](https://github.com/espressif/openocd-esp32/blob/master/src/server/tcl_server.c): command shell · Interactive scripting and telnet control interfaces · `src/server/tcl_server.c`

### Espressif

ESP-specific target, flash, tracing, and stub infrastructure

- [ESP Targets](https://github.com/espressif/openocd-esp32/tree/master/src/target/espressif): vendor target stack · Espressif target logic for Xtensa and RISC-V variants · `src/target/espressif`
- [RTT/Trace](https://github.com/espressif/openocd-esp32/tree/master/src/rtt): streaming path · RTT, SWO/ETM-style trace, and apptrace data paths · `src/rtt`

### Scripts

Tcl configuration and startup layering

- [Tcl Config](https://github.com/espressif/openocd-esp32/tree/master/tcl): configuration scripts · Board, interface, target, and chip startup configuration trees · `tcl`

### Quality

Tests, validation, and release tooling

- [Testing](https://github.com/espressif/openocd-esp32/tree/master/testing): regression suite · Protocol, Tcl, hardware, and ESP-specific test harnesses · `testing`
- [Tools](https://github.com/espressif/openocd-esp32/tree/master/tools): release/validation · Release scripts, config validators, log filters, and utilities · `tools`

## Connections

- Main → Core: starts · Bootstraps the daemon lifecycle
- Core → Helpers: uses · Relies on shared runtime helpers
- Core → Transport: selects · Chooses and initializes transports
- Core → Servers: starts · Brings up external services
- Core → Tcl Config: loads · Consumes startup and board configuration
- Transport → JTAG Core: binds · Transport layer feeds adapter operations
- JTAG Core → Adapter API: defines · Shares the adapter-facing API
- JTAG Core → Drivers: dispatches · Routes to concrete hardware backends
- JTAG Core → HLA: supports · Includes high-level adapter variants
- Drivers → Target Core: talks to · Hardware adapters drive target debug access
- HLA → Target Core: bridges · High-level adapters connect to targets
- Target Core → ARM: specializes · Architecture-specific ARM execution/debug logic
- Target Core → RISC-V: specializes · Architecture-specific RISC-V debug logic
- Target Core → Xtensa: specializes · Architecture-specific Xtensa debug logic
- Target Core → ESP Targets: extends · Vendor-specific Espressif target behaviors
- Core → Flash Core: invokes · Flash commands flow through programming services
- Flash Core → NOR Flash: routes · NOR drivers implement most flash operations
- Flash Core → NAND Flash: routes · NAND subsystem handles parallel flash operations
- Flash Core → PLD/SVF: routes · PLD flows share the same adapter foundation
- Core → GDB: serves · Primary debugger-facing protocol endpoint
- Core → Tcl/Telnet: serves · Interactive control and scripting endpoints
- Servers → GDB: hosts · Server framework hosts the GDB service
- Servers → Tcl/Telnet: hosts · Server framework hosts command shells
- Servers → RTT/Trace: hosts · Server framework exposes RTT services
- Tcl Config → Drivers: configures · Interface scripts choose adapter backends
- Tcl Config → Target Core: configures · Target scripts define CPU and board setup
- Tcl Config → ESP Targets: specializes · ESP board and chip scripts tune vendor flows
- ESP Targets → RTT/Trace: adds · Adds apptrace/sysview and related streaming paths
- ESP Targets → Flash Core: extends · Vendor flash support plugs into common flash flow
- Testing → Servers: exercises · Regression suites drive exposed services
- Testing → Tcl Config: validates · Configuration checks cover script boundaries
- Tools → Testing: supports · Release and validation utilities aid test workflows
