# lowrisc/sonata-system architecture

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

- Interactive diagram: https://gitdiagram.com/lowrisc/sonata-system
- Repository: https://github.com/lowrisc/sonata-system

## Overview

##### Main Components
- FPGA Hardware Platform: At the hardware level, you have the FPGA design (the RTL folder). This includes:
– The CHERIoT Ibex core and its related “sonata.core” and “sonata_system.core” files.
– Peripheral modules implemented as IP blocks in the rtl/ip folder (for example, GPIO, I2C, SPI, USB, PWM, revocation control, pinmux, etc.).
– Bus interconnections (see rtl/bus for bus packages, crossbars, and related service protocols).
– Additional system-level infrastructure (top-level files in rtl/system, pinmux, clock generation, reset logic, JTAG, etc.).
- Simulation and Verification Environment:
– Verification environments using Verilator and DPI tests found in dv/verilator, dv/dpi, and related simulation test files.
– Flow scripts (in the flow directory) that prepare the FPGA design for synthesis and place-and-route.
- Software and Embedded Applications:
– The sw directory contains the firmware, tests, bootloader, and drivers written for the microcontroller. It includes parts specific to CHERI in “sw/cheri,” legacy support, and example/demo applications.
– Build system integrations (CMake files, linker scripts, and the use of Nix/flake configurations).
- Documentation and Utility Tools:
– mdBook documentation (doc folder and util/mdbook) along with scripts that automate tasks such as generating top-level configurations, peripheral registers, or even the UF2 boot images.

##### Relationships and Interactions
- Around that, add blocks for each peripheral IP (e.g., GPIO, SPI, I2C, USB, UART, PWM, HyperRAM, etc.) showing connections (likely via a common bus or crossbar – see rtl/bus and autogen rv_plic components).
- Bus interconnect (an “Xbar” for fetching instructions/data) and show how the processor communicates with the peripherals.
- A block for “System IP & Control” that groups elements like system information, pinmux, revocation control, and other system-level controllers.
- On the verification side, illustrate a simulation environment block that links back to the hardware system. This block represents the Verilator simulation (dv/verilator) and DPI test components.
- For the software side, add a separate layer that represents the firmware/RTOS/bootloader stack along with drivers. Show its connection to the hardware (i.e., how the software interacts via registers or API calls with peripheral logic).

##### Architectural Patterns and Design Principles
- Documentation and utility integration: while not part of the runtime system, these components (mdBook docs, scripts in util/) should be annotated as supporting tools that aid in design generation, configuration, and deployment.

##### Relevant Technologies and Frameworks
- FPGA design: Verilog/SystemVerilog (RTL directory), Vivado tool flows (flow folder script hooks), and simulation tools (Verilator, DPI).
- Build and dependency management: Nix/flake configurations, CMake scripts found in sw/cheri and other directories.
- Software development: Integration with CHERIoT RTOS, provided bootloaders (with drag-and-drop programming via UF2 files), and examples for real-world testing.
- Documentation: mdBook for documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware/FPGA Layer
    subgraph "Hardware/FPGA Layer"
        A1["CHERIoT Ibex Core"]:::hardware
        A2["sonata.core"]:::hardware
        A3["sonata_system.core"]:::hardware
        A4["cheriot_debug_module.core"]:::hardware
        
        B1["Main Bus (Xbar)"]:::bus
        
        P1["GPIO IP"]:::peripheral
        P2["SPI IP"]:::peripheral
        P3["HyperRAM IP"]:::peripheral
        P4["Revocation Control IP"]:::peripheral
        P5["RGB LED Controller"]:::peripheral
        P6["System Info IP"]:::peripheral
        
        INF["System Infrastructure (Pinmux, Clock, Reset, JTAG)"]:::hardware

        %% Connections within Hardware Layer
        A1 --> B1
        B1 --> P1
        B1 --> P2
        B1 --> P3
        B1 --> P4
        B1 --> P5
        B1 --> P6
        A1 --> INF
    end

    %% Simulation & Verification Layer
    subgraph "Simulation & Verification"
        SIM["Verilator Simulation Environment"]:::simulation
        DPI["DPI Test Environment"]:::simulation
    end

    %% Software & Embedded Applications Layer
    subgraph "Software & Embedded Applications"
        SW["Firmware, Bootloader & Drivers"]:::software
    end

    %% Documentation & Utility Tools Layer
    subgraph "Documentation & Utility Tools"
        DOC["mdBook Documentation"]:::doc
        UTIL["Utility Scripts"]:::doc
    end

    %% Inter-layer Connections
    A1 -->|"interfaces"| SIM
    A1 -->|"interfaces"| DPI
    SW -->|"accesses"| A1
    SW -->|"builds with"| DOC
    DOC --- UTIL

    %% Click Events for Hardware Core Components
    click A2 "https://github.com/lowrisc/sonata-system/blob/main//sonata.core"
    click A3 "https://github.com/lowrisc/sonata-system/blob/main//sonata_system.core"
    click A4 "https://github.com/lowrisc/sonata-system/blob/main//cheriot_debug_module.core"
    
    %% Click Events for Peripheral IP Blocks
    click P1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/gpio/gpio.core"
    click P1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/gpio/rtl/gpio.sv"
    
    click P2 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/spi/spi.core"
    click P2 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/spi/rtl/spi.sv"
    
    click P3 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/hyperram/hyperram.core"
    click P3 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/hyperram/rtl/hyperram.sv"
    
    click P4 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/rev_ctl/rev_ctl.core"
    click P4 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/rev_ctl/rtl/rev_ctl.sv"
    
    click P5 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/rgbled_ctrl/rgbled_ctrl.core"
    click P5 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/rgbled_ctrl/rtl/rgbled_ctrl.sv"
    
    click P6 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/system_info/system_info.core"
    click P6 "https://github.com/lowrisc/sonata-system/blob/main//rtl/ip/system_info/rtl/system_info_reg_top.sv"
    
    %% Click Events for Bus Interconnections
    click B1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/bus/xbar_ifetch.core"
    click B1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/bus/xbar_ifetch.sv"
    click B1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/bus/xbar_main.core"
    click B1 "https://github.com/lowrisc/sonata-system/blob/main//rtl/bus/xbar_main.sv"
    
    %% Click Events for System Infrastructure
    click INF "https://github.com/lowrisc/sonata-system/blob/main//rtl/system/pinmux.sv"
    click INF "https://github.com/lowrisc/sonata-system/blob/main//rtl/system/sonata_system.sv"
    click INF "https://github.com/lowrisc/sonata-system/blob/main//rtl/system/clkgen_sonata.sv"
    click INF "https://github.com/lowrisc/sonata-system/blob/main//rtl/fpga/rst_ctrl.sv"

    %% Click Events for Simulation Environment
    click SIM "https://github.com/lowrisc/sonata-system/blob/main//dv/verilator/sonata_system.cc"
    click SIM "https://github.com/lowrisc/sonata-system/blob/main//dv/verilator/top_verilator.sv"
    click DPI "https://github.com/lowrisc/sonata-system/tree/main//dv/dpi"
    
    %% Click Events for Software Components
    click SW "https://github.com/lowrisc/sonata-system/tree/main//sw/cheri"
    click SW "https://github.com/lowrisc/sonata-system/tree/main//sw/legacy"
    click SW "https://github.com/lowrisc/sonata-system/blob/main//sw/cheri/link.ld"
    
    %% Click Events for Documentation & Utility Tools
    click DOC "https://github.com/lowrisc/sonata-system/tree/main//doc"
    click DOC "https://github.com/lowrisc/sonata-system/tree/main//util/mdbook"
    click UTIL "https://github.com/lowrisc/sonata-system/blob/main//util/reg_gen.sh"
    click UTIL "https://github.com/lowrisc/sonata-system/blob/main//util/top_gen.py"

    %% Styles
    classDef hardware fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef bus fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef peripheral fill:#D3F9D8,stroke:#333,stroke-width:2px;
    classDef simulation fill:#F9D5E5,stroke:#333,stroke-width:2px;
    classDef software fill:#C2E9FB,stroke:#333,stroke-width:2px;
    classDef doc fill:#D3CCE3,stroke:#333,stroke-width:2px;
```
