# s-steven-joshua/js-soc architecture

> Architecture diagram of the GitHub repository s-steven-joshua/js-soc, 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/s-steven-joshua/js-soc
- Repository: https://github.com/s-steven-joshua/js-soc

## Overview

JS-SoC is a SystemVerilog RV32I single-cycle SoC. Its main workflow executes instructions on the CPU, routes load/store accesses through a bridge to normal memory or APB peripherals, and can write peripheral data back for CPU use. A separate boot path assembles incoming bytes into instructions and initializes IMEM. The README documents these flows and major capabilities; RTL variants differ, and the excerpts do not establish all module-level wiring, so the graph stays at documented subsystem boundaries where needed.

Main entry points: [`RTL/SoC_V3/src/decoder_logic.sv`](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/decoder_logic.sv) (APB Decoder), [`RTL/SoC_V3/src/core.sv`](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/core.sv) (RV32I CPU), [`RTL/SoCV1/src/peripherial_ram.sv`](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoCV1/src/peripherial_ram.sv) (Peripheral RAM), [`RTL/SoC_V3/src/datapath.sv`](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/datapath.sv) (Single-Cycle Datapath)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cpu["RV32I Processor"]
  node_cpu["RV32I CPU<br/>[core.sv]"]
  node_datapath["Single-Cycle Datapath<br/>[datapath.sv]"]
  node_controller["Control Unit<br/>[controller.sv]"]
  node_alu["ALU<br/>[alu.sv]"]
  node_registers[("Register File<br/>[register_file.sv]")]
  node_imem[("Instruction Memory<br/>[imem.sv]")]
end

subgraph group_access["Memory Access"]
  node_dmem[("Data Memory<br/>[dmem.sv]")]
  node_bridge["Access Bridge<br/>[bridge.sv]"]
  node_apb["APB Master<br/>[apb_master.sv]"]
  node_decoder["APB Decoder<br/>[decoder_logic.sv]"]
end

subgraph group_peripherals["Peripherals"]
  node_uart["UART<br/>[uart_soc.sv]"]
  node_pwm["PWM<br/>[pwm.sv]"]
  node_timer["Timer<br/>[timer.sv]"]
  node_i2c["I²C Peripheral<br/>[i2c_top.sv]"]
  node_periph_ram[("Peripheral RAM<br/>[peripherial_ram.sv]")]
  node_writeback["Peripheral Write-Back<br/>[datapath.sv]"]
end

subgraph group_boot["Instruction Boot"]
  node_bootloader["Bootloader<br/>[bootloader.sv]"]
end

subgraph group_utilities["Control Word Tools"]
  node_pwm_word["PWM Word Generator<br/>[pwm.java]"]
  node_timer_word["Timer Word Generator"]
end

node_programmer(("Program / Data Source"))
node_bootdata(("External Boot Data"))

node_programmer -->|"provides program"| node_cpu
node_cpu -->|"routes accesses"| node_bridge
node_bridge -->|"selects normal memory"| node_dmem
node_bridge -->|"selects APB access"| node_apb
node_apb -->|"decodes address"| node_decoder
node_decoder -->|"selects peripheral"| node_uart
node_decoder -->|"selects peripheral"| node_pwm
node_decoder -->|"selects peripheral"| node_timer
node_decoder -->|"selects peripheral"| node_i2c
node_uart -->|"writes peripheral data"| node_periph_ram
node_pwm -->|"writes peripheral data"| node_periph_ram
node_timer -->|"writes peripheral data"| node_periph_ram
node_i2c -->|"writes peripheral data"| node_periph_ram
node_periph_ram -->|"supplies write-back data"| node_writeback
node_writeback -->|"returns CPU data"| node_cpu
node_bootdata -->|"sends bytes"| node_bootloader
node_bootloader -->|"initializes instructions"| node_imem
node_bootloader -->|"holds during loading"| node_cpu
node_imem -->|"provides instructions"| node_cpu
node_datapath -.->|"uses control signals"| node_controller
node_datapath -.->|"executes operations"| node_alu
node_datapath -.->|"reads and writes"| node_registers
node_pwm_word -.->|"formats register value"| node_pwm
node_timer_word -.->|"formats control word"| node_timer

click node_cpu "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/core.sv"
click node_datapath "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/datapath.sv"
click node_controller "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/controller.sv"
click node_alu "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/alu.sv"
click node_registers "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/register_file.sv"
click node_imem "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/imem.sv"
click node_dmem "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/dmem.sv"
click node_bridge "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/bridge.sv"
click node_apb "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/apb_master.sv"
click node_decoder "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/decoder_logic.sv"
click node_uart "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/uart_soc.sv"
click node_pwm "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/pwm.sv"
click node_timer "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/timer.sv"
click node_i2c "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoCV1/src/i2c_top.sv"
click node_periph_ram "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoCV1/src/peripherial_ram.sv"
click node_writeback "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/datapath.sv"
click node_bootloader "https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/bootloader.sv"
click node_pwm_word "https://github.com/s-steven-joshua/js-soc/blob/main/Java_files/pwm.java"
click node_timer_word "https://github.com/s-steven-joshua/js-soc/blob/main/Java_files/timer_generation.java"

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_cpu,node_datapath,node_controller,node_alu,node_registers,node_imem toneBlue
class node_dmem,node_bridge,node_apb,node_decoder toneAmber
class node_uart,node_pwm,node_timer,node_i2c,node_periph_ram,node_writeback toneMint
class node_bootloader toneRose
class node_pwm_word,node_timer_word,node_programmer,node_bootdata toneIndigo
```

## Components

### RV32I Processor

- [RV32I CPU](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/core.sv): `RTL/SoC_V3/src/core.sv`
- [Single-Cycle Datapath](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/datapath.sv): `RTL/SoC_V3/src/datapath.sv`
- [Control Unit](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/controller.sv): `RTL/SoC_V3/src/controller.sv`
- [ALU](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/alu.sv): `RTL/SoC_V3/src/alu.sv`
- [Register File](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/register_file.sv): `RTL/SoC_V3/src/register_file.sv`
- [Instruction Memory](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/imem.sv): `RTL/SoC_V3/src/imem.sv`

### Memory Access

- [Data Memory](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/dmem.sv): `RTL/SoC_V3/src/dmem.sv`
- [Access Bridge](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/bridge.sv): `RTL/SoC_V3/src/bridge.sv`
- [APB Master](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/apb_master.sv): `RTL/SoC_V3/src/apb_master.sv`
- [APB Decoder](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/decoder_logic.sv): `RTL/SoC_V3/src/decoder_logic.sv`

### Peripherals

- [UART](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/uart_soc.sv): `RTL/SoC_V3/src/uart_soc.sv`
- [PWM](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/pwm.sv): `RTL/SoC_V3/src/pwm.sv`
- [Timer](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/timer.sv): `RTL/SoC_V3/src/timer.sv`
- [I²C Peripheral](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoCV1/src/i2c_top.sv): `RTL/SoCV1/src/i2c_top.sv`
- [Peripheral RAM](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoCV1/src/peripherial_ram.sv): `RTL/SoCV1/src/peripherial_ram.sv`
- [Peripheral Write-Back](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/datapath.sv): `RTL/SoC_V3/src/datapath.sv`

### Instruction Boot

- [Bootloader](https://github.com/s-steven-joshua/js-soc/blob/main/RTL/SoC_V3/src/bootloader.sv): `RTL/SoC_V3/src/bootloader.sv`

### Control Word Tools

- [PWM Word Generator](https://github.com/s-steven-joshua/js-soc/blob/main/Java_files/pwm.java): `Java_files/pwm.java`
- [Timer Word Generator](https://github.com/s-steven-joshua/js-soc/blob/main/Java_files/timer_generation.java): `Java_files/timer_generation.java`

### Other components

- **Program / Data Source**
- **External Boot Data**

## Connections

- Program / Data Source → RV32I CPU: provides program (evidence: `README.md`)
- RV32I CPU → Access Bridge: routes accesses (evidence: `README.md`)
- Access Bridge → Data Memory: selects normal memory (evidence: `README.md`)
- Access Bridge → APB Master: selects APB access (evidence: `README.md`)
- APB Master → APB Decoder: decodes address (evidence: `README.md`)
- APB Decoder → UART: selects peripheral (evidence: `README.md`)
- APB Decoder → PWM: selects peripheral (evidence: `README.md`)
- APB Decoder → Timer: selects peripheral (evidence: `README.md`)
- APB Decoder → I²C Peripheral: selects peripheral (evidence: `README.md`)
- UART → Peripheral RAM: writes peripheral data (evidence: `README.md`)
- PWM → Peripheral RAM: writes peripheral data (evidence: `README.md`)
- Timer → Peripheral RAM: writes peripheral data (evidence: `README.md`)
- I²C Peripheral → Peripheral RAM: writes peripheral data (evidence: `README.md`)
- Peripheral RAM → Peripheral Write-Back: supplies write-back data (evidence: `README.md`)
- Peripheral Write-Back → RV32I CPU: returns CPU data (evidence: `README.md`)
- External Boot Data → Bootloader: sends bytes (evidence: `README.md`)
- Bootloader → Instruction Memory: initializes instructions (evidence: `README.md`)
- Bootloader → RV32I CPU: holds during loading (evidence: `README.md`)
- Instruction Memory → RV32I CPU: provides instructions (evidence: `README.md`)
- Single-Cycle Datapath → Control Unit: uses control signals
- Single-Cycle Datapath → ALU: executes operations
- Single-Cycle Datapath → Register File: reads and writes
- PWM Word Generator → PWM: formats register value
- Timer Word Generator → Timer: formats control word