{"id":13649317,"url":"https://github.com/gsmecher/minimax","last_synced_at":"2026-04-10T05:04:05.789Z","repository":{"id":62182861,"uuid":"558107635","full_name":"gsmecher/minimax","owner":"gsmecher","description":"Minimax: a Compressed-First, Microcoded RISC-V CPU","archived":false,"fork":false,"pushed_at":"2024-04-21T04:58:20.000Z","size":253,"stargazers_count":203,"open_issues_count":3,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-11-10T00:32:56.123Z","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":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gsmecher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-10-26T23:02:11.000Z","updated_at":"2024-10-16T20:38:34.000Z","dependencies_parsed_at":"2024-01-17T16:08:05.375Z","dependency_job_id":"d5b95323-a27d-4be3-81ff-72162f0f3519","html_url":"https://github.com/gsmecher/minimax","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsmecher%2Fminimax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsmecher%2Fminimax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsmecher%2Fminimax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gsmecher%2Fminimax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gsmecher","download_url":"https://codeload.github.com/gsmecher/minimax/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250258918,"owners_count":21400997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-08-02T01:04:56.670Z","updated_at":"2025-12-30T14:04:45.186Z","avatar_url":"https://github.com/gsmecher.png","language":"Verilog","funding_links":[],"categories":["Verilog","CPUs"],"sub_categories":[],"readme":"Minimax: a Compressed-First, Microcoded RISC-V CPU\n==================================================\n\n[![CI status](https://github.com/gsmecher/minimax/workflows/CI/badge.svg)](https://github.com/gsmecher/minimax/actions?query=workflow%3ACI)\n\nWhat?\n-----\n\nRISC-V's compressed instruction (RVC) extension is intended as an add-on to the\nregular, 32-bit instruction set, not a replacement or competitor. Its designers\ndesigned RVC instructions to be expanded into regular 32-bit RV32I equivalents\nvia a pre-decoder.\n\nWhat happens if we *explicitly* architect a RISC-V CPU to execute RVC\ninstructions, and \"mop up\" any RV32I instructions that aren't convenient via a\nmicrocode layer? What architectural optimizations are unlocked as a result?\n\n\"Minimax\" is an experimental RISC-V implementation intended to establish if an\nRVC-optimized CPU is, in practice, any simpler than an ordinary RV32I core with\npre-decoder. While it passes a modest test suite, you should not use it without\ncaution. (There are a large number of excellent, open source, \"little\" RISC-V\nimplementations you should probably use reach for first.)\n\nOriginally, we included both Verilog and VHDL implementations. Sadly, the VHDL\nimplementation has been retired.\n\nIn short:\n\n* RV32C (compressed) instructions are first-class and execute at 1 clock per\n  instruction. (Exceptions: branches have a 2-cycle \"taken\" penalty.)\n\n* All RV32I instructions are emulated in microcode, using the instructions\n  above.\n\nThis is distinct from (all?) other RV32C-capable RISC-V cores, because it\nreally is architected for compressed first. This is not how the compressed\nISA was intended to be implemented.\n\nWhy?\n----\n\nA compressed-first RISC-V architecture unlocks the following:\n\n* 1 clock per instruction (CPI) using a 2-port register file. RVC\n  instructions have only 1 rd and 1 rs field. A 2-port register file\n  maps cleanly into a single RAM64X1D per bit.\n\n* A simplified 16-bit instruction path without alignment considerations. The\n  processor is a modified Harvard architecture, with a separate 16-bit\n  instruction bus intended to connect to a second port of the instruction\n  memory.  On Xilinx, the asymmetric ports (16-bit instruction, 32-bit data)\n  are reconciled using an asymmetric block RAM primitive. As a result, we don't\n  have to worry about a 32-bit instruction split across two 32-bit words.\n\nWhy is this desirable?\n\n* Compilers (GCC, LLVM) are learning to prefer RVC instructions when\n  optimizing for size. This means compiled code (with appropriate\n  optimization settings) plays to Minimax's performance sweet-spot,\n  preferring direct instructions to microcoded instructions.\n  (see e.g. https://muxup.com/2022q3/whats-new-for-risc-v-in-llvm-15)\n\n* RVC instructions nearly double code density, which pay for the cost of\n  microcode ROM when compared against a minimalist RV32I implementation.\n\n* It's not quite the smallest RVC implementation (SERV is smaller), but\n  it is likely much faster with the appropriate compiler settings, and\n  slightly less unorthodox in implementation.\n\nWhat's awkward?\n\n* RVC decoding is definitely uglier than regular RV32I. I expect this\n  ugliness is better masked when RVC instructions are decoded to RV32I and\n  executed as \"regular\" 32-bit instructions.\n\nHow?\n----\n\nWhat's the design like?\n\n* Three-stage pipeline (fetch, decode, and everything-else).\n  There is a corresponding 2-cycle penalty on taken branches.\n\n* Several \"extension instructions\" that use the non-standard extension space\n  reserved in C.SLLI. This space allows us to add \"fused\" instructions\n  accessible only in microcode, that perform the following:\n\n  - \"Thunk\" from microcode back to standard code,\n  - Move data from \"user\" registers into \"microcode\" registers and back again.\n\n  These instructions are only part of the microcode - you are not required to\n  build an unusual toolchain to use Minimax.\n\nPerformance\n===========\n\nResource Usage\n--------------\n\nThe following statistics were collected using an Arty A7 (35T) as an execution\ntarget. This FPGA uses LUT6s.\n\nResource usage (excluding ROM and peripherals; KU060; 12-bit PC):\n\n* Minimax: 191 FFs, 507 CLB LUTs\n\nCompare to:\n\n* PicoRV32: 483 FFs, 782 LUTs (\"small\", RV32I only)\n* FemtoRV32 186 FFs, 411 LUTs (\"quark\", RV32I only)\n* SERV: 312 FFs, 182 LUTs (no CSR or timer; RV32I only)\n* PicoBlaze: 82 FFs, 103 LUTs\n\nMinimax is competitive, even against RV32I-only cores. When comparing\nagainst RV32IC implementations, it does better:\n\n* SERV: 303 FFs, 336 LUTs (no CSR or timer; RV32IC)\n* PicoRV32: 518 FFs, 1085 LUTs (RV32IC)\n\nIt is difficult to gather defensible benchmarks: please treat these as\napproximate, and let me know if they are inaccurate.\n\nFmax\n----\n\nMinimax meets timing closure at 100 MHz on an Artix A7 FPGA (-1 speed grade; xc7a35tcsg324-1).\n\nHow To\n======\n\nRegression Tests\n----------------\n\nThe following command line snippet:\n\n    $ cd minimax/tests\n    $ run\n\n...will run regression tests using the cSail framework. (The regression tests\ntake several minutes to complete; the initial run is even slower since it\ninvolves a git checkout of the regression tests themselves.)\n\nAfter completion, you should see something like the following:\n\n    INFO | TEST NAME                                          : COMMIT ID                                : STATUS\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cadd-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/caddi-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/caddi16sp-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/caddi4spn-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cand-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/candi-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cbeqz-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cbnez-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cj-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cjal-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cjalr-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cjr-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cli-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/clui-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/clw-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/clwsp-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cmv-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cnop-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cor-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cslli-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/csrai-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/csrli-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/csub-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/csw-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cswsp-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/C/src/cxor-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/add-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/addi-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/and-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/andi-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/auipc-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/beq-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/bge-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/bgeu-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/blt-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/bltu-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/bne-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/fence-01.S : 81c7a2b769baa2f33f40bc5455299b1362b5d125 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/jal-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/jalr-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lb-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lbu-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lh-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lhu-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lui-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/lw-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/misalign1-jalr-01.S : 0c4cdffe19b1a48d9fec8590c8817af2ff924a37 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/or-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/ori-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sb-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sh-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sll-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/slli-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/slt-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/slti-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sltiu-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sltu-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sra-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/srai-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/srl-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/srli-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sub-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/sw-align-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/xor-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | /minimax/test/riscv-arch-test/riscv-test-suite/rv32i_m/I/src/xori-01.S : b91f98f3a0e908bad4680c2e3901fbc24b63a563 : Passed\n    INFO | Test report generated at /minimax/test/riscof_work/report.html.\n\n\nExample Bitstream\n-----------------\n\nThe following command line snippet:\n\n    $ source /path/to/Vivado/settings.sh\n    $ cd minimax/tcl\n    $ ./arty_a7.tcl\n\n...will create a \"blinker\" project using a Minimax core in Vivado. You should\nbe able to click \"generate bitstream\" and produce a blinking light using an\nArty A35T board.\n\nContributing\n============\n\nMinimax needs the following:\n\n* Zicsr and interrupt support\n\nI am happy to collaborate and/or provide mentorship on this or any other\nMinimax-related project.  Comments and PRs always welcome.\n\nGraeme Smecher\ngsmecher@threespeedlogic.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsmecher%2Fminimax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgsmecher%2Fminimax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgsmecher%2Fminimax/lists"}