# shouryadip-c/maze-runner-soc architecture

> Architecture diagram of the GitHub repository shouryadip-c/maze-runner-soc, 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/shouryadip-c/maze-runner-soc
- Repository: https://github.com/shouryadip-c/maze-runner-soc

## Overview

Maze Runner SoC combines ultrasonic sensing and a maze-exploration FSM with a picorv32 CPU, memory-mapped peripherals, and bare-metal firmware that reports state over UART and handles goal interrupts. The graph follows the documented top-level architecture and sampled firmware behavior; unsampled RTL internals are represented only where the README documents their connections.

Main entry points: [`firmware/main.c`](https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/main.c) (Firmware main), [`rtl/bus/axi4lite_interconnect_4s.sv`](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/bus/axi4lite_interconnect_4s.sv) (AXI4-Lite interconnect), [`rtl/maze/maze_solver_fsm.sv`](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/maze/maze_solver_fsm.sv) (Maze solver FSM), [`rtl/cpu/riscv_core.sv`](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/cpu/riscv_core.sv) (picorv32 wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Sensing"]
  node_hc_sr04["HC-SR04 controller"]
  node_wall_detector["Wall detector<br/>[wall_detector.sv]"]
end

subgraph group_maze["Maze solving"]
  node_solver["Maze solver FSM<br/>[maze_solver_fsm.sv]"]
end

subgraph group_soc["SoC fabric"]
  node_status["Status registers"]
  node_cpu["picorv32 wrapper<br/>[riscv_core.sv]"]
  node_bus["AXI4-Lite interconnect"]
  node_ram[("Program RAM<br/>[prog_ram_axi.sv]")]
  node_uart["UART peripheral<br/>[uart_axi.sv]"]
  node_timer["Timer peripheral<br/>[timer_axi.sv]"]
end

subgraph group_firmware["Firmware"]
  node_firmware_main["Firmware main<br/>[main.c]"]
  node_firmware_uart["UART helpers<br/>[uart.c]"]
  node_firmware_irq["IRQ handler<br/>[irq.S]"]
end

node_echo(("Ultrasonic echo"))
node_side_sensors(("Side wall sensors"))
node_serial(("UART serial endpoint"))

node_echo -->|"echo input"| node_hc_sr04
node_hc_sr04 -->|"distance"| node_wall_detector
node_wall_detector -->|"front wall"| node_solver
node_side_sensors -->|"side walls"| node_solver
node_solver -->|"state signals"| node_status
node_solver -->|"goal interrupt"| node_cpu
node_cpu -->|"AXI requests"| node_bus
node_bus -->|"addressed access"| node_status
node_bus -->|"addressed access"| node_uart
node_bus -->|"addressed access"| node_timer
node_bus -->|"addressed access"| node_ram
node_ram -->|"instruction fetch"| node_cpu
node_cpu -->|"executes"| node_firmware_main
node_firmware_main -->|"calls"| node_firmware_uart
node_firmware_main -->|"reads status"| node_status
node_firmware_main -->|"reads counter"| node_timer
node_firmware_main -->|"configures UART"| node_uart
node_firmware_uart -->|"writes characters"| node_uart
node_firmware_main -->|"enables IRQ"| node_firmware_irq
node_firmware_irq -->|"calls handler"| node_firmware_main
node_firmware_irq -->|"prints completion"| node_firmware_uart
node_uart -->|"serial output"| node_serial

click node_hc_sr04 "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/sensors/hc_sr04_controller.sv"
click node_wall_detector "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/sensors/wall_detector.sv"
click node_solver "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/maze/maze_solver_fsm.sv"
click node_status "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/registers/status_registers_axi.sv"
click node_cpu "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/cpu/riscv_core.sv"
click node_bus "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/bus/axi4lite_interconnect_4s.sv"
click node_ram "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/ram/prog_ram_axi.sv"
click node_uart "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/uart/uart_axi.sv"
click node_timer "https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/timer/timer_axi.sv"
click node_firmware_main "https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/main.c"
click node_firmware_uart "https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/uart.c"
click node_firmware_irq "https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/irq.S"

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_hc_sr04,node_wall_detector toneBlue
class node_solver toneAmber
class node_status,node_cpu,node_bus,node_ram,node_uart,node_timer toneMint
class node_firmware_main,node_firmware_uart,node_firmware_irq toneRose
class node_echo,node_side_sensors,node_serial toneIndigo
```

## Components

### Sensing

- [HC-SR04 controller](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/sensors/hc_sr04_controller.sv): `rtl/sensors/hc_sr04_controller.sv`
- [Wall detector](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/sensors/wall_detector.sv): `rtl/sensors/wall_detector.sv`

### Maze solving

- [Maze solver FSM](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/maze/maze_solver_fsm.sv): `rtl/maze/maze_solver_fsm.sv`

### SoC fabric

- [Status registers](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/registers/status_registers_axi.sv): `rtl/registers/status_registers_axi.sv`
- [picorv32 wrapper](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/cpu/riscv_core.sv): `rtl/cpu/riscv_core.sv`
- [AXI4-Lite interconnect](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/bus/axi4lite_interconnect_4s.sv): `rtl/bus/axi4lite_interconnect_4s.sv`
- [Program RAM](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/ram/prog_ram_axi.sv): `rtl/ram/prog_ram_axi.sv`
- [UART peripheral](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/uart/uart_axi.sv): `rtl/uart/uart_axi.sv`
- [Timer peripheral](https://github.com/shouryadip-c/maze-runner-soc/blob/master/rtl/timer/timer_axi.sv): `rtl/timer/timer_axi.sv`

### Firmware

- [Firmware main](https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/main.c): `firmware/main.c`
- [UART helpers](https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/uart.c): `firmware/uart.c`
- [IRQ handler](https://github.com/shouryadip-c/maze-runner-soc/blob/master/firmware/irq.S): `firmware/irq.S`

### Other components

- **Ultrasonic echo**
- **Side wall sensors**
- **UART serial endpoint**

## Connections

- Ultrasonic echo → HC-SR04 controller: echo input
- HC-SR04 controller → Wall detector: distance
- Wall detector → Maze solver FSM: front wall
- Side wall sensors → Maze solver FSM: side walls
- Maze solver FSM → Status registers: state signals
- Maze solver FSM → picorv32 wrapper: goal interrupt
- picorv32 wrapper → AXI4-Lite interconnect: AXI requests
- AXI4-Lite interconnect → Status registers: addressed access
- AXI4-Lite interconnect → UART peripheral: addressed access
- AXI4-Lite interconnect → Timer peripheral: addressed access
- AXI4-Lite interconnect → Program RAM: addressed access
- Program RAM → picorv32 wrapper: instruction fetch
- picorv32 wrapper → Firmware main: executes
- Firmware main → UART helpers: calls
- Firmware main → Status registers: reads status
- Firmware main → Timer peripheral: reads counter
- Firmware main → UART peripheral: configures UART
- UART helpers → UART peripheral: writes characters
- Firmware main → IRQ handler: enables IRQ
- IRQ handler → Firmware main: calls handler
- IRQ handler → UART helpers: prints completion
- UART peripheral → UART serial endpoint: serial output