# guztech/misato architecture

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

- Interactive diagram: https://gitdiagram.com/guztech/misato
- Repository: https://github.com/guztech/misato

## Overview

##### Project type and purpose
- This is a hardware‐design project: a single‐cycle RISC-V RV32I CPU core (“Misato”), written in Amaranth HDL (Python) and formally verified with SymbiYosys.
- It comes with a SoC wrapper for FPGA (ULX3S), separate instruction/data memories, and (in a branch) a Wishbone Classic bus interconnect to peripherals (GPIO).

##### File structure
Top‐level source files (Amaranth modules):
– cpu.py           : top‐level CPU core
– decoder.py       : instruction decode logic
– isa.py           : instruction definitions, encodings
– alu.py, adder.py : arithmetic/logic units
– forwarding.py    : pipeline‐hazard forwarding logic
– branch.py        : branch target generation
– ram.py, rom.py   : single‐cycle instruction/data memories
– interconnect.py  : Wishbone Classic bus master interface
– gpio.py          : simple memory‐mapped peripheral
– soc.py           : system‐on‐chip wrapper (connects core, memories, bus, GPIO)
– ulx3s.py         : FPGA‐specific pinout constraints & build script
– misatogen.py     : automatic generation of core instances/parameters
Verification & build:
– *.sby            : SymbiYosys formal verification scripts (cpu.sby, decoder.sby)
– *.gtkw           : GTKWave waveform setups
– .github/workflows/openlane.yml : ASIC flow via OpenLANE (Sky130 & 65 nm PDKs)
Tests & docs:
– programs/        : small assembly tests (branch.s, count.s, etc.)
– riscv-filter.py  : post‐processing of simulation traces
– README.md, PDFs for RISC-V spec & Wishbone spec

##### README for additional insights
- All RV32I instructions except FENCE, ECALL, EBREAK are implemented.
- Formal verification covers functional correctness of each instruction.
- Current design uses separate instruction/data memories; a Wishbone interconnect is under development.
- Target flows: formal (SymbiYosys + GTKWave), FPGA (ULX3S), ASIC (OpenLANE).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "FPGA Top Level"
        ULX["ULX3S FPGA"]:::fpga
        subgraph "SoC Wrapper"
            SOC["SoC (soc.py)"]:::soc
            subgraph "CPU Core"
                IF["Instruction Fetch (rom.py)"]:::core
                DEC["Decoder (decoder.py)"]:::core
                ISA["ISA Definitions (isa.py)"]:::core
                ALU["ALU (alu.py)"]:::core
                ADD["Adder (adder.py)"]:::core
                BR["Branch Logic (branch.py)"]:::core
                RF["RegFile & Hazard (forwarding.py)"]:::core
                MEMStage["MEM Stage"]:::core
            end
            subgraph "On-Chip Memories"
                IMEM["Instruction Memory (ROM)"]:::mem
                DMEM["Data Memory (RAM)"]:::mem
            end
            BUS["Wishbone Bus Interconnect (interconnect.py)"]:::bus
            GPIO["GPIO Peripheral (gpio.py)"]:::peri
        end
    end

    subgraph "Formal Verification Harness"
        FVER["SymbiYosys Scripts"]:::harness
        GTK["GTKWave Setups"]:::harness
    end

    %% Data Flow
    IMEM -->|fetch| IF
    IF -->|instructions| DEC
    DEC -->|decode| ISA
    DEC -->|controls| ALU
    DEC -->|controls| ADD
    DEC -->|controls| BR
    DEC -->|controls| RF
    RF -- feedback --> DEC
    ALU -->|result| MEMStage
    ADD -->|result| MEMStage
    BR -->|target| MEMStage
    MEMStage -->|load/store| DMEM
    MEMStage -->|bus master| BUS
    BUS -->|slave| DMEM
    BUS -->|slave| GPIO

    %% Formal Harness Connections
    FVER -->|stimulus| IF
    FVER -->|properties| DEC
    GTK -.->|waveforms| FVER

    %% Hierarchical connections
    ULX --> SOC
    SOC --> CPU
    SOC --> IMEM
    SOC --> DMEM
    SOC --> BUS
    SOC --> GPIO

    %% Click events
    click CPU "https://github.com/guztech/misato/blob/main/cpu.py"
    click IF "https://github.com/guztech/misato/blob/main/rom.py"
    click DEC "https://github.com/guztech/misato/blob/main/decoder.py"
    click ISA "https://github.com/guztech/misato/blob/main/isa.py"
    click ALU "https://github.com/guztech/misato/blob/main/alu.py"
    click ADD "https://github.com/guztech/misato/blob/main/adder.py"
    click BR "https://github.com/guztech/misato/blob/main/branch.py"
    click RF "https://github.com/guztech/misato/blob/main/forwarding.py"
    click IMEM "https://github.com/guztech/misato/blob/main/rom.py"
    click DMEM "https://github.com/guztech/misato/blob/main/ram.py"
    click BUS "https://github.com/guztech/misato/blob/main/interconnect.py"
    click GPIO "https://github.com/guztech/misato/blob/main/gpio.py"
    click SOC "https://github.com/guztech/misato/blob/main/soc.py"
    click ULX "https://github.com/guztech/misato/blob/main/ulx3s.py"
    click FVER "https://github.com/guztech/misato/blob/main/cpu.sby"
    click FVER "https://github.com/guztech/misato/blob/main/decoder.sby"
    click GTK "https://github.com/guztech/misato/blob/main/cpu.gtkw"
    click GTK "https://github.com/guztech/misato/blob/main/my.gtkw"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#3182BD,color:#000;
    classDef mem fill:#FFD7A6,stroke:#DD6B20,color:#000;
    classDef bus fill:#C6F6D5,stroke:#38A169,color:#000;
    classDef peri fill:#FBD5E1,stroke:#D53F8C,color:#000;
    classDef soc fill:#E2E8F0,stroke:#4A5568,color:#000;
    classDef fpga fill:#EDE9FE,stroke:#6B46C1,color:#000;
    classDef harness fill:#F0FFF4,stroke:#2F855A,color:#000;
```
