# armmbed/daplink architecture

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

- Interactive diagram: https://gitdiagram.com/armmbed/daplink
- Repository: https://github.com/armmbed/daplink

## Overview

##### Project Type and Purpose
- This is an embedded interface‐firmware project (“DAPLink”) that runs on a secondary MCU (HIC), exposes a USB composite device to the host (PC), and bridges to a target MCU via SWD/JTAG.
- Key use cases: MSC (mass‐storage drag-and-drop programming), CDC (virtual COM port), CMSIS-DAP debug channels (HID, WinUSB, WebUSB).

##### File Structure—Top-Level Modules
- source/board       → board-specific initialization and overrides
- source/target      → target configuration abstraction
- source/family      → per-vendor flash blobs and target reset logic
- source/hic_hal     → hardware-abstraction layer (GPIO, USB PHY, peripheral drivers)
- source/cmsis-core  → ARM CMSIS core headers and startup code
- source/rtos*       → RTOS kernels (CMSIS-RTOS1 and RTOS2)
- source/daplink     → main interface logic (USB interface dispatch, settings, flash manager)
- source/usb         → USB device stack and class drivers (MSC, CDC, HID, WebUSB)
- tools/             → Python and shell scripts for generating configs, building, packaging
- test/              → Python test harnesses and unit tests
- docs/              → user, developer, board-porting, troubleshooting guides

##### README for Insights
- Confirms the four host interfaces (MSC, CDC, CMSIS-DAPv1 HID, CMSIS-DAPv2 WinUSB, WebUSB).
- Mentions quarterly and on-demand releases, CI via GitHub Actions.
- Points to developers’ guide for build and test flows.

##### Main Components & Their Interactions
a. Hardware Abstraction Layer (HAL)
- Board-specific code (source/board) + family flash blobs (source/family) + hic_hal drivers → sets up clocks, pins, USB PHY, memory.
b. RTOS Kernel
- CMSIS-RTOS1 or RTOS2 scheduler (source/rtos, source/rtos2) → task scheduling, inter-task messaging.
c. DAPLink Core
- Main interface (source/daplink/main_interface.c) → initializes USB stack, RTOS, modules; dispatches USB events; manages settings (flash storage).
- Settings Manager (source/daplink/settings) → reads/writes device configuration in non-volatile storage.
- Flash Manager / Drag-n-Drop (source/daplink/drag-n-drop) → virtual FS, flash programming via in-application programming (IAP) through SWD.
d. USB Device Stack
- Core USB (source/usb/usbd_core) → enumeration, endpoint management.
- Class Drivers: MSC, CDC, HID (CMSIS-DAP), WebUSB, WinUSB → expose endpoints to host.
e. CMSIS-DAP Host Driver
- Implements SWD/JTAG protocol over HID or vendor bulk → source/daplink/cmsis-dap & hic_hal/SWD host driver.
f. Target Communication
- Runs via SWD/JTAG port on application MCU → uses flash algorithms (source/family) and target_reset code (source/target).
g. Build & Test Infrastructure
- YAML board definitions (projects.yaml + records/) + Python tools (tools/generate_config.py) → generate per-board build configs.
- CI pipelines (.github/workflows) → build, test on Linux/Windows.
- Unit and acceptance tests (test/) → validate USB classes, board logic.

##### Architectural Patterns & Principles
- Layered Architecture: HAL → RTOS → Core → Interfaces → USB Stack → Host.
- Plugin-style Extensibility: board/family modules loaded at build time based on YAML configs.
- Separation of Concerns: distinct modules for USB, flash, settings, SWD transport.
- Build-time Meta-Programming: Python tools generate C headers from YAML.

##### Technologies & Frameworks
- C language, GCC/ArmCC/ArmClang toolchains
- CMSIS-Core & CMSIS-Driver
- CMSIS-RTOS1 and RTOS2 (RTX)
- USB device stack (USBD library)
- Python 3 for tools and tests
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hardware Abstraction Layer (HAL)"
        direction TB
        BOARD["Board-specific code\n(source/board/)"]:::hal
        HIC_HAL["MCU HAL drivers\n(source/hic_hal/)"]:::hal
        CMSIS_CORE["CMSIS core headers & startup\n(source/cmsis-core/)"]:::hal
    end

    subgraph "RTOS Kernel"
        direction TB
        RTOS1["CMSIS-RTOS1 (RTX)\n(source/rtos/)"]:::rtos
        RTOS2["CMSIS-RTOS2 (RTX2)\n(source/rtos2/)"]:::rtos
        RTOS_NONE["No-OS stub\n(source/rtos_none/)"]:::rtos
    end

    subgraph "DAPLink Core"
        direction TB
        MAIN_IF["Main Interface\n(source/daplink/interface/main_interface.c)"]:::core
        SETTINGS["Settings Manager\n(source/daplink/settings/)"]:::core
        FLASH_MGR["Flash Manager\n(source/daplink/drag-n-drop/)"]:::core
        CIRC_BUF["Circular Buffer\n(source/daplink/circ_buf.c)"]:::core
        UTIL["Utilities\n(source/daplink/util.c)"]:::core
        INFO["Info & Version\n(source/daplink/info.c)"]:::core
    end

    subgraph "USB Device Stack"
        direction TB
        USB_CORE["USB Core\n(source/usb/usbd_core.c)"]:::usb
        MSC["MSC Driver\n(source/usb/msc/)"]:::usb
        CDC["CDC Driver\n(source/usb/cdc/)"]:::usb
        HID["HID Driver\n(source/usb/hid/)"]:::usb
        WEBUSB["WebUSB Driver\n(source/usb/webusb/)"]:::usb
        WINUSB["WinUSB Driver\n(source/usb/winusb/)"]:::usb
    end

    subgraph "CMSIS-DAP Host Driver"
        direction TB
        DAP["DAP Protocol\n(source/daplink/cmsis-dap/)"]:::usb
        SWD_HOST["SWD Host\n(source/daplink/interface/swd_host.c)"]:::usb
    end

    subgraph "Target Communication"
        direction TB
        TARGET_BOARD["Target API\n(source/target/)"]:::target
        FAMILY["Flash Blobs & Reset\n(source/family/)"]:::target
    end

    subgraph "Build-time Config & Code-Gen"
        direction TB
        YAML["YAML Definitions\n(projects.yaml, records/)"]:::build
        PY_GEN["Python Generators\n(tools/generate_config.py)"]:::build
    end

    subgraph "Host PC Interfaces"
        direction TB
        HOST_MSC["Mass Storage"]:::host
        HOST_CDC["Serial Port (CDC)"]:::host
        HOST_HID["Debug HID (CMSIS-DAPv1)"]:::host
        HOST_WINUSB["Debug WinUSB (CMSIS-DAPv2)"]:::host
        HOST_WEBUSB["WebUSB"]:::host
    end

    HW_PINS["MCU Pins & Clocks"]:::hal
    HW_SWD["SWD/JTAG Interface"]:::hal
    HW_FLASH["Target Flash"]:::hal

    BOARD --> HW_PINS
    HIC_HAL --> HW_PINS
    CMSIS_CORE --> HW_PINS

    RTOS1 --> MAIN_IF
    RTOS2 --> MAIN_IF
    RTOS_NONE --> MAIN_IF

    MAIN_IF --> SETTINGS
    MAIN_IF --> FLASH_MGR
    MAIN_IF --> DAP
    MAIN_IF --> UTIL
    MAIN_IF --> INFO
    SETTINGS --> HW_FLASH
    FLASH_MGR --> FAMILY

    USB_CORE --> MSC
    USB_CORE --> CDC
    USB_CORE --> HID
    USB_CORE --> WEBUSB
    USB_CORE --> WINUSB

    MSC --> MAIN_IF
    CDC --> MAIN_IF
    HID --> MAIN_IF
    WEBUSB --> MAIN_IF
    WINUSB --> MAIN_IF

    HOST_MSC --> MSC
    HOST_CDC --> CDC
    HOST_HID --> HID
    HOST_WINUSB --> WINUSB
    HOST_WEBUSB --> WEBUSB

    DAP --> SWD_HOST
    SWD_HOST --> HW_SWD
    SWD_HOST --> TARGET_BOARD
    TARGET_BOARD --> FAMILY

    YAML --> PY_GEN
    PY_GEN --> BOARD
    PY_GEN --> HIC_HAL
    PY_GEN --> CMSIS_CORE
    PY_GEN --> RTOS1
    PY_GEN --> RTOS2
    PY_GEN --> USB_CORE

    click BOARD "https://github.com/armmbed/daplink/tree/main/source/board/"
    click HIC_HAL "https://github.com/armmbed/daplink/tree/main/source/hic_hal/"
    click CMSIS_CORE "https://github.com/armmbed/daplink/tree/main/source/cmsis-core/"
    click RTOS1 "https://github.com/armmbed/daplink/tree/main/source/rtos/"
    click RTOS2 "https://github.com/armmbed/daplink/tree/main/source/rtos2/"
    click RTOS_NONE "https://github.com/armmbed/daplink/tree/main/source/rtos_none/"
    click MAIN_IF "https://github.com/armmbed/daplink/blob/main/source/daplink/interface/main_interface.c"
    click SETTINGS "https://github.com/armmbed/daplink/blob/main/source/daplink/settings/settings.c"
    click FLASH_MGR "https://github.com/armmbed/daplink/blob/main/source/daplink/drag-n-drop/flash_manager.c"
    click CIRC_BUF "https://github.com/armmbed/daplink/blob/main/source/daplink/circ_buf.c"
    click UTIL "https://github.com/armmbed/daplink/blob/main/source/daplink/util.c"
    click INFO "https://github.com/armmbed/daplink/blob/main/source/daplink/info.c"
    click USB_CORE "https://github.com/armmbed/daplink/blob/main/source/usb/usbd_core.c"
    click MSC "https://github.com/armmbed/daplink/blob/main/source/usb/msc/usbd_core_msc.c"
    click CDC "https://github.com/armmbed/daplink/blob/main/source/usb/cdc/usbd_cdc_acm.c"
    click HID "https://github.com/armmbed/daplink/blob/main/source/usb/hid/usbd_hid.c"
    click WEBUSB "https://github.com/armmbed/daplink/blob/main/source/usb/webusb/usbd_core_webusb.c"
    click WINUSB "https://github.com/armmbed/daplink/blob/main/source/usb/winusb/usbd_core_winusb.c"
    click DAP "https://github.com/armmbed/daplink/blob/main/source/daplink/cmsis-dap/DAP.c"
    click SWD_HOST "https://github.com/armmbed/daplink/blob/main/source/daplink/interface/swd_host.c"
    click TARGET_BOARD "https://github.com/armmbed/daplink/blob/main/source/target/target_board.c"
    click FAMILY "https://github.com/armmbed/daplink/blob/main/source/family/flash_blob.c"
    click YAML "https://github.com/armmbed/daplink/blob/main/projects.yaml"
    click PY_GEN "https://github.com/armmbed/daplink/blob/main/tools/generate_config.py"

    classDef hal fill:#cce5ff,stroke:#000
    classDef rtos fill:#ccffcc,stroke:#000
    classDef core fill:#ffdb99,stroke:#000
    classDef usb fill:#e0ccff,stroke:#000
    classDef host fill:#e8e8e8,stroke:#000
    classDef build fill:#fff2cc,stroke:#000
    classDef target fill:#ffe6e6,stroke:#000
```
