# zero-day-labs/riscv-aia architecture

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

- Interactive diagram: https://gitdiagram.com/zero-day-labs/riscv-aia
- Repository: https://github.com/zero-day-labs/riscv-aia

## Overview

##### Project Type and Purpose
- The project is a hardware RTL implementation of the RISC-V AIA specification. Its purpose is to support interrupt management through different microarchitectural configurations – namely APLIC IP and IMSIC IP – that can operate in direct, distributed, or embedded modes. This makes it particularly interesting for SoC designs and mixed-criticality systems.

##### File Structure
- Notice the top-level directories:
- The “rtl/” folder is the heart of the project with SystemVerilog files. Here you find separate files for APLIC (e.g., aplic_domain_top.sv, aplic_top.sv) and IMSIC (e.g., imsic_top.sv) along with registers maps and protocol packages.
- The “rtl/package/” subfolder holds configuration packages (like aia_pkg.sv, imsic_pkg.sv) that dictate the IP’s parameterization.
- The “test/” folder includes cocotb-based tests that simulate both the APLIC and IMSIC components, showing how they integrate.
- Additional directories (.github, vendor) support metadata, contributions, and vendor-specific RTL modules.

- Main Components to Represent:
a. APLIC IP Block(s):
- Core APLIC modules (e.g., aplic_domain_top, aplic_regmap) which manage different interrupt domains and their parameters.
- That the APLIC can operate in different modes (direct vs. MSI mode), based on parameters configured in the package files.
b. IMSIC IP Block(s):
- IMSIC modules (e.g., imsic_top) and consider the different microarchitectures (Vanilla, IMSIC Island, Embedded). The interaction between IMSIC and APLIC (for managing harts and interrupt distribution) should be clear.
c. Configuration and Parameterization Packages:
d. Verification Environment:
e. Documentation and External Interfaces:
- A note about external interfaces or integration points as described in the documentation and README. This might involve the bus interfaces where the IP is integrated into a larger SoC.

- Relationships and Interactions:
- How the configuration packages feed into and parameterize the RTL components.
- Feedback loops or synchronization mechanisms, which could be represented by utilities (such as synchronizer.sv in rtl/util).

##### Architectural Patterns and Design Principles
- Separation of concerns: distinct blocks for APLIC and IMSIC.
- Configurability: use of parameter and package files to allow different microarchitectures.
- Hierarchical organization: for example, separate submodules for domain management within APLIC and multiple harts management in IMSIC.

##### Putting It All Together
- Core IP Blocks: APLIC (with submodules such as domain control, regmap, etc.) and IMSIC (with its different microarchitecture variants).
- Configuration Layer: Show how the SystemVerilog packages (aia_pkg.sv, imsic_pkg.sv, etc.) feed into these blocks.
- Verification: Illustrate the connection to the cocotb test framework and the simulation environment.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core IP Blocks
    subgraph "Core IP Blocks"
        %% APLIC IP Block
        APLIC["APLIC IP Block"]:::ip
        subgraph "APLIC Module Components"
            APLIC_T["APLIC Top"]:::ip
            APLIC_D["APLIC Domain Top"]:::ip
            APLIC_R["APLIC Regmap"]:::ip
            APLIC_CR["APLIC Domain RegCtl"]:::ip
            APLIC_CN["APLIC Domain Notifier"]:::ip
        end
        %% IMSIC IP Block
        IMSIC["IMSIC IP Block"]:::ip
        subgraph "IMSIC Module Components"
            IMSIC_T["IMSIC Top"]:::ip
            IMSIC_R["IMSIC Regmap"]:::ip
        end
    end

    %% Configuration Packages
    subgraph "Configuration Layer"
        CONFIG["Configuration Packages"]:::config
        subgraph "Configuration Files"
            AIA_PKG["aia_pkg.sv"]:::config
            APLIC_PKG["aplic_pkg.sv"]:::config
            IMSIC_PKG["imsic_pkg.sv"]:::config
            AIA_DIRECT["aia_define_direct.svh"]:::config
            AIA_DIST["aia_define_distributed.svh"]:::config
            AIA_EMBED["aia_define_embedded.svh"]:::config
            AIA_MSI["aia_define_msi.svh"]:::config
            APLIC_DOMAIN_PKG["aplic_domain_pkg.sv"]:::config
            IMSIC_PROTO["imsic_protocol_pkg.sv"]:::config
        end
    end

    %% Verification Environment
    subgraph "Verification Environment"
        VERIF["Verification Environment"]:::test
        subgraph "APLIC Tests"
            APLIC_AXI_TEST["aplic_axi.py"]:::test
            APLIC_CTRL_TEST["aplic_domain_regctl_tb.py"]:::test
            APLIC_WRAP["wrap.sv (APLIC)"]:::test
        end
        subgraph "IMSIC Tests"
            IMSIC_TOP_TEST["imsic_top_tb.py"]:::test
            IMSIC_WRAP["wrap.sv (IMSIC)"]:::test
        end
        subgraph "Integration Tests"
            INTEG_AIA_REGMAP["aia_regmap.py"]:::test
            INTEG_AIA_TB["aia_tb.py"]:::test
            INTEG_APLIC_AXI["aplic_axi.py (Integration)"]:::test
            INTEG_GEN_AIA["generate_aia_define.py"]:::test
            INTEG_IMSIC_CSR["imsic_csr_channel.py"]:::test
            INTEG_IEAIA_WRAP["ieaia_wrap.sv"]:::test
        end
    end

    %% Documentation and External Interfaces
    subgraph "Documentation"
        DOC_APLIC["APLIC Documentation"]:::doc
        DOC_IMSIC["IMSIC Documentation"]:::doc
    end

    %% Utility Functions
    subgraph "Utility Functions"
        UTIL_SYNCH["synchronizer.sv"]:::utility
        UTIL_AXI["axi4_lite_write_master.sv"]:::utility
    end

    %% Relationships
    %% Configuration packages feed into IP blocks
    CONFIG -->|"configures"| APLIC
    CONFIG -->|"configures"| IMSIC
    AIA_PKG --> CONFIG
    APLIC_PKG --> CONFIG
    IMSIC_PKG --> CONFIG
    AIA_DIRECT --> CONFIG
    AIA_DIST --> CONFIG
    AIA_EMBED --> CONFIG
    AIA_MSI --> CONFIG
    APLIC_DOMAIN_PKG --> CONFIG
    IMSIC_PROTO --> CONFIG

    %% Interaction between APLIC and IMSIC IP Blocks
    APLIC -->|"embedded_instantiation"| IMSIC
    IMSIC -->|"interrupt_distribution"| APLIC

    %% Utility functions support IP blocks
    UTIL_SYNCH --> APLIC
    UTIL_SYNCH --> IMSIC
    UTIL_AXI --> APLIC
    UTIL_AXI --> IMSIC

    %% Verification tests connect to IP blocks
    APLIC -->|"tested_by"| VERIF
    IMSIC -->|"tested_by"| VERIF

    %% Documentation relates to IP blocks
    DOC_APLIC --- APLIC
    DOC_IMSIC --- IMSIC

    %% Click Events for APLIC IP Block Files
    click APLIC_T "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/aplic_top.sv"
    click APLIC_D "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/aplic_domain_top.sv"
    click APLIC_R "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/aplic_regmap.sv"
    click APLIC_CR "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/aplic_domain_regctl.sv"
    click APLIC_CN "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/aplic_domain_notifier.sv"

    %% Click Events for IMSIC IP Block Files
    click IMSIC_T "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/imsic_top.sv"
    click IMSIC_R "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/imsic_regmap.sv"

    %% Click Events for Configuration and Parameterization Packages
    click AIA_PKG "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aia_pkg.sv"
    click APLIC_PKG "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aplic_pkg.sv"
    click IMSIC_PKG "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/imsic_pkg.sv"
    click AIA_DIRECT "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aia_define_direct.svh"
    click AIA_DIST "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aia_define_distributed.svh"
    click AIA_EMBED "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aia_define_embedded.svh"
    click AIA_MSI "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aia_define_msi.svh"
    click APLIC_DOMAIN_PKG "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/aplic_domain_pkg.sv"
    click IMSIC_PROTO "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/package/imsic_protocol_pkg.sv"

    %% Click Events for Verification Environment Files
    click APLIC_AXI_TEST "https://github.com/zero-day-labs/riscv-aia/blob/master/test/aplic/aplic_axi.py"
    click APLIC_CTRL_TEST "https://github.com/zero-day-labs/riscv-aia/blob/master/test/aplic/aplic_domain_regctl_tb.py"
    click APLIC_WRAP "https://github.com/zero-day-labs/riscv-aia/blob/master/test/aplic/wrap.sv"
    click IMSIC_TOP_TEST "https://github.com/zero-day-labs/riscv-aia/blob/master/test/imsic/imsic_top_tb.py"
    click IMSIC_WRAP "https://github.com/zero-day-labs/riscv-aia/blob/master/test/imsic/wrap.sv"
    click INTEG_AIA_REGMAP "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/aia_regmap.py"
    click INTEG_AIA_TB "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/aia_tb.py"
    click INTEG_APLIC_AXI "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/aplic_axi.py"
    click INTEG_GEN_AIA "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/generate_aia_define.py"
    click INTEG_IMSIC_CSR "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/imsic_csr_channel.py"
    click INTEG_IEAIA_WRAP "https://github.com/zero-day-labs/riscv-aia/blob/master/test/integration/ieaia_wrap.sv"

    %% Click Events for Documentation
    click DOC_APLIC "https://github.com/zero-day-labs/riscv-aia/tree/master/doc/aplic"
    click DOC_IMSIC "https://github.com/zero-day-labs/riscv-aia/tree/master/doc/imsic"

    %% Click Events for Utility Functions
    click UTIL_SYNCH "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/util/synchronizer.sv"
    click UTIL_AXI "https://github.com/zero-day-labs/riscv-aia/blob/master/rtl/util/axi4_lite_write_master.sv"

    %% Styles
    classDef ip fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef config fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px;
    classDef test fill:#C8E6C9,stroke:#43A047,stroke-width:2px;
    classDef doc fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef utility fill:#E0E0E0,stroke:#757575,stroke-width:2px;
```
