# metagur/nds-openocd architecture

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

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

## Overview

##### Project type and purpose
- OpenOCD is an **open-source, command-line on-chip debugger and programmer**.
- It provides a layered architecture of:
- Transport and adapter drivers (e.g. USB, FTDI, bit-bang)
- A JTAG/SWD core with TAP and target support
- Flash and (X)SVF/CPLD programming engines
- Embedded Tcl interpreter and network servers (GDB, Telnet, TCL)

##### Main architectural components
a. User Interfaces (CLI & Scripting)
- `openocd.c` / `main.c`: command-line entry point
- Embedded Jim-Tcl interpreter (in `jimtcl/`, `tcl/`)
- Network servers: GDB server, Telnet server, Tcl server (`src/server/`)
b. Command Dispatcher & Configuration
- Parses CLI args and config scripts (`src/helper/` modules)
- Loads board/interface/target config files (`tcl/board/`, `tcl/interface/`, `tcl/target/`)
c. Transport Layer
- Abstraction in `src/transport/`
- Supports USB, parallel, sysfs-GPIO, etc.
d. Adapter Drivers (JTAG/SWD Interfaces)
- `src/jtag/transport` and `src/jtag/drivers/`
- Plugin-style drivers for FTDI, CMSIS-DAP, Bus Pirate, OpenOCD-USB, etc.
e. JTAG/SWD Core & TAP Engine
- `src/jtag/core.c`, `src/jtag/interface.c`, `src/jtag/adapter.c`
- Manages TAP state machine, IR/DR shifts
f. Target Support
- `src/target/`: per-architecture modules (ARMv7, RISC-V, MIPS, etc.)
- Implements register access, semihosting, simulators, caches, breakpoints
g. Flash Programming & SVF Engines
- `src/flash/`: NOR & NAND flash drivers, `src/svf/` and `src/xsvf/`
h. Optional RTOS Helpers & RTT
- `src/rtos/`, `src/rtt/` for RTOS hooks and real-time trace
i. TCL Scripts
- High-level procedure scripts under `tcl/` for board, chip, interface, etc.
j. Contrib and Tooling
- Build helpers, cross-build scripts, testing examples in `contrib/`, `tools/`, `testing/`

##### Relationships & Data Flow
- **User** invokes `openocd` → **CLI**
- CLI → **Command Dispatcher** loads **Tcl scripts/configs**
- Dispatcher → initializes **Transport** + **Adapter Driver**
- Adapter → drives signals into **JTAG/SWD Core**
- Core → uses **TAP engine** to communicate with **Target modules**
- Target modules → optional **Flash/SVF engines** for memory programming
- Meanwhile, the **Network Servers** expose GDB/Telnet/Tcl protocols to clients, routing commands into the Dispatcher and back out to the Target layer
- All components can be treated as loadable “plugins”

##### Architectural Patterns & Principles
- **Layered architecture**: clear separation of UI, dispatch, transport, core, target
- **Plugin/extensibility**: adapters, targets, flash drivers, network servers loaded at runtime
- **Interpreter pattern**: embedded Tcl for scriptable control
- **Autotools build**: modular Makefile.am in each directory

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::user
    %% UI & Scripting
    subgraph "UI & Scripting"
        CLI1["openocd.c"]:::ui
        CLI2["main.c"]:::ui
        TclInterp["Embedded Tcl Interpreter\n(jimtcl/, tcl/)"]:::script
    end

    %% Command Dispatcher & Configuration
    subgraph "Command Dispatcher & Configuration"
        Dispatcher["Dispatcher & Config\n(src/helper/)"]:::backend
    end

    %% Transport Layer
    subgraph "Transport Layer"
        Transport["Transport Layer\n(src/transport/)"]:::transport
    end

    %% Adapter Drivers
    subgraph "Adapter Drivers"
        Adapter["Adapter Drivers\n(src/jtag/drivers/)"]:::transport
    end

    %% JTAG/SWD Core & TAP Engine
    subgraph "JTAG/SWD Core & TAP Engine"
        Core["Core & TAP Engine\n(src/jtag/)"]:::core
    end

    %% Target Support Modules
    subgraph "Target Modules"
        Target["Target Modules\n(src/target/)"]:::target
    end

    %% Flash Programming & SVF Engines
    subgraph "Flash & SVF Engines"
        Flash["Flash & SVF Engines\n(src/flash/, src/svf/, src/xsvf/)"]:::storage
    end

    %% Network Servers
    subgraph "Network Servers"
        Servers["Network Servers\n(src/server/)"]:::network
    end

    %% Connections
    User -->|"invokes"| CLI1
    User -->|"invokes"| CLI2
    CLI1 -->|"starts"| Dispatcher
    CLI2 -->|"starts"| Dispatcher
    TclInterp -->|"provides scripts"| Dispatcher
    Dispatcher -->|"initializes"| Transport
    Transport -->|"selects driver"| Adapter
    Adapter -->|"drives signals"| Core
    Core -->|"executes TAP"| Target
    Target -->|"memory ops"| Flash
    Servers -->|"routes GDB/Telnet/Tcl"| Dispatcher
    Servers -->|"direct commands"| Core
    Servers -->|"access targets"| Target

    %% Click Events
    click CLI1 "https://github.com/metagur/nds-openocd/blob/ast-v5_3_0-branch/src/openocd.c"
    click CLI2 "https://github.com/metagur/nds-openocd/blob/ast-v5_3_0-branch/src/main.c"
    click TclInterp "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/jimtcl/"
    click TclInterp "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/tcl/"
    click Dispatcher "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/helper/"
    click Transport "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/transport/"
    click Adapter "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/jtag/drivers/"
    click Core "https://github.com/metagur/nds-openocd/blob/ast-v5_3_0-branch/src/jtag/core.c"
    click Target "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/target/"
    click Flash "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/flash/"
    click Servers "https://github.com/metagur/nds-openocd/tree/ast-v5_3_0-branch/src/server/"

    %% Styles
    classDef ui fill:#D6E9FE,stroke:#1E6FB2;
    classDef script fill:#E8DFF5,stroke:#8E44AD;
    classDef backend fill:#D6F5D6,stroke:#28A745;
    classDef transport fill:#D1F2EB,stroke:#117A65;
    classDef core fill:#FDDEA5,stroke:#D35400;
    classDef target fill:#FCF3CF,stroke:#B7950B;
    classDef storage fill:#FADBD8,stroke:#C0392B;
    classDef network fill:#EBDEF0,stroke:#6C3483;
    classDef user fill:#FFFFFF,stroke:#000000;
```
