{"id":51241008,"url":"https://github.com/celpha2svx/matrix-riscv","last_synced_at":"2026-06-29T00:03:22.406Z","repository":{"id":357814484,"uuid":"1237656843","full_name":"celpha2svx/matrix-riscv","owner":"celpha2svx","description":"Custom RISC-V core with Matrix MAC instruction","archived":false,"fork":false,"pushed_at":"2026-06-05T23:08:12.000Z","size":899,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T00:12:00.577Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/celpha2svx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T11:38:30.000Z","updated_at":"2026-06-05T23:08:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/celpha2svx/matrix-riscv","commit_stats":null,"previous_names":["celpha2svx/matrix-riscv"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/celpha2svx/matrix-riscv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fmatrix-riscv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fmatrix-riscv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fmatrix-riscv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fmatrix-riscv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/celpha2svx","download_url":"https://codeload.github.com/celpha2svx/matrix-riscv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fmatrix-riscv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34907985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-29T00:03:21.547Z","updated_at":"2026-06-29T00:03:22.394Z","avatar_url":"https://github.com/celpha2svx.png","language":"Verilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ⚡ Matrix-RISCV\n\n### A Custom MAC Instruction for Memory-Efficient Machine Learning\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Language: Verilog](https://img.shields.io/badge/Language-Verilog-blue.svg)](https://github.com/celpha2svx/matrix-riscv)\n[![Architecture: RV32I](https://img.shields.io/badge/Architecture-RV32I-green.svg)](https://riscv.org/)\n[![Simulation: Icarus Verilog](https://img.shields.io/badge/Sim-Icarus%20Verilog-orange.svg)](http://iverilog.icarus.com/)\n\n*A single-cycle RV32I RISC-V processor extended with a custom Multiply-Accumulate instruction — built for ML workloads on memory-constrained hardware.*\n\n\u003c/div\u003e\n\n---\n\n## 🧠 The Problem\n\nTraining ML models requires **millions of matrix multiply-accumulate operations**. On a standard RISC-V core, every single MAC costs two instructions:\n\n```asm\nmul  t0, a0, a1    # Multiply   → 1 instruction, 1 cycle, 1 register write\nadd  a2, a2, t0    # Accumulate → 1 instruction, 1 cycle, 1 register write\n```\n\nThat's **2 cycles, 2 register writes, 8 bytes of instruction memory** per MAC. On a 4 GB RAM machine, your instruction stream competes directly with your training data for memory bandwidth. At 1 million MACs, you're burning **8 MB just on instruction fetches** — before a single weight is touched.\n\n---\n\n## ✅ The Solution\n\n```asm\nmac  a2, a0, a1    # a2 = a2 + (a0 * a1) — ONE instruction, ONE cycle\n```\n\nA single custom instruction that does the full multiply-accumulate in **one cycle**. Half the instructions. Half the memory traffic. Same result.\n\n![Comparison Diagram](images/comparison.png)\n\n---\n\n## 🌍 Why This Matters Beyond the Numbers\n\nMost researchers building AI on constrained hardware — students, independent\nresearchers, developers in low-resource environments — don't have the luxury\nof throwing more RAM at the problem.\n\nThis project asks a different question: what if the instruction set itself\nwas part of the solution?\n\nA 50% reduction in instruction fetch overhead is not just a benchmark number.\nOn a 4GB RAM machine running a real ML workload, it means the difference\nbetween training completing and training stalling. This is hardware designed\nfor the constraints that actually exist — not the constraints that are\nconvenient to assume away.\n\n---\n\n## 📐 Instruction Encoding\n\n```\n 31      25  24   20  19  15  14  12  11   7  6      0\n┌──────────┬───────┬───────┬───────┬───────┬─────────┐\n│  funct7  │  rs2  │  rs1  │funct3 │  rd   │ opcode  │\n│ 0000001  │  rs2  │  rs1  │  000  │  rd   │ 0001011 │\n└──────────┴───────┴───────┴───────┴───────┴─────────┘\n                                          custom-0\n```\n\n`mac rd, rs1, rs2` → R-type, opcode `0001011` (RISC-V custom-0 space)\n\n---\n\n## ⚙️ Hardware Architecture\n\nThe datapath below shows how `MatrixALU` plugs into the writeback stage. The Register File gains a third read port (`rd / h4`) so the old accumulator value is available every cycle. A 3-input MUX selects between ALU, Data Memory, and MAC result via a 2-bit `ResultSrc`.\n\n![Datapath Diagram](images/datapath.png)\n\n### Modified Modules\n\n| Module | Modification |\n|---|---|\n| `MatrixALU.v` | New 32-bit signed Multiply-Accumulate unit |\n| `Register_File.v` | Third read port (A4/RD4) to read `rd` for accumulation |\n| `Mux.v` | Extended 2→3 input (ALU / Memory / MAC) with 2-bit select |\n| `Main_Decoder.v` | Detects custom-0 opcode and asserts `MAC_Enable` |\n| `Control_Unit_Top.v` | Routes `MAC_Enable` through the control path |\n| `Single_Cycle_Top.v` | Integrates `MatrixALU` into the writeback stage |\n\n---\n\n## 📊 Results\n\n### Simulation Waveform — 16-MAC Benchmark\n\nThe waveform below shows all control signals across 16 consecutive MAC cycles. `MAC_Enable` and `RegWrite` stay high for every MAC instruction and drop exactly at the store — confirming the decoder and datapath are working correctly with no stray cycles.\n\n![Simulation Waveform](waveform.png)\n\n### 4×4 Matrix MAC Benchmark — Real Simulation Numbers\n\nBoth versions were compiled and simulated on the same processor using Icarus Verilog. The standard version uses `mul`+`add` pairs. The MAC version uses the custom `mac` instruction. Results captured directly from simulation output:\n\n![Benchmark Chart](benchmark_chart.png)\n\n| Metric | Standard (`mul`+`add`) | Matrix-RISCV (`mac`) | Reduction |\n|---|---|---|---|\n| Total instructions | 33 | 17 | **~48.5%** |\n| Register writes | 32 | 16 | **50%** |\n| Instruction memory traffic | 132 bytes | 68 bytes | **~48.5%** |\n| MAC instructions | 0 | 16 | — |\n\n\u003e These are real numbers from simulation, not theoretical estimates. Full logs in `result_mac.txt` and `result_standard.txt`.\n\n### Original 4-MAC Functional Verification\n\nReal terminal output confirming correct chained accumulation:\n\n![MAC Cycles Terminal Output](images/MAC-Cycles.jpg)\n\n```\nCycle 1: Instr=0262828b MAC=1 RegWrite=1 MACResult=000002d6  →  726\nCycle 2: Instr=0262828b MAC=1 RegWrite=1 MACResult=00001f32  →  7,986\nCycle 3: Instr=0262828b MAC=1 RegWrite=1 MACResult=00015726  →  87,846\nCycle 4: Instr=0262828b MAC=1 RegWrite=1 MACResult=000ebea2  →  966,306\nSimulation finished.\n```\n\n---\n\n## 🚀 Quick Start\n\n**Prerequisites**\n- [Icarus Verilog](http://iverilog.icarus.com/) (`iverilog`)\n\n**Clone \u0026 Simulate**\n\n```bash\ngit clone https://github.com/celpha2svx/matrix-riscv.git\ncd matrix-riscv\niverilog -o simv Single_Cycle_Top.v Single_Cycle_Top_Tb.v\n./simv\n```\n\n**Run the 4×4 Benchmark**\n\n```bash\n# MAC version\ncp matmul_mac.hex memfile.hex\niverilog -o bench_mac Single_Cycle_Top.v Benchmark_Tb.v \u0026\u0026 ./bench_mac\n\n# Standard version\ncp matmul_standard.hex memfile.hex\niverilog -o bench_std Single_Cycle_Top.v Benchmark_Tb.v \u0026\u0026 ./bench_std\n```\n\n**Expected Output (MAC version)**\n\n```\nCycle 1: Instr=0262828b MAC=1 RegWrite=1 MACResult=00000042\n...\nCycle 16: Instr=0262828b MAC=1 RegWrite=1 MACResult=1442a086\n========================================\n         BENCHMARK RESULTS\n========================================\nTotal instructions executed : 17\nMAC instructions            : 16\nRegister writes             : 16\nInstruction memory traffic  : 68 bytes\n========================================\n```\n\n---\n\n## 📁 File Reference\n\n| File | Description |\n|---|---|\n| `MatrixALU.v` | Custom 32-bit signed MAC hardware unit |\n| `Register_File.v` | Extended register file with third read port |\n| `Mux.v` | 3-input multiplexer for writeback `ResultSrc` |\n| `Main_Decoder.v` | Control decoder with custom-0 opcode support |\n| `Control_Unit_Top.v` | Top-level control unit routing `MAC_Enable` |\n| `Single_Cycle_Top.v` | Full processor with MAC datapath integrated |\n| `Single_Cycle_Top_Tb.v` | Original testbench (4-MAC verification) |\n| `Benchmark_Tb.v` | Extended testbench for 4×4 benchmark with counters |\n| `mac_bench.hex` | Original test program: 4 MACs + store |\n| `matmul_mac.hex` | 4×4 benchmark: 16 MAC instructions |\n| `matmul_standard.hex` | 4×4 benchmark: 32 standard mul+add instructions |\n| `result_mac.txt` | Full simulation log — MAC version |\n| `result_standard.txt` | Full simulation log — standard version |\n| `benchmark_chart.png` | Bar chart comparing both approaches |\n| `waveform.png` | Signal waveform across 16-MAC benchmark |\n| `plot_benchmark.py` | Python script that generated the benchmark chart |\n| `plot_waveform.py` | Python script that generated the waveform figure |\n\n---\n\n## 🗺️ Roadmap\n\n- [ ] FPGA synthesis (Tang Nano / ICE40 target)\n- [ ] Vector MAC for SIMD-style parallelism\n- [ ] Integration with TinyML inference\n- [ ] Memory bandwidth measurement on physical hardware\n- [ ] Paper submission — RISC-V Summit / CARRV workshop\n\n---\n\n## 👤 Author\n\n**Ademuyiwa Afeez** — Building efficient hardware for resource-constrained machine learning.\n\n\u003e *\"We don't need bigger machines. We need smarter architectures.\"*\n\n---\n\n## 📄 License\n\n[MIT](LICENSE) — Build on it. Improve it. Share it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fmatrix-riscv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelpha2svx%2Fmatrix-riscv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fmatrix-riscv/lists"}