# sfu-arch/muir-lib architecture

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

- Interactive diagram: https://gitdiagram.com/sfu-arch/muir-lib
- Repository: https://github.com/sfu-arch/muir-lib

## Overview

muIR is a Chisel library for generating configurable parallel dataflow accelerators. The principal workflow is to use a hardware designer’s generated dataflow design, composed from instruction-like nodes and control/loop logic, then connect its memory requests through memory controllers and interfaces. The README also documents configurable computation, arbitrary control paths, memory structures, and junctions. Several subsystem links are supported only by README descriptions; the graph omits unverified internal wiring because much of the source was not sampled.

Main entry points: [`src/main/scala/memory/UnifiedController.scala`](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/UnifiedController.scala) (Unified controller), [`src/main/scala/generator`](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/generator) (Generated designs), [`src/main/scala/node/ComputeNode.scala`](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/node/ComputeNode.scala) (Compute nodes), [`src/main/scala/interfaces/HandShaking.scala`](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/interfaces/HandShaking.scala) (Handshake protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accelerator["Accelerator shell"]
  node_core["Accelerator core<br/>[Core.scala]"]
  node_accel_io["Accelerator I/O<br/>[AccelIO.scala]"]
end

subgraph group_dataflow["Dataflow execution"]
  node_compute["Compute nodes<br/>[ComputeNode.scala]"]
  node_control["Control nodes<br/>[BasicBlock.scala]"]
  node_loops["Loop blocks<br/>[LoopBlock.scala]"]
  node_floating["Floating-point units"]
end

subgraph group_memory["Memory system"]
  node_unified["Unified controller"]
  node_rw_arbiter["Read/write arbiter"]
  node_read_ctrl["Read controllers"]
  node_write_ctrl["Write controllers"]
  node_cache[("AXI cache<br/>[AXICache.scala]")]
  node_scratchpad[("Scratchpad memory")]
end

subgraph group_connectivity["Interfaces and concurrency"]
  node_handshake["Handshake protocol<br/>[HandShaking.scala]"]
  node_junctions["Stream junctions"]
  node_concurrency["Task concurrency"]
  node_arbiter["Arbiter tree<br/>[ArbiterTree.scala]"]
  node_memory_interface["Memory interface"]
end

subgraph group_designs["Generated designs"]
  node_dataflow_examples["Dataflow examples"]
  node_generator["Generated designs"]
end

node_designer(("Hardware designer"))

node_designer -->|"specifies design"| node_generator
node_generator -->|"wraps design"| node_core
node_generator -->|"instantiates"| node_compute
node_generator -->|"connects loop logic"| node_loops
node_compute -->|"uses protocol"| node_handshake
node_compute -.->|"uses arithmetic"| node_floating
node_control -.->|"uses protocol"| node_handshake
node_loops -->|"exchanges signals"| node_handshake
node_core -.->|"exposes interface"| node_accel_io
node_unified -->|"routes requests"| node_rw_arbiter
node_rw_arbiter -->|"forwards requests"| node_memory_interface
node_read_ctrl -->|"arbitrates inputs"| node_arbiter
node_write_ctrl -->|"arbitrates inputs"| node_arbiter
node_unified -->|"dispatches reads"| node_read_ctrl
node_unified -->|"dispatches writes"| node_write_ctrl
node_unified -.->|"may use cache"| node_cache
node_unified -.->|"may use scratchpad"| node_scratchpad
node_dataflow_examples -.->|"demonstrates nodes"| node_compute
node_concurrency -.->|"supports task parallelism"| node_core
node_junctions -.->|"connects streams"| node_handshake

click node_core "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/accel/Core.scala"
click node_accel_io "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/accel/AccelIO.scala"
click node_compute "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/node/ComputeNode.scala"
click node_control "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/control/BasicBlock.scala"
click node_loops "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/loop/LoopBlock.scala"
click node_floating "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/FPU/FPComputeNode.scala"
click node_handshake "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/interfaces/HandShaking.scala"
click node_junctions "https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/junctions"
click node_concurrency "https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/concurrent"
click node_arbiter "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/arbiters/ArbiterTree.scala"
click node_unified "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/UnifiedController.scala"
click node_rw_arbiter "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ReadWriteArbiter.scala"
click node_read_ctrl "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ReadTypMemoryController.scala"
click node_write_ctrl "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/WriteTypMemoryController.scala"
click node_cache "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/cache/AXICache.scala"
click node_scratchpad "https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ScratchPadMemory.scala"
click node_memory_interface "https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/interfaces"
click node_dataflow_examples "https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/dataflow"
click node_generator "https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/generator"

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_core,node_accel_io toneBlue
class node_compute,node_control,node_loops,node_floating toneAmber
class node_unified,node_rw_arbiter,node_read_ctrl,node_write_ctrl,node_cache,node_scratchpad toneMint
class node_handshake,node_junctions,node_concurrency,node_arbiter,node_memory_interface toneRose
class node_dataflow_examples,node_generator,node_designer toneIndigo
```

## Components

### Accelerator shell

- [Accelerator core](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/accel/Core.scala): `src/main/scala/accel/Core.scala`
- [Accelerator I/O](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/accel/AccelIO.scala): `src/main/scala/accel/AccelIO.scala`

### Dataflow execution

- [Compute nodes](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/node/ComputeNode.scala): `src/main/scala/node/ComputeNode.scala`
- [Control nodes](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/control/BasicBlock.scala): `src/main/scala/control/BasicBlock.scala`
- [Loop blocks](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/loop/LoopBlock.scala): `src/main/scala/loop/LoopBlock.scala`
- [Floating-point units](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/FPU/FPComputeNode.scala): `src/main/scala/FPU/FPComputeNode.scala`

### Memory system

- [Unified controller](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/UnifiedController.scala): `src/main/scala/memory/UnifiedController.scala`
- [Read/write arbiter](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ReadWriteArbiter.scala): `src/main/scala/memory/ReadWriteArbiter.scala`
- [Read controllers](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ReadTypMemoryController.scala): `src/main/scala/memory/ReadTypMemoryController.scala`
- [Write controllers](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/WriteTypMemoryController.scala): `src/main/scala/memory/WriteTypMemoryController.scala`
- [AXI cache](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/cache/AXICache.scala): `src/main/scala/memory/cache/AXICache.scala`
- [Scratchpad memory](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/memory/ScratchPadMemory.scala): `src/main/scala/memory/ScratchPadMemory.scala`

### Interfaces and concurrency

- [Handshake protocol](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/interfaces/HandShaking.scala): `src/main/scala/interfaces/HandShaking.scala`
- [Stream junctions](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/junctions): `src/main/scala/junctions`
- [Task concurrency](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/concurrent): `src/main/scala/concurrent`
- [Arbiter tree](https://github.com/sfu-arch/muir-lib/blob/master/src/main/scala/arbiters/ArbiterTree.scala): `src/main/scala/arbiters/ArbiterTree.scala`
- [Memory interface](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/interfaces): `src/main/scala/interfaces`

### Generated designs

- [Dataflow examples](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/dataflow): `src/main/scala/dataflow`
- [Generated designs](https://github.com/sfu-arch/muir-lib/tree/master/src/main/scala/generator): `src/main/scala/generator`

### Other components

- **Hardware designer**

## Connections

- Hardware designer → Generated designs: specifies design
- Generated designs → Accelerator core: wraps design
- Generated designs → Compute nodes: instantiates (evidence: `src/main/scala/generator/conv2dSerial.scala`)
- Generated designs → Loop blocks: connects loop logic (evidence: `src/main/scala/generator/conv2dSerial.scala`)
- Compute nodes → Handshake protocol: uses protocol
- Compute nodes → Floating-point units: uses arithmetic
- Control nodes → Handshake protocol: uses protocol
- Loop blocks → Handshake protocol: exchanges signals (evidence: `src/main/scala/loop/LoopBlock.scala`)
- Accelerator core → Accelerator I/O: exposes interface
- Unified controller → Read/write arbiter: routes requests (evidence: `src/main/scala/memory/UnifiedController.scala`)
- Read/write arbiter → Memory interface: forwards requests (evidence: `src/main/scala/memory/ReadWriteArbiter.scala`)
- Read controllers → Arbiter tree: arbitrates inputs (evidence: `src/main/scala/memory/ReadTypMemoryController.scala`)
- Write controllers → Arbiter tree: arbitrates inputs (evidence: `src/main/scala/memory/WriteTypMemoryController.scala`)
- Unified controller → Read controllers: dispatches reads (evidence: `src/main/scala/memory/UnifiedController.scala`)
- Unified controller → Write controllers: dispatches writes (evidence: `src/main/scala/memory/UnifiedController.scala`)
- Unified controller → AXI cache: may use cache
- Unified controller → Scratchpad memory: may use scratchpad
- Dataflow examples → Compute nodes: demonstrates nodes
- Task concurrency → Accelerator core: supports task parallelism
- Stream junctions → Handshake protocol: connects streams
