# valmyr/systoliccore architecture

> Architecture diagram of the GitHub repository valmyr/systoliccore, 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/valmyr/systoliccore
- Repository: https://github.com/valmyr/systoliccore

## Overview

This repository implements a parameterized systolic-array matrix-multiplication accelerator, with a Python-side workflow for preparing matrices and convolution workloads and communicating with a Zynq FPGA. The main path prepares and arranges operands, sends them over TCP to the board, transfers data toward programmable logic, performs multiply-accumulate operations, and returns results. The README describes the array and operand shifting; sampled Python and C show client/server and FIFO behavior. RTL wiring beyond the documented architecture is inferred from module names, so uncertain connections are omitted.

Main entry points: [`python/echo_backup_funcional.c`](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/echo_backup_funcional.c) (TCP echo server), [`rtl/systolicMatrixMultiply.sv`](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/systolicMatrixMultiply.sv) (Matrix multiply), [`rtl/SystolicCore.sv`](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/SystolicCore.sv) (Systolic core), [`python/ethernet_server_zynq.py`](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py) (TCP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workload["Workload preparation"]
  node_conv["Convolution workflow"]
  node_arrange["Operand arrangement"]
  node_client["TCP client"]
end

subgraph group_transport["Board transport"]
  node_server["TCP echo server"]
  node_fifo["AXI FIFO transfer"]
end

subgraph group_hardware["Accelerator RTL"]
  node_matrix["Matrix multiply"]
  node_core["Systolic core<br/>[SystolicCore.sv]"]
  node_accum["Multiply accumulate<br/>[accumulator.sv]"]
end

subgraph group_support["Data movement"]
  node_stream["AXI stream core"]
  node_control["Systolic control"]
  node_shift["Operand shifting<br/>[shiftdata.sv]"]
  node_serial["Serial conversion<br/>[serial2mem.sv]"]
  node_result["Result conversion<br/>[mem2serial.sv]"]
end

node_user(("Workload user"))
node_board(("Zynq board"))

node_user -->|"supplies workload"| node_conv
node_conv -->|"prepares operands"| node_arrange
node_arrange -->|"provides operands"| node_client
node_client -->|"sends TCP data"| node_server
node_server -->|"writes input words"| node_fifo
node_fifo -.->|"transfers data"| node_stream
node_stream -.->|"streams input"| node_serial
node_serial -.->|"supplies operands"| node_matrix
node_matrix -.->|"controls computation"| node_core
node_core -.->|"multiplies and accumulates"| node_accum
node_core -.->|"forwards operands"| node_shift
node_matrix -.->|"provides results"| node_result
node_result -.->|"returns output data"| node_fifo
node_fifo -->|"reads output words"| node_server
node_server -->|"writes TCP response"| node_client

click node_conv "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py"
click node_arrange "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py"
click node_client "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py"
click node_server "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/echo_backup_funcional.c"
click node_fifo "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/echo_backup_funcional.c"
click node_stream "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/AXI_Stream_Systolic_Core.v"
click node_control "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/SystolicControlUnit.sv"
click node_matrix "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/systolicMatrixMultiply.sv"
click node_core "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/SystolicCore.sv"
click node_accum "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/accumulator.sv"
click node_shift "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/shiftdata.sv"
click node_serial "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/serial2mem.sv"
click node_result "https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/mem2serial.sv"

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_conv,node_arrange,node_client,node_user toneBlue
class node_server,node_fifo toneAmber
class node_matrix,node_core,node_accum toneMint
class node_stream,node_control,node_shift,node_serial,node_result toneRose
class node_board toneIndigo
```

## Components

### Workload preparation

- [Convolution workflow](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py): `python/ethernet_server_zynq.py`
- [Operand arrangement](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py): `python/ethernet_server_zynq.py`
- [TCP client](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/ethernet_server_zynq.py): `python/ethernet_server_zynq.py`

### Board transport

- [TCP echo server](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/echo_backup_funcional.c): `python/echo_backup_funcional.c`
- [AXI FIFO transfer](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/python/echo_backup_funcional.c): `python/echo_backup_funcional.c`

### Accelerator RTL

- [Matrix multiply](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/systolicMatrixMultiply.sv): `rtl/systolicMatrixMultiply.sv`
- [Systolic core](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/SystolicCore.sv): `rtl/SystolicCore.sv`
- [Multiply accumulate](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/accumulator.sv): `rtl/accumulator.sv`

### Data movement

- [AXI stream core](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/AXI_Stream_Systolic_Core.v): `rtl/AXI_Stream_Systolic_Core.v`
- [Systolic control](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/SystolicControlUnit.sv): `rtl/SystolicControlUnit.sv`
- [Operand shifting](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/shiftdata.sv): `rtl/shiftdata.sv`
- [Serial conversion](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/serial2mem.sv): `rtl/serial2mem.sv`
- [Result conversion](https://github.com/valmyr/systoliccore/blob/Systolic_Core_Pipeline/rtl/mem2serial.sv): `rtl/mem2serial.sv`

### Other components

- **Workload user**
- **Zynq board**

## Connections

- Workload user → Convolution workflow: supplies workload
- Convolution workflow → Operand arrangement: prepares operands
- Operand arrangement → TCP client: provides operands
- TCP client → TCP echo server: sends TCP data
- TCP echo server → AXI FIFO transfer: writes input words
- AXI FIFO transfer → AXI stream core: transfers data
- AXI stream core → Serial conversion: streams input
- Serial conversion → Matrix multiply: supplies operands
- Matrix multiply → Systolic core: controls computation
- Systolic core → Multiply accumulate: multiplies and accumulates
- Systolic core → Operand shifting: forwards operands
- Matrix multiply → Result conversion: provides results
- Result conversion → AXI FIFO transfer: returns output data
- AXI FIFO transfer → TCP echo server: reads output words
- TCP echo server → TCP client: writes TCP response