{"id":13672567,"url":"https://github.com/djanderson/riscv-5stage-simulator","last_synced_at":"2025-04-27T22:32:23.799Z","repository":{"id":40508517,"uuid":"107747543","full_name":"djanderson/riscv-5stage-simulator","owner":"djanderson","description":"A 5-stage pipelining RISC-V 32I simulator written in Rust.","archived":false,"fork":false,"pushed_at":"2021-04-21T22:50:01.000Z","size":1081,"stargazers_count":19,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-11T10:42:33.301Z","etag":null,"topics":["isa","pipelining","risc-v","rust","simulator"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djanderson.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}},"created_at":"2017-10-21T03:15:26.000Z","updated_at":"2023-09-03T23:33:10.000Z","dependencies_parsed_at":"2022-09-11T09:01:47.027Z","dependency_job_id":null,"html_url":"https://github.com/djanderson/riscv-5stage-simulator","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/djanderson%2Friscv-5stage-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djanderson%2Friscv-5stage-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djanderson%2Friscv-5stage-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djanderson%2Friscv-5stage-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djanderson","download_url":"https://codeload.github.com/djanderson/riscv-5stage-simulator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219601,"owners_count":21554444,"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":["isa","pipelining","risc-v","rust","simulator"],"created_at":"2024-08-02T09:01:39.571Z","updated_at":"2025-04-27T22:32:23.292Z","avatar_url":"https://github.com/djanderson.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# RISC-V 5-Stage Pipeline Simulator [![Rustdoc Build Status][docs-badge]][docs-link]\n\n  [docs-link]: https://djanderson.github.io/riscv-5stage-simulator\n  [docs-badge]: https://img.shields.io/badge/docs-available-brightgreen.svg\n  \nRISC-V 5-Stage Pipeline Simulator is a 32-bit integer instruction\nset architecture (ISA) and pipelining RISC-V simulator written in\nRust. The simulator is based on the design in the book Computer\nOrganization and Design RISC-V Edition by Patterson and Hennessy.\n\n\n## Quickstart\n\n### General usage:\n\n 1) Follow instructions at [rustup.rs](https://rustup.rs/) to install Rust stable for your platform.\n 2) Run all tests: `cargo test`\n 3) Run a specific test: `cargo test ca_simulator_riscv_32i_sorting`\n 4) Run the CA simulator against a disassembly file:\n\n    ```bash\n    $ cargo run tests/riscv_32i_sorting_disassembly.txt\n       Compiling riscv-5stage-simulator v0.1.0 (file:///[...]/git/riscv-5stage-simulator)\n        Finished dev [unoptimized + debuginfo] target(s) in 0.66 secs\n         Running `target/debug/casim tests/riscv_32i_sorting_disassembly.txt`\n\n    RISC-V 5-Stage Simulator\n\n                  vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv\n                      vvvvvvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrr       vvvvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrrrrr      vvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrrrrrrr    vvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrrrrrrr    vvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrrrrrrr    vvvvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrrrrr      vvvvvvvvvvvvvvvvvvvvvv\n    rrrrrrrrrrrrr       vvvvvvvvvvvvvvvvvvvvvv\n    rr                vvvvvvvvvvvvvvvvvvvvvv\n    rr            vvvvvvvvvvvvvvvvvvvvvvvv      rr\n    rrrr      vvvvvvvvvvvvvvvvvvvvvvvvvv      rrrr\n    rrrrrr      vvvvvvvvvvvvvvvvvvvvvv      rrrrrr\n    rrrrrrrr      vvvvvvvvvvvvvvvvvv      rrrrrrrr\n    rrrrrrrrrr      vvvvvvvvvvvvvv      rrrrrrrrrr\n    rrrrrrrrrrrr      vvvvvvvvvv      rrrrrrrrrrrr\n    rrrrrrrrrrrrrr      vvvvvv      rrrrrrrrrrrrrr\n    rrrrrrrrrrrrrrrr      vv      rrrrrrrrrrrrrrrr\n    rrrrrrrrrrrrrrrrrr          rrrrrrrrrrrrrrrrrr\n    rrrrrrrrrrrrrrrrrrrr      rrrrrrrrrrrrrrrrrrrr\n    rrrrrrrrrrrrrrrrrrrrrr  rrrrrrrrrrrrrrrrrrrrrr\n\n\n    Caught HALT instruction at 0xd8, exiting...\n    ```\n\n### Debugging a test\n\n 1) Run the test and note the name of the executable\n\n    ```bash\n    $ cargo test ca_simulator_riscv_32i_sorting\n    ...\n         Running target/debug/deps/riscv_32i_disassembly-a87e2e4f7ca5fb9b\n\n    running 1 test\n    test test_ca_simulator_riscv_32i_sorting_disassembly ... ok\n    ...\n    ```\n\n 2) Run with different log levels (warn, info, debug, trace)\n\n    ```bash\n    $ RUST_LOG=trace ./target/debug/riscv_32i_disassembly-a87e2e4f7ca5fb9b ca_simulator_riscv_32i_sorting 2\u0026\u003e trace.out\n    $ head trace.out\n\n    running 1 test\n    TRACE:riscv_5stage_simulator::pipeline::stages: Hazard: rs1 = 11960320 forwarded from EX/MEM ALU result (clock 3)\n    TRACE:riscv_5stage_simulator::stages: Writeback: x[6] = 11960320 (clock 4)\n    TRACE:riscv_5stage_simulator::pipeline::stages: Hazard: rs1 = 28672 forwarded from EX/MEM ALU result (clock 5)\n    TRACE:riscv_5stage_simulator::pipeline::stages: Hazard: rs2 = 2920, forwarded from previous ALU result (clock 5)\n    TRACE:riscv_5stage_simulator::stages: Writeback: x[6] = 2920 (clock 5)\n    TRACE:riscv_5stage_simulator::stages: Writeback: x[2] = 28672 (clock 6)\n    TRACE:riscv_5stage_simulator::pipeline::stages: Jump: 0x10 -\u003e 0x48 (clock 7)\n    TRACE:riscv_5stage_simulator::stages: Writeback: x[2] = 31592 (clock 7)\n    $ ll -h trace.out\n    -rw-rw-r-- 1 dja dja 36M Dec  4 00:31 trace.out\n    ```\n 3) Attach GDB\n\n    ```bash\n    $ ./scripts/enable_integration_test_debugging.sh\n    Created the following files:\n    ./target/debug/tests/riscv_32i_disassembly_1.txt\n    ./target/debug/tests/riscv_32i_disassembly_2.txt\n    ./target/debug/tests/riscv_32i_sorting_disassembly.txt\n    $ rust-gdb ./target/debug/riscv_32i_disassembly-a87e2e4f7ca5fb9b\n    [...]\n    Reading symbols from ./target/debug/riscv_32i_disassembly-a87e2e4f7ca5fb9b...done.\n    (gdb) tbreak riscv_5stage_simulator::ca_simulator::run\n    Temporary breakpoint 1 at 0x3ace1: file src/ca_simulator.rs, line 19.\n    (gdb) run ca_simulator_riscv_32i_sorting\n    Starting program: /home/dja/git/riscv-5stage-simulator/target/debug/riscv_32i_disassembly-a87e2e4f7ca5fb9b ca_simulator_riscv_32i_sorting\n    [Thread debugging using libthread_db enabled]\n    Using host libthread_db library \"/lib/x86_64-linux-gnu/libthread_db.so.1\".\n\n    running 1 test\n    [New Thread 0x7ffff69ff700 (LWP 6149)]\n    [Switching to Thread 0x7ffff69ff700 (LWP 6149)]\n\n    Thread 2 \"test_ca_simulat\" hit Temporary breakpoint 1, riscv_5stage_simulator::ca_simulator::run (\n        insns=\u0026InstructionMemory, mem=0x7ffff69fe430, reg=0x7ffff69fe440) at src/ca_simulator.rs:19\n    19      insns: \u0026InstructionMemory,\n    (gdb) n\n    20      mut mem: \u0026mut DataMemory,\n    (gdb)\n    21      mut reg: \u0026mut RegisterFile,\n    (gdb)\n    24      let mut clock: u64 = 0;\n    (gdb)\n    27      let mut write_pipeline = Pipeline::new();\n    (gdb) watch clock == 12345\n    Hardware watchpoint 2: clock == 12345\n    (gdb) c\n    Continuing.\n\n    Thread 2 \"test_ca_simulat\" hit Hardware watchpoint 2: clock == 12345\n\n    Old value = false\n    New value = true\n    riscv_5stage_simulator::ca_simulator::run (insns=\u0026InstructionMemory, mem=0x7ffff69fe430,\n        reg=0x7ffff69fe440) at src/ca_simulator.rs:30\n    ...\n    ```\n\n\n## Implemented Execution Models\n\n - [X] IA (instruction accurate), single cycle simulator\n - [X] CA (cycle accurate), 5-stage pipelining simulator\n\n\n## Implemented Hazard Detection and Forwarding\n\n - [X] EX/MEM data hazard detection and ALU result forwarding\n - [X] MEM/WB data hazard detection and data memory/previous result forwarding\n - [X] Register write/read hazard detection and forwarding\n - [X] Load-use hazard detection and pipeline stall insertion\n\n\n## Tests\n\nCurrently, integration tests are loaded via a disassembly loader that parses a\ngiven disassembly file and populates the instruction memory. The loader adds a\nspecial `HALT` instruction at the end, and the simulator returns the address of\nthe first `HALT` instruction that it hits. Integration tests pass or fail based\non this address. The following integration tests are passing for both IA and CA\nsimulators:\n\n - [X] RISCV_32I_DISASSEMBLY_1\n - [X] RISCV_32I_DISASSEMBLY_2\n - [X] RISCV_32I_SORTING_DISASSEMBLY\n\nIn addition, there are ~30 unit tests within implementation files that test\nmore specific features.\n\n\n## Implemented Instructions\n\nRV32I Base Instruction Set, Version 2.0 (as defined in Volume 1: RISC-V\nUser-Level ISA V2.2)\n\n - [X] LUI\n - [X] AUIPC\n - [X] JAL\n - [X] JALR\n\nBranches\n\n - [X] BEQ\n - [X] BNE\n - [X] BLT\n - [X] BGE\n - [X] BLTU\n - [X] BGEU\n\nLoads\n\n - [X] LB\n - [X] LH\n - [X] LW\n - [X] LBU\n - [X] LHU\n\nStores\n\n - [X] SB\n - [X] SH\n - [X] SW\n\nOperations on immediates\n\n - [X] ADDI\n - [X] SLTI\n - [X] SLTIU\n - [X] XORI\n - [X] ORI\n - [X] ANDI\n - [X] SLLI\n - [X] SRLI\n - [X] SRAI\n\nOperations on registers\n\n - [X] ADD\n - [X] SUB\n - [X] SLL\n - [X] SLT\n - [X] SLTU\n - [X] XOR\n - [X] SRL\n - [X] SRA\n - [X] OR\n - [X] AND\n - [X] HALT\n\nControl and status registers\n\n - [ ] FENCE\n - [ ] FENCE.I\n - [ ] ECALL\n - [ ] EBREAK\n - [ ] CSRRW\n - [ ] CSRRS\n - [ ] CSRRC\n - [ ] CSRRWI\n - [ ] CSRRSI\n - [ ] CSRRCI\n\n\n## Licence\n\nCopyright 2017 Douglas Anderson \u003cdouglas.anderson-1@colorado.edu\u003e. Released\nunder GPL 3 _except for the 3 disassembly files in tests/ which are copyright\ntheir respective authors and not covered under this license._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjanderson%2Friscv-5stage-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjanderson%2Friscv-5stage-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjanderson%2Friscv-5stage-simulator/lists"}