Add janus_cube_pyc: 16×16 systolic array matrix multiplication accelerator

[fengzhazha]

Summary

This PR adds a new hardware module janus_cube_pyc - a 16×16 systolic array matrix multiplication accelerator implemented in pyCircuit.

Features

• 16×16 Weight-Stationary Systolic Array: 256 Processing Elements (PEs) arranged in a 16×16 grid
• 16-bit Inputs, 32-bit Accumulators: Supports 16-bit weight and activation values with 32-bit accumulation
• Memory-Mapped Interface: Integrates with CPU via memory-mapped registers at configurable base address
• FSM Control: 5-state FSM (IDLE → LOAD_WEIGHTS → COMPUTE → DRAIN → DONE)
• C++ Testbench: Includes testbench with identity and 2x2 matrix tests

Files Added/Modified

Source Files (janus/pyc/janus/cube/)

• cube.py - Main module with FSM, PE array, and memory interface (357 lines)
• cube_types.py - Dataclasses (CubeState, PERegs, FsmResult, MmioWriteResult)
• cube_consts.py - Constants (states, addresses, array size)
• util.py - Utility functions (Consts dataclass)
• README.md - Documentation

Generated Files (janus/generated/janus_cube_pyc/)

• janus_cube_pyc.v - Verilog RTL (~949 KB)
• janus_cube_pyc_gen.hpp - C++ header (~1.1 MB)

Test Files

• janus/tb/tb_janus_cube_pyc.cpp - C++ testbench
• janus/tools/run_janus_cube_pyc_cpp.sh - Test runner script

Architecture

         Activations (16 × 16-bit)
              ↓ ↓ ↓ ... ↓
            ┌─┬─┬─┬───┬─┐
Weights →   │PE│PE│PE│...│PE│ → Results
(256×16-bit)├─┼─┼─┼───┼─┤
            │PE│PE│PE│...│PE│
            ├─┼─┼─┼───┼─┤
            │ :│ :│ :│   │ :│
            ├─┼─┼─┼───┼─┤
            │PE│PE│PE│...│PE│
            └─┴─┴─┴───┴─┘
              (16×16 = 256 PEs)

Implementation Highlights

The code follows pyCircuit JIT compilation patterns:

1. Functions without @jit_inline execute at Python time (before JIT)

   • Used for register creation loops (_make_pe_regs, _make_weight_regs, etc.)

2. Functions with @jit_inline compile to hardware

   • Used for combinational logic (_build_pe, _build_fsm)

3. Dataclasses for return values avoid tuple unpacking (not supported in JIT)

   • FsmResult(load_weight, compute, done)
   • MmioWriteResult(start, reset_cube)

Testing

# Generate outputs
bash janus/update_generated.sh

# Run C++ testbench
bash janus/tools/run_janus_cube_pyc_cpp.sh

# With tracing
PYC_TRACE=1 PYC_VCD=1 bash janus/tools/run_janus_cube_pyc_cpp.sh

Known Limitations

• Multiplication uses addition as placeholder (pyCircuit limitation)
• Fixed 16×16 array size
• Simplified memory interface (no AXI/AHB)