# ngxx-fus/riscvtutorial architecture

> Architecture diagram of the GitHub repository ngxx-fus/riscvtutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ngxx-fus/riscvtutorial
- Repository: https://github.com/ngxx-fus/riscvtutorial

## Overview

This repository is a RISC-V tutorial built around Chipyard: it contains configurable SoC generators, FPGA platform support, simulation integrations, and bare-metal examples. A typical user journey is selecting a configuration, generating a SoC, then running or deploying it; the examples demonstrate UART/GPIO access and a RoCC accelerator. The README provides only the project title, and several subsystems are represented here by their tree paths rather than inspected source, so uncertain internal wiring is omitted.

Main entry points: [`generators/chipyard/src/main/scala/ChipTop.scala`](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/ChipTop.scala) (Chip top), [`generators/chipyard/src/main/scala/config`](https://github.com/ngxx-fus/riscvtutorial/tree/base/generators/chipyard/src/main/scala/config) (SoC configs), [`generators/chipyard/src/main/scala/Generator.scala`](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/Generator.scala) (Generator stage), [`fpga/sw/rocc/src/main.c`](https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/rocc/src/main.c) (RoCC example)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_soc["SoC generation"]
  node_generator["Generator stage<br/>[Generator.scala]"]
  node_configs["SoC configs"]
  node_subsystem["Subsystem<br/>[Subsystem.scala]"]
  node_digitaltop["Digital top<br/>[DigitalTop.scala]"]
  node_chiptop["Chip top<br/>[ChipTop.scala]"]
  node_clocking["Clocking config"]
end

subgraph group_cores["Cores and accelerators"]
  node_tileconfig["Tile config"]
  node_roccconfig["RoCC config"]
  node_spiketile["Spike tile<br/>[SpikeTile.scala]"]
  node_spikesim["Spike simulator<br/>[spiketile.cc]"]
end

subgraph group_platforms["Platforms and simulation"]
  node_fpga["FPGA platforms"]
  node_harness["Simulation harness<br/>[TestHarness.scala]"]
  node_firesim["FireSim bridges"]
end

subgraph group_software["Bare-metal software"]
  node_hello["GPIO example<br/>[main.c]"]
  node_roccapp["RoCC example<br/>[main.c]"]
  node_roccheader["RoCC instructions<br/>[rocc.h]"]
end

node_user(("SoC developer"))
node_uartgpio["UART and GPIO"]
node_accelerator["RoCC accelerator"]

node_user -->|"selects configuration"| node_generator
node_configs -->|"configures generation"| node_generator
node_generator -->|"generates design"| node_chiptop
node_subsystem -->|"composes subsystem"| node_digitaltop
node_digitaltop -->|"forms chip top"| node_chiptop
node_clocking -->|"sets clock parameters"| node_configs
node_tileconfig -->|"sets tile parameters"| node_configs
node_roccconfig -->|"assigns accelerators"| node_configs
node_spiketile -->|"exchanges simulation requests"| node_spikesim
node_chiptop -->|"instantiated by"| node_harness
node_chiptop -.->|"targets platform"| node_fpga
node_chiptop -.->|"uses simulation bridges"| node_firesim
node_hello -->|"accesses registers"| node_uartgpio
node_roccapp -->|"uses instruction macros"| node_roccheader
node_roccapp -->|"issues custom instruction"| node_accelerator

click node_generator "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/Generator.scala"
click node_configs "https://github.com/ngxx-fus/riscvtutorial/tree/base/generators/chipyard/src/main/scala/config"
click node_subsystem "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/Subsystem.scala"
click node_digitaltop "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/DigitalTop.scala"
click node_chiptop "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/ChipTop.scala"
click node_clocking "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/ClockingFragments.scala"
click node_tileconfig "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/TileFragments.scala"
click node_roccconfig "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/RoCCFragments.scala"
click node_spiketile "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/SpikeTile.scala"
click node_spikesim "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/resources/csrc/spiketile.cc"
click node_fpga "https://github.com/ngxx-fus/riscvtutorial/tree/base/fpga/src/main/scala"
click node_harness "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/harness/TestHarness.scala"
click node_firesim "https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/firechip/src/main/scala/BridgeBinders.scala"
click node_hello "https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/helloWorld/src/main.c"
click node_roccapp "https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/rocc/src/main.c"
click node_roccheader "https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/rocc/include/rocc.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generator,node_configs,node_subsystem,node_digitaltop,node_chiptop,node_clocking toneBlue
class node_tileconfig,node_roccconfig,node_spiketile,node_spikesim toneAmber
class node_fpga,node_harness,node_firesim toneMint
class node_hello,node_roccapp,node_roccheader toneRose
class node_user,node_uartgpio,node_accelerator toneIndigo
```

## Components

### SoC generation

- [Generator stage](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/Generator.scala): `generators/chipyard/src/main/scala/Generator.scala`
- [SoC configs](https://github.com/ngxx-fus/riscvtutorial/tree/base/generators/chipyard/src/main/scala/config): `generators/chipyard/src/main/scala/config`
- [Subsystem](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/Subsystem.scala): `generators/chipyard/src/main/scala/Subsystem.scala`
- [Digital top](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/DigitalTop.scala): `generators/chipyard/src/main/scala/DigitalTop.scala`
- [Chip top](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/ChipTop.scala): `generators/chipyard/src/main/scala/ChipTop.scala`
- [Clocking config](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/ClockingFragments.scala): `generators/chipyard/src/main/scala/config/fragments/ClockingFragments.scala`

### Cores and accelerators

- [Tile config](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/TileFragments.scala): `generators/chipyard/src/main/scala/config/fragments/TileFragments.scala`
- [RoCC config](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/config/fragments/RoCCFragments.scala): `generators/chipyard/src/main/scala/config/fragments/RoCCFragments.scala`
- [Spike tile](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/SpikeTile.scala): `generators/chipyard/src/main/scala/SpikeTile.scala`
- [Spike simulator](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/resources/csrc/spiketile.cc): `generators/chipyard/src/main/resources/csrc/spiketile.cc`

### Platforms and simulation

- [FPGA platforms](https://github.com/ngxx-fus/riscvtutorial/tree/base/fpga/src/main/scala): `fpga/src/main/scala`
- [Simulation harness](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/chipyard/src/main/scala/harness/TestHarness.scala): `generators/chipyard/src/main/scala/harness/TestHarness.scala`
- [FireSim bridges](https://github.com/ngxx-fus/riscvtutorial/blob/base/generators/firechip/src/main/scala/BridgeBinders.scala): `generators/firechip/src/main/scala/BridgeBinders.scala`

### Bare-metal software

- [GPIO example](https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/helloWorld/src/main.c): `fpga/sw/helloWorld/src/main.c`
- [RoCC example](https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/rocc/src/main.c): `fpga/sw/rocc/src/main.c`
- [RoCC instructions](https://github.com/ngxx-fus/riscvtutorial/blob/base/fpga/sw/rocc/include/rocc.h): `fpga/sw/rocc/include/rocc.h`

### Other components

- **SoC developer**
- **UART and GPIO**
- **RoCC accelerator**

## Connections

- SoC developer → Generator stage: selects configuration
- SoC configs → Generator stage: configures generation
- Generator stage → Chip top: generates design
- Subsystem → Digital top: composes subsystem
- Digital top → Chip top: forms chip top
- Clocking config → SoC configs: sets clock parameters
- Tile config → SoC configs: sets tile parameters
- RoCC config → SoC configs: assigns accelerators
- Spike tile → Spike simulator: exchanges simulation requests
- Chip top → Simulation harness: instantiated by
- Chip top → FPGA platforms: targets platform
- Chip top → FireSim bridges: uses simulation bridges
- GPIO example → UART and GPIO: accesses registers
- RoCC example → RoCC instructions: uses instruction macros
- RoCC example → RoCC accelerator: issues custom instruction