# jimx-/softssd architecture

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

- Interactive diagram: https://gitdiagram.com/jimx-/softssd
- Repository: https://github.com/jimx-/softssd

## Overview

##### Project Type and Purpose
- This is an embedded, multi-core firmware project targeting an SoC with three processing elements:
- Cortex-A53 (A53)
- Arm Cortex-R5_0 (R5_0)
- Arm Cortex-R5_1 (R5_1)
- Each core runs its own bare-metal application:
- A53 runs the main controller code under `src/`
- R5_0 runs a polling engine under `r5poll/`
- R5_1 runs an ECC offload engine under `eccengine/`
- All cores share on-chip peripherals (PCIe/NVMe host interface, flash controller, timers, interrupts) and common libraries in `include/`.

##### File Structure Analysis
- Top-level directories:
- `src/`        – A53 firmware source (FTL, hostif, coroutine scheduler, flash abstraction)
- `r5poll/`     – R5_0 polling application (flash interface, NFC, timers)
- `eccengine/`  – R5_1 ECC engine (BCH encode/decode)
- `include/`    – Shared headers (data structures, threading, config)
- Key modules under `src/`:
- `hostif/`    – PCIe and NVMe command handling
- `ftl/`       – Flash translation layer components
- `coro/`      – Lightweight coroutine scheduler, mutexes, queues
- `hdrhistogram/` – Latency tracking utility
- Interrupts, timers, worker threads, slab allocator, I/O iterators
- Build scripts & config:
- `create_projects.tcl` – Auto-generates cross-compile projects for each core
- Linker scripts (`*.ld`) in each source tree
- Shared include path (`include/`)

##### Insights from README
- Three separate linker/build targets map directly to three cores.
- A53 uses `src/`, R5_0 uses `r5poll/`, R5_1 uses `eccengine/`.
- All three include the headers under `include/`.

a. Main Components
- Processing Elements:
- Core-A53 (main FTL & host interface)
- Core-R5_0 (polling engine for flash / NFC)
- Core-R5_1 (ECC encode/decode engine)
- Shared Peripherals:
- PCIe Root Complex / NVMe host controller
- Flash channels & NFC controllers
- On-chip timers & interrupt controller
- Common Software Libraries:
- Coroutine scheduler, threading primitives
- Data structures (AVL, bitmap, ring queue)
- Flash abstraction layer, I/O iterator
b. Relationships & Interactions
- Core-A53 issues NVMe commands via PCIe host interface → interacts with `hostif/nvme.*`.
- FTL logic on A53 submits read/write to flash controller → may trigger interrupts.
- R5_0 polls flash controller status and handles raw page reads (`r5poll/fil/`).
- When R5_1 ECC engine is needed, A53 or R5_0 streams data via shared memory / IPC → R5_1 performs BCH encode/decode.
- Synchronization via interrupts, shared memory queues (ringq), IPI (inter-processor interrupt) lines.
c. Architectural Patterns
- Multi-core separation of concerns:
- Control plane on A53, data plane (polling) on R5_0, offload (ECC) on R5_1
- Producer-consumer queues between cores (implement via `ringq`, `ipi`)
- Lightweight cooperative multitasking on A53 (coroutines)
d. Relevant Technologies & Frameworks
- Bare-metal C code, custom coroutine library (`src/coro/`)
- Host interface modules (`pcie.c`, `nvme.c`)
- Flash translation (`ftl/`) and ECC (`bch*` in `eccengine/`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Processing Elements
    subgraph "Core A53"
        direction TB
        A53_main["main.c"]:::processor
        A53_ld["lscript.ld"]:::processor
        hostif_pcie["pcie.c"]:::processor
        hostif_nvme["nvme.c"]:::processor
        ftl["FTL Layer"]:::processor
        coro["Coroutine Scheduler"]:::processor
        intr_ipi["Intr & IPI"]:::processor
    end

    subgraph "Core R5_0"
        direction TB
        R5p_main["main.c"]:::processor
        R5p_ld["lscript.ld"]:::processor
        R5p_ipi["IPI Front-end"]:::processor
        R5p_fil["Flash Interface"]:::processor
        R5p_nfc["NFC Controller"]:::processor
    end

    subgraph "Core R5_1"
        direction TB
        R5e_main["main.c"]:::processor
        R5e_ld["lscript.ld"]:::processor
        R5e_ipi["IPI Front-end"]:::processor
        bch_engine["BCH Engine"]:::processor
    end

    %% Shared Hardware Peripherals
    PCIe["PCIe/NVMe Host If"]:::peripheral
    FlashCtrl["Flash Controller"]:::peripheral
    TimersIRQ["Timers & IRQ Ctrl"]:::peripheral

    %% Shared Software Libraries
    SharedSW["Shared SW Libs\n(data structures, coro API, IPC)"]:::library

    %% Data and Control Flows
    PCIe -->|"NVMe cmds"| hostif_pcie
    hostif_pcie -->|"handles cmd"| hostif_nvme
    hostif_nvme -->|"calls"| ftl
    ftl -->|"flash ops"| FlashCtrl
    R5p_fil -->|"raw reads"| FlashCtrl
    bch_engine -->|"ECC ops"| FlashCtrl

    corotrigger{Shared Memory\n& RingQ/IPI}
    corotrigger -->|"ringq / IPI"| R5p_ipi
    corotrigger -->|"ringq / IPI"| R5e_ipi
    intr_ipi --> corotrigger

    %% Shared Libraries Usage
    SharedSW --> A53_main
    SharedSW --> R5p_main
    SharedSW --> R5e_main

    %% Click Events
    click A53_main "https://github.com/jimx-/softssd/blob/master/src/main.c"
    click A53_ld "https://github.com/jimx-/softssd/blob/master/src/lscript.ld"
    click hostif_pcie "https://github.com/jimx-/softssd/blob/master/src/hostif/pcie.c"
    click hostif_nvme "https://github.com/jimx-/softssd/blob/master/src/hostif/nvme.c"
    click ftl "https://github.com/jimx-/softssd/blob/master/src/ftl/ftl.c"
    click coro "https://github.com/jimx-/softssd/tree/master/src/coro/"
    click R5p_main "https://github.com/jimx-/softssd/blob/master/r5poll/main.c"
    click R5p_ld "https://github.com/jimx-/softssd/blob/master/r5poll/lscript.ld"
    click R5p_fil "https://github.com/jimx-/softssd/blob/master/r5poll/fil/fil.c"
    click R5p_nfc "https://github.com/jimx-/softssd/blob/master/r5poll/fil/nfc.c"
    click R5e_main "https://github.com/jimx-/softssd/blob/master/eccengine/main.c"
    click R5e_ld "https://github.com/jimx-/softssd/blob/master/eccengine/lscript.ld"
    click bch_engine "https://github.com/jimx-/softssd/blob/master/eccengine/bch.c"
    click SharedSW "https://github.com/jimx-/softssd/tree/master/include/"

    %% Styles
    classDef processor fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef peripheral fill:#F9E79F,stroke:#B7950B,color:#6E2C00;
    classDef library fill:#ABEBC6,stroke:#229954,color:#145A32;
```
