{"id":19065504,"url":"https://github.com/menci/pipeline-tester","last_synced_at":"2025-04-28T11:28:41.433Z","repository":{"id":85770037,"uuid":"320448190","full_name":"Menci/pipeline-tester","owner":"Menci","description":"Random tests generator \u0026 runner for your pipelined MIPS processor (from @t123yh)","archived":false,"fork":false,"pushed_at":"2020-12-13T20:43:07.000Z","size":3921,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-18T15:17:29.171Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Menci.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}},"created_at":"2020-12-11T02:44:08.000Z","updated_at":"2023-11-21T10:47:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"42da55ed-7e2f-4d56-bdc6-2cb1bb80f7d7","html_url":"https://github.com/Menci/pipeline-tester","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/Menci%2Fpipeline-tester","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fpipeline-tester/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fpipeline-tester/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Menci%2Fpipeline-tester/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Menci","download_url":"https://codeload.github.com/Menci/pipeline-tester/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251304191,"owners_count":21567834,"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-11-09T00:50:29.134Z","updated_at":"2025-04-28T11:28:41.419Z","avatar_url":"https://github.com/Menci.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pipeline Tester\n\nRandom tests generator \u0026 runner for your pipelined MIPS processor.\n\nOriginally authored by [@t123yh](https://github.com/t123yh). Modified for running with Vivado.\n\n# Requirements\n\nYou need Microsoft .NET SDK to build and run this program.\n\nYou can download and install Microsoft .NET SDK [here](https://dotnet.microsoft.com/download).\n\nYou must have Java (to run Mars) and Vivado installed.\n\nYour MIPS cpu should be a Vivado project.\n\n# Preparation\n\nYou should have a single testbench file in your Vivado project. It should be (replace `TopLevel` with your top level module name, e.g. `mips`):\n\n```verilog\nmodule mips_tb;\n\nreg reset, clock;\n\n// !!! Replace here\nTopLevel topLevel(.reset(reset), .clock(clock));\n\ninteger k;\ninitial begin\n    reset = 1;\n    clock = 0; #1;\n    clock = 1; #1;\n    clock = 0; #1;\n    reset = 0; #1;\n    \n    $stop;\n\n    #1;\n    for (k = 0; k \u003c 5000; k = k + 1) begin\n        clock = 1; #5;\n        clock = 0; #5;\n    end\n\n    $finish;\nend\n    \nendmodule\n```\n\nYou should read instruction memory from `/tmp/code.txt`.\n\n```verilog\ninitial\n    $readmemh(\"/tmp/code.txt\", memory);\n```\n\nSince we check your registers and memory writes. You must `$display` these information when writing registers and memory. The output is like:\n\n```java\n@00003000: $31 \u003c= 00003000\n@00003004: $ 2 \u003c= 00000000\n@00003008: $ 2 \u003c= 00000000\n@0000300c: $ 0 \u003c= 00030000\n@00003010: $ 0 \u003c= 00000000\n@00003014: $ 1 \u003c= 00040000\n@00003018: *00000004 \u003c= 00003000\n@0000301c: $ 1 \u003c= 00006000\n@00003020: *00000008 \u003c= 00003000\n@00003024: $ 1 \u003c= 00003000\n```\n\nYou can add these code snippets to your Verilog code to print that information:\n\n```verilog\n// When writing to data memory (in your `always @ (posedge/negedge clock)` block, after your assign statement to data memory, remember to write `begin ... end`)\n// PC value must be passed from program counter module to data memory module.\n// Address is 32-bit\n$display(\"@%h: *%h \u003c= %h\", programCounter, address, dataWrite);\n\n// When writing to registers (in your `always @ (posedge/negedge clock)` block, after your assign statement to registers, remember to write `begin ... end`)\n// PC value must be passed from program counter module to data memory module.\n$display(\"@%h: $%d \u003c= %h\", programCounter, registerId, dataWrite);\n```\n\nYou must **NOT** `$display` any other lines starting with `@`. Any other lines not starting with `@` is ignored.\n\nThe PC value in your output is ignored when comparing with Mars's since you may NOT saved PC value in every pipeline stage (then you can pass a `0` instead). Printing a PC value may help you debugging. But at least you can see the different line and read PC value in Mars's output.\n\nBefore running tests, you should start simulation in your Vivado IDE and **make sure your code compiles and runs**. I didn't handle compilation errors in tests.\n\n# Usage\n\nClone this repository:\n\n```bash\ngit clone https://github.com/Menci/pipeline-tester\ncd pipeline-tester\n```\n\nYou need to provide your Vivado executable and project to this program.\n\n```bash\ndotnet run \u003cvivado executable path\u003e \u003cproject file path\u003e\n```\n\nFor example:\n\n```bash\ndotnet run ~/Xilinx/Vivado/2019.1/bin/vivado ~/CPU/pipeline/pipeline.xpr\n```\n\n\u003e **Note**: It's **`dotnet run`**, not `docker run`.\n\nIf Vivado successfully loads your project, it will print something like:\n\n```bash\nVivado: ''\nVivado: '****** Vivado v2019.1 (64-bit)'\nVivado: '  **** SW Build 2552052 on Fri May 24 14:47:09 MDT 2019'\nVivado: '  **** IP Build 2548770 on Fri May 24 18:01:18 MDT 2019'\nVivado: '    ** Copyright 1986-2019 Xilinx, Inc. All Rights Reserved.'\nVivado: ''\nVivado: 'open_project /home/Menci/Courses/CPU/pipeline/pipeline.xpr'\nVivado: 'Scanning sources...'\nVivado: 'Finished scanning sources'\n```\n\nAfter starting running tests, it will print something like:\n\n```\nRunning Comprehensive test for P5 #1\nRunning mine\nTotal Valid lines: Mars: 8 vs mine: 48\nTotal Valid lines: Mars: 33 vs mine: 192\nRunning Comprehensive test for P5 (Large) #1\nRunning mine\nTotal Valid lines: Mars: 60 vs mine: 616\nTotal Valid lines: Mars: 418 vs mine: 4153\nRunning Comprehensive test for P5 #2\nRunning mine\nTotal Valid lines: Mars: 44 vs mine: 444\nTotal Valid lines: Mars: 256 vs mine: 2553\nRunning Comprehensive test for P5 (Large) #2\nRunning mine\nTotal Valid lines: Mars: 64 vs mine: 665\nTotal Valid lines: Mars: 385 vs mine: 3754\n```\n\nIf a test fails, it will exit with a error message. You should check the outputs according to the error message, for example, check `mine-registers.txt` and `mars-registers.txt`. The first is the correct registers write operations and the second is what you did.\n\n```bash\nvimdiff mine-registers.txt mars-registers.txt\n# Your wrong operations are on the left side\n# [Type \":wq\" and press enter] twice to exit `vimdiff`\n```\n\nYou may need to check `mars-memory.txt` and `mine-memory.txt` if the error message tells you.\n\nIf your CPU doesn't fail, it will exit after running 100 groups of tests. You may want to let it run continuously:\n\n```bash\nwhile dotnet run \u003cvivado executable path\u003e \u003cproject file path\u003e; do :; done\n```\n\nIf you want to sleep, you may want to let it run even if a test fails to capture as many bugs as possible. You can run this command to let it save failed testcase and result (to a folder named with time in current directory) on failure and restart tests.\n\n```bash\nwhile true; do if ! dotnet run\u003cvivado executable path\u003e \u003cproject file path\u003e; then d=$(date); mkdir \"$d\"; mv *-registers.txt *-memory.txt \"$d\"; fi; done\n```\n\nFor debugging your CPU with failed tests, Mars GUI may be helpful. You can view the instructions near by the instruction you failed and run to see the correct result.\n\n# Customization\n\nBy default it generates instructions below:\n\n```\n* addu, subu\n* ori\n* lw, sw\n* beq\n* lui\n* jr, jal\n```\n\nTo change the instruction set, **uncomment** the `new List`'s arguments in `P5Generator.cs` file.\n\nThere're also **specific instruction tests** in `Program.cs` file, you can uncomment them to test your individual instruction (or group of instructions). But testing individual instruction could NOT guarantee that your pipeline is implemented properly since some data/control hazards only occur on combination of different instructions.\n\n# Known Issue\n\nIt don't generate `lw` with a register other than `$zero` as the base address (no this issue for unaligned loads e.g. `lh`).\n\nVivado has bugs on simulation. Its simulator may crash when running. If you see a test fails and your output lines is less than Mars's lines, it may be:\n\n* Your testbench didn't run for enough cycles. I recommend 5000 if you didn't change the Mars's execuation script (to increase Mars's maximum step).\n* Your CPU is stalled for too long. Or your CPU deadlocked.\n* It's a **Vivado bug**. You can re-run with Vivado GUI. Vivado will tell you if it crashes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmenci%2Fpipeline-tester","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmenci%2Fpipeline-tester","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmenci%2Fpipeline-tester/lists"}