# pulp-platform/hwpe-tb architecture

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

- Interactive diagram: https://gitdiagram.com/pulp-platform/hwpe-tb
- Repository: https://github.com/pulp-platform/hwpe-tb

## Overview

This repository is an almost-standalone simulation testbench for a PULP Hardware Processing Engine (HWPE), demonstrating fixed-point multiply-accumulate offload from a RISC-V core. The principal workflow is: the C test configures the accelerator through memory-mapped registers, starts a job, waits for completion, and checks output values; the RTL testbench supplies the simulated platform. The README documents the core, dummy memories, and accelerator IPs, but their RTL internals are not included in the excerpts, so those relationships are shown only where documented.

Main entry points: [`sw/tb_hwpe.c`](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/tb_hwpe.c) (C testbench), [`hw/rtl/sim_hwpe.sv`](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/sim_hwpe.sv) (Simulation top), [`hw/rtl/tb_hwpe.sv`](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/tb_hwpe.sv) (RTL testbench), [`hw/ips/hwpe-mac-engine`](https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-mac-engine) (MAC engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_software["Software test"]
  node_test["C testbench<br/>[tb_hwpe.c]"]
  node_registers["Register definitions<br/>[archi_hwpe.h]"]
  node_hal["HWPE HAL<br/>[hal_hwpe.h]"]
  node_stimuli["Input vectors"]
  node_printf["Tiny printf<br/>[tinyprintf.h]"]
  node_boot["Boot code<br/>[crt0.S]"]
  node_vectors["Interrupt vectors<br/>[vectors.S]"]
end

subgraph group_platform["Simulation platform"]
  node_core(("RISC-V core"))
  node_rtlbench["RTL testbench<br/>[tb_hwpe.sv]"]
  node_simtop["Simulation top<br/>[sim_hwpe.sv]"]
  node_memories[("Dummy memories<br/>[tb_dummy_memory.sv]")]
  node_simulator["Verilator driver<br/>[sim_main.cpp]"]
  node_result[("Output memory")]
end

subgraph group_accelerator["HWPE IPs"]
  node_mac["MAC engine"]
  node_control["HWPE control"]
  node_stream["HWPE streaming"]
end

node_core -->|"runs"| node_test
node_test -->|"uses offsets"| node_registers
node_test -->|"configures and starts"| node_hal
node_test -->|"loads vectors"| node_stimuli
node_test -->|"includes"| node_printf
node_boot -.->|"boots"| node_core
node_vectors -.->|"provides vectors"| node_core
node_rtlbench -->|"hosts"| node_core
node_rtlbench -->|"uses"| node_memories
node_rtlbench -.->|"instantiates"| node_simtop
node_simulator -->|"evaluates"| node_simtop
node_simtop -->|"integrates"| node_control
node_simtop -->|"integrates"| node_stream
node_simtop -->|"integrates"| node_mac
node_mac -.->|"streams data"| node_memories
node_test -->|"checks values"| node_result

click node_test "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/tb_hwpe.c"
click node_registers "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/archi_hwpe.h"
click node_hal "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/hal_hwpe.h"
click node_stimuli "https://github.com/pulp-platform/hwpe-tb/tree/master/sw/inc"
click node_printf "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/tinyprintf.h"
click node_boot "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/crt0.S"
click node_vectors "https://github.com/pulp-platform/hwpe-tb/blob/master/sw/vectors.S"
click node_rtlbench "https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/tb_hwpe.sv"
click node_simtop "https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/sim_hwpe.sv"
click node_memories "https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/tb_dummy_memory.sv"
click node_simulator "https://github.com/pulp-platform/hwpe-tb/blob/master/hw/sim_main.cpp"
click node_mac "https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-mac-engine"
click node_control "https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-ctrl"
click node_stream "https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-stream"

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_test,node_registers,node_hal,node_stimuli,node_printf,node_boot,node_vectors toneBlue
class node_core,node_rtlbench,node_simtop,node_memories,node_simulator,node_result toneAmber
class node_mac,node_control,node_stream toneMint
```

## Components

### Software test

- [C testbench](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/tb_hwpe.c): `sw/tb_hwpe.c`
- [Register definitions](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/archi_hwpe.h): `sw/archi_hwpe.h`
- [HWPE HAL](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/hal_hwpe.h): `sw/hal_hwpe.h`
- [Input vectors](https://github.com/pulp-platform/hwpe-tb/tree/master/sw/inc): `sw/inc`
- [Tiny printf](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/tinyprintf.h): `sw/tinyprintf.h`
- [Boot code](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/crt0.S): `sw/crt0.S`
- [Interrupt vectors](https://github.com/pulp-platform/hwpe-tb/blob/master/sw/vectors.S): `sw/vectors.S`

### Simulation platform

- **RISC-V core**
- [RTL testbench](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/tb_hwpe.sv): `hw/rtl/tb_hwpe.sv`
- [Simulation top](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/sim_hwpe.sv): `hw/rtl/sim_hwpe.sv`
- [Dummy memories](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/rtl/tb_dummy_memory.sv): `hw/rtl/tb_dummy_memory.sv`
- [Verilator driver](https://github.com/pulp-platform/hwpe-tb/blob/master/hw/sim_main.cpp): `hw/sim_main.cpp`
- **Output memory**

### HWPE IPs

- [MAC engine](https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-mac-engine): `hw/ips/hwpe-mac-engine`
- [HWPE control](https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-ctrl): `hw/ips/hwpe-ctrl`
- [HWPE streaming](https://github.com/pulp-platform/hwpe-tb/tree/master/hw/ips/hwpe-stream): `hw/ips/hwpe-stream`

## Connections

- RISC-V core → C testbench: runs (evidence: `README.md`)
- C testbench → Register definitions: uses offsets (evidence: `sw/tb_hwpe.c`)
- C testbench → HWPE HAL: configures and starts (evidence: `sw/tb_hwpe.c`)
- C testbench → Input vectors: loads vectors (evidence: `sw/tb_hwpe.c`)
- C testbench → Tiny printf: includes (evidence: `sw/tb_hwpe.c`)
- Boot code → RISC-V core: boots (evidence: `README.md`)
- Interrupt vectors → RISC-V core: provides vectors (evidence: `README.md`)
- RTL testbench → RISC-V core: hosts (evidence: `README.md`)
- RTL testbench → Dummy memories: uses (evidence: `README.md`)
- RTL testbench → Simulation top: instantiates
- Verilator driver → Simulation top: evaluates (evidence: `hw/sim_main.cpp`)
- Simulation top → HWPE control: integrates (evidence: `README.md`)
- Simulation top → HWPE streaming: integrates (evidence: `README.md`)
- Simulation top → MAC engine: integrates (evidence: `README.md`)
- MAC engine → Dummy memories: streams data
- C testbench → Output memory: checks values (evidence: `sw/tb_hwpe.c`)
