{"id":49107355,"url":"https://github.com/hwang-fu/rv32emu","last_synced_at":"2026-04-21T02:17:39.065Z","repository":{"id":330995947,"uuid":"1124373982","full_name":"hwang-fu/rv32emu","owner":"hwang-fu","description":"Fully emulating the RISC-V Base Integer Instruction Set (WIP)","archived":false,"fork":false,"pushed_at":"2025-12-29T17:24:01.000Z","size":38,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-01T20:16:12.649Z","etag":null,"topics":["byte-code","dune","emulator","functional-programming","ocaml","risc-v","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hwang-fu.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T22:54:34.000Z","updated_at":"2026-01-01T18:27:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hwang-fu/rv32emu","commit_stats":null,"previous_names":["hwang-fu/rv32emu"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hwang-fu/rv32emu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwang-fu%2Frv32emu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwang-fu%2Frv32emu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwang-fu%2Frv32emu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwang-fu%2Frv32emu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hwang-fu","download_url":"https://codeload.github.com/hwang-fu/rv32emu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwang-fu%2Frv32emu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32073515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T01:35:38.224Z","status":"online","status_checked_at":"2026-04-21T02:00:06.111Z","response_time":128,"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":["byte-code","dune","emulator","functional-programming","ocaml","risc-v","virtual-machine"],"created_at":"2026-04-21T02:17:38.338Z","updated_at":"2026-04-21T02:17:39.050Z","avatar_url":"https://github.com/hwang-fu.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rv32emu\n\nA RISC-V RV32I emulator implemented from scratch in OCaml.\n\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()\n[![OCaml](https://img.shields.io/badge/OCaml-%3E%3D5.4.0-orange)]()\n[![License](https://img.shields.io/badge/license-MIT-blue)]()\n\n## Overview\n\n**rv32emu** is a cycle-accurate emulator for the RISC-V RV32I base integer instruction set, built entirely from the ground up in OCaml. This project demonstrates deep understanding of CPU architecture, instruction encoding, and low-level systems programming through a functional programming lens.\n\n### Why OCaml?\n\nOCaml's type system and pattern matching make it exceptionally well-suited for instruction set emulation:\n\n- **Algebraic Data Types** elegantly represent the instruction set taxonomy\n- **Exhaustive Pattern Matching** ensures all instruction variants are handled\n- **Strong Static Typing** catches encoding errors at compile time\n- **Immutable-First Design** makes CPU state transitions explicit and testable\n\n## Current Status\n\n### Implemented\n\n- **Type System** — Foundational types for words, addresses, and register indices\n- **Bit Manipulation** — Utilities for instruction field extraction and sign/zero extension\n- **Register File** — 32 general-purpose registers with x0 hardwired to zero\n- **Memory Subsystem** — Byte-addressable little-endian memory with load/store operations\n- **Test Suite** — 42 unit tests covering all foundation components\n\n### In Development\n\n- Instruction decoder (R/I/S/B/U/J-type formats)\n- Instruction execution engine\n- CPU fetch-decode-execute cycle\n\n### Planned\n\n- ELF binary loading\n- System call emulation\n- Instruction tracing and debugging\n- RISC-V compliance testing\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph Foundation [\"Foundation Layer ✓\"]\n        Types[\"\u003cb\u003eTypes\u003c/b\u003e\u003cbr/\u003eword, address, pc\"]\n        Bits[\"\u003cb\u003eBits\u003c/b\u003e\u003cbr/\u003eextract, sign_ext, zero_ext\"]\n        Registers[\"\u003cb\u003eRegisters\u003c/b\u003e\u003cbr/\u003ex0-x31 (x0=0)\"]\n        Memory[\"\u003cb\u003eMemory\u003c/b\u003e\u003cbr/\u003eload/store (little-endian)\"]\n    end\n\n    subgraph Core [\"Core Pipeline\"]\n        Decode[\"\u003cb\u003eDecode\u003c/b\u003e\u003cbr/\u003eR/I/S/B/U/J-type\u003cbr/\u003e\u003ci\u003eIn Development\u003c/i\u003e\"]\n        Execute[\"\u003cb\u003eExecute\u003c/b\u003e\u003cbr/\u003eALU, Load/Store, Branch\u003cbr/\u003e\u003ci\u003ePlanned\u003c/i\u003e\"]\n        CPU[\"\u003cb\u003eCPU\u003c/b\u003e\u003cbr/\u003eFetch → Decode → Execute\u003cbr/\u003e\u003ci\u003ePlanned\u003c/i\u003e\"]\n    end\n\n    Types --\u003e Decode\n    Bits --\u003e Decode\n    Registers --\u003e Execute\n    Memory --\u003e Execute\n    Decode --\u003e Execute\n    Execute --\u003e CPU\n\n    style Types fill:#22c55e,color:#fff\n    style Bits fill:#22c55e,color:#fff\n    style Registers fill:#22c55e,color:#fff\n    style Memory fill:#22c55e,color:#fff\n    style Decode fill:#eab308,color:#000\n    style Execute fill:#6b7280,color:#fff\n    style CPU fill:#6b7280,color:#fff\n```\n\n## Project Structure\n\n```\nrv32emu/\n├── lib/                    # Core library\n│   ├── types.ml           # Fundamental type definitions\n│   ├── bits.ml            # Bit manipulation utilities\n│   ├── registers.ml       # 32-register file (x0 hardwired to zero)\n│   └── memory.ml          # Byte-addressable memory subsystem\n├── bin/                    # CLI executable\n│   └── main.ml            # Command-line interface\n├── test/                   # Test suite (42 tests)\n│   ├── test_bits.ml       # Bit manipulation tests\n│   ├── test_registers.ml  # Register file tests\n│   └── test_memory.ml     # Memory subsystem tests\n└── programs/               # Sample RISC-V programs\n```\n\n## Building\n\n### Prerequisites\n\n- OCaml \u003e= 5.4.0\n- Dune \u003e= 3.20.0\n- RISC-V GNU Toolchain (optional, for compiling test programs)\n\n### Build \u0026 Test\n\n```bash\n# Build the project\ndune build\n\n# Run all tests\ndune runtest\n\n# Run the emulator\ndune exec rv32emu\n```\n\n## Target: RV32I Instruction Set\n\nThe emulator targets all 47 instructions from the RISC-V RV32I base specification:\n\n| Category | Instructions |\n|----------|-------------|\n| **Arithmetic** | ADD, SUB, ADDI, LUI, AUIPC |\n| **Logical** | AND, OR, XOR, ANDI, ORI, XORI |\n| **Shifts** | SLL, SRL, SRA, SLLI, SRLI, SRAI |\n| **Compare** | SLT, SLTU, SLTI, SLTIU |\n| **Load** | LB, LH, LW, LBU, LHU |\n| **Store** | SB, SH, SW |\n| **Branch** | BEQ, BNE, BLT, BGE, BLTU, BGEU |\n| **Jump** | JAL, JALR |\n| **System** | ECALL, EBREAK, FENCE, FENCE.I |\n| **CSR** | CSRRW, CSRRS, CSRRC, CSRRWI, CSRRSI, CSRRCI |\n\n## Design Philosophy\n\n### Type Safety Over Performance\n\nThis emulator prioritizes correctness and clarity over raw performance. OCaml's `int32` type ensures exact 32-bit wraparound semantics, and explicit type aliases (`word`, `address`, `pc`) make the code self-documenting.\n\n### Functional Core, Imperative Shell\n\nWhile the register file and memory use mutable state for efficiency, the instruction decoding is purely functional—pattern matching on algebraic data types produces clean, verifiable code.\n\n### Modular Architecture\n\nEach component (registers, memory, decoder, executor) is independently testable with a clean interface, following OCaml's module system conventions.\n\n## Future Extensions\n\nThe architecture is designed for extensibility to additional RISC-V standard extensions:\n\n| Extension | Description |\n|-----------|-------------|\n| **M** | Integer Multiplication and Division |\n| **A** | Atomic Instructions |\n| **C** | Compressed Instructions (16-bit) |\n| **F** | Single-Precision Floating-Point |\n| **D** | Double-Precision Floating-Point |\n\n### Advanced Features Under Consideration\n\n- **GDB Remote Protocol** — Connect standard debuggers for step-through debugging\n- **Performance Counters** — Cycle-accurate profiling and instruction statistics\n- **Memory-Mapped I/O** — Peripheral device emulation framework\n- **Multi-Hart Support** — Symmetric multiprocessing emulation\n- **JIT Compilation** — Dynamic binary translation for near-native performance\n\n## References\n\n- [RISC-V Unprivileged ISA Specification](https://riscv.org/technical/specifications/)\n- [RISC-V Privileged ISA Specification](https://riscv.org/technical/specifications/)\n- [riscv-tests](https://github.com/riscv/riscv-tests) — Official compliance test suite\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwang-fu%2Frv32emu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhwang-fu%2Frv32emu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwang-fu%2Frv32emu/lists"}