# riscv-stc/riscv-isa-sim architecture

> Architecture diagram of the GitHub repository riscv-stc/riscv-isa-sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riscv-stc/riscv-isa-sim
- Repository: https://github.com/riscv-stc/riscv-isa-sim

## Overview

Spike is a functional RISC-V ISA simulator. The primary workflow is to invoke `spike` with a RISC-V program, configure simulated harts and memory, execute instructions, and observe results through logs or debugging. The graph also retains documented instruction-set coverage, disassembly, interactive debugging, and remote GDB support. Several implementation links are necessarily omitted or marked unverified: the excerpts show only parts of the CLI and runtime, so they do not establish all internal calls or program-loading paths.

Main entry points: [`spike_main/spike.cc`](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/spike_main/spike.cc) (Spike CLI), [`riscv/sim.h`](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/sim.h) (Simulation), [`riscv/execute.cc`](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/execute.cc) (Instruction execution), [`riscv/processor.cc`](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/processor.cc) (Hart processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation runtime"]
  node_spike["Spike CLI<br/>[spike.cc]"]
  node_sim["Simulation<br/>[sim.h]"]
  node_hart["Hart processor<br/>[processor.cc]"]
  node_mmu["Address translation<br/>[mmu.h]"]
  node_memory["Memory and devices<br/>[devices.h]"]
end

subgraph group_isa["ISA modeling"]
  node_decode["Instruction decoding<br/>[decode.h]"]
  node_execute["Instruction execution<br/>[execute.cc]"]
  node_semantics["Instruction semantics"]
  node_isa_parser["ISA configuration<br/>[isa_parser.cc]"]
  node_softfloat["Floating-point arithmetic<br/>[softfloat.h]"]
end

subgraph group_debug["Inspection and debug"]
  node_disasm["Disassembly<br/>[disasm.cc]"]
  node_debugger["Interactive debug<br/>[sim.h]"]
  node_debug_module["Debug module<br/>[debug_module.h]"]
  node_remote_bitbang["Remote bitbang<br/>[remote_bitbang.h]"]
end

subgraph group_host["Host interface"]
  node_loader["ELF loading<br/>[elfloader.cc]"]
  node_htif["Host target interface<br/>[htif.cc]"]
  node_syscalls["Guest syscalls<br/>[syscall.cc]"]
end

node_user(("Simulator user"))
node_gdb(("GDB and OpenOCD"))
node_program["RISC-V program"]

node_user -->|"invokes"| node_spike
node_program -->|"simulated by"| node_spike
node_spike -.->|"starts simulation"| node_sim
node_spike -.->|"configures memory"| node_mmu
node_sim -.->|"dispatches harts"| node_hart
node_hart -.->|"decodes instructions"| node_decode
node_hart -.->|"executes instructions"| node_execute
node_execute -.->|"uses semantics"| node_semantics
node_execute -.->|"accesses memory"| node_mmu
node_execute -.->|"uses arithmetic"| node_softfloat
node_spike -.->|"loads program"| node_loader
node_sim -.->|"communicates through"| node_htif
node_htif -.->|"handles guest calls"| node_syscalls
node_sim -.->|"models devices"| node_memory
node_isa_parser -.->|"configures ISA"| node_hart
node_user -->|"disassembles logs"| node_disasm
node_user -->|"enters debug mode"| node_debugger
node_gdb -->|"connects remotely"| node_remote_bitbang
node_remote_bitbang -.->|"accesses debug module"| node_debug_module
node_spike -.->|"configures debugging"| node_debug_module

click node_spike "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/spike_main/spike.cc"
click node_sim "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/sim.h"
click node_hart "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/processor.cc"
click node_mmu "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/mmu.h"
click node_memory "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/devices.h"
click node_loader "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/elfloader.cc"
click node_htif "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/htif.cc"
click node_syscalls "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/syscall.cc"
click node_decode "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/decode.h"
click node_execute "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/execute.cc"
click node_semantics "https://github.com/riscv-stc/riscv-isa-sim/tree/matrix/riscv/insns"
click node_isa_parser "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/disasm/isa_parser.cc"
click node_softfloat "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/softfloat/softfloat.h"
click node_disasm "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/disasm/disasm.cc"
click node_debugger "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/sim.h"
click node_debug_module "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/debug_module.h"
click node_remote_bitbang "https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/remote_bitbang.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_spike,node_sim,node_hart,node_mmu,node_memory,node_user toneBlue
class node_decode,node_execute,node_semantics,node_isa_parser,node_softfloat toneAmber
class node_disasm,node_debugger,node_debug_module,node_remote_bitbang toneMint
class node_loader,node_htif,node_syscalls toneRose
class node_gdb,node_program toneIndigo
```

## Components

### Simulation runtime

- [Spike CLI](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/spike_main/spike.cc): `spike_main/spike.cc`
- [Simulation](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/sim.h): `riscv/sim.h`
- [Hart processor](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/processor.cc): `riscv/processor.cc`
- [Address translation](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/mmu.h): `riscv/mmu.h`
- [Memory and devices](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/devices.h): `riscv/devices.h`

### ISA modeling

- [Instruction decoding](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/decode.h): `riscv/decode.h`
- [Instruction execution](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/execute.cc): `riscv/execute.cc`
- [Instruction semantics](https://github.com/riscv-stc/riscv-isa-sim/tree/matrix/riscv/insns): `riscv/insns`
- [ISA configuration](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/disasm/isa_parser.cc): `disasm/isa_parser.cc`
- [Floating-point arithmetic](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/softfloat/softfloat.h): `softfloat/softfloat.h`

### Inspection and debug

- [Disassembly](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/disasm/disasm.cc): `disasm/disasm.cc`
- [Interactive debug](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/sim.h): `riscv/sim.h`
- [Debug module](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/debug_module.h): `riscv/debug_module.h`
- [Remote bitbang](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/riscv/remote_bitbang.h): `riscv/remote_bitbang.h`

### Host interface

- [ELF loading](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/elfloader.cc): `fesvr/elfloader.cc`
- [Host target interface](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/htif.cc): `fesvr/htif.cc`
- [Guest syscalls](https://github.com/riscv-stc/riscv-isa-sim/blob/matrix/fesvr/syscall.cc): `fesvr/syscall.cc`

### Other components

- **Simulator user**
- **GDB and OpenOCD**
- **RISC-V program**

## Connections

- Simulator user → Spike CLI: invokes
- RISC-V program → Spike CLI: simulated by
- Spike CLI → Simulation: starts simulation (evidence: `spike_main/spike.cc`)
- Spike CLI → Address translation: configures memory (evidence: `spike_main/spike.cc`)
- Simulation → Hart processor: dispatches harts
- Hart processor → Instruction decoding: decodes instructions
- Hart processor → Instruction execution: executes instructions
- Instruction execution → Instruction semantics: uses semantics
- Instruction execution → Address translation: accesses memory
- Instruction execution → Floating-point arithmetic: uses arithmetic
- Spike CLI → ELF loading: loads program
- Simulation → Host target interface: communicates through
- Host target interface → Guest syscalls: handles guest calls
- Simulation → Memory and devices: models devices (evidence: `riscv/sim.h`)
- ISA configuration → Hart processor: configures ISA
- Simulator user → Disassembly: disassembles logs
- Simulator user → Interactive debug: enters debug mode
- GDB and OpenOCD → Remote bitbang: connects remotely
- Remote bitbang → Debug module: accesses debug module
- Spike CLI → Debug module: configures debugging
