{"id":39355578,"url":"https://github.com/sshwy/y86-pipe-rs","last_synced_at":"2026-01-18T02:36:53.769Z","repository":{"id":208476314,"uuid":"721729075","full_name":"sshwy/y86-pipe-rs","owner":"sshwy","description":"Y86 Pipeline Simulator Rust Implementation, employed in PKU's ICS 2024 archlab","archived":false,"fork":false,"pushed_at":"2025-04-09T03:55:41.000Z","size":3348,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T04:28:27.636Z","etag":null,"topics":["archlab","assembly","csapp","debugger","isa","macros","pipeline","risc-v","rust","y86"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/sshwy.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":"2023-11-21T16:50:01.000Z","updated_at":"2025-04-09T03:55:45.000Z","dependencies_parsed_at":"2024-09-15T03:43:11.385Z","dependency_job_id":"7f3fe6d9-f7ea-4ff8-a1ca-7f329bfcc029","html_url":"https://github.com/sshwy/y86-pipe-rs","commit_stats":null,"previous_names":["sshwy/y86-pipe-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sshwy/y86-pipe-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshwy%2Fy86-pipe-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshwy%2Fy86-pipe-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshwy%2Fy86-pipe-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshwy%2Fy86-pipe-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshwy","download_url":"https://codeload.github.com/sshwy/y86-pipe-rs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshwy%2Fy86-pipe-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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":["archlab","assembly","csapp","debugger","isa","macros","pipeline","risc-v","rust","y86"],"created_at":"2026-01-18T02:36:53.695Z","updated_at":"2026-01-18T02:36:53.757Z","avatar_url":"https://github.com/sshwy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# y86-pipe-rs: Y86-64 Processor Simulator written in Rust\n\nThis document describes the processor simulators that accompany the presentation of the Y86-64 processor architectures in Chapter 4 of _Computer Systems: A Programmer’s Perspective, Third Edition_.\n\nThe original (official) simulator, written in C has difficulty adapting to too many modifications on the seq, seq+ and pipe HCL, leading to a limited range of lab assignments. This project aims to provide a more flexible and extensible simulator for the Y86-64 processor, and is employed in Peking U's _ICS: Introduction to Computer System_ in 2024.\n\n## Installation\n\nThis project is written in Rust, so you'd have your Rust toolchain installed. If you haven't, please execute the following command to install [rustup](https://rustup.rs/):\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\nYou can verify the installation by executing the command `rustup`.\n\nInstall and the Rust toolchain by executing the following command (by the time of writing, the latest stable version is 1.86):\n\n```bash\nrustup install 1.86\nrustup default 1.86\n```\n\n## Build the Project\n\nSimply execute `cargo build` to build all the binaries in the project. After running this command, a folder named `target` will be created to store the output binaries and other intermediate files. The output executables are\n\n- `target/debug/yas`: Y86-64 Assembler\n- `target/debug/yis`: Y86-64 ISA Simulator\n- `target/debug/ysim`: Y86-64 Pipline Simulator\n- `target/debug/ydb`: Y86-64 Debugger Server\n\nTo build the release version, execute `cargo build --release`. The release version is optimized for performance. The released version executables locate in the `target/release` folder (`target/release/{yas,yis,ysim,ydb}`).\n\n## Assembler Usage\n\nTo assemble a Y86-64 assembly file, execute the following command:\n\n```bash\n./target/debug/yas [input_file].ys\n```\n\nThe default output filename is `[input_file].yo`. You can specify the output filename by adding the `-o` option. For example, given the following y86 assembly file `swap.ys`:\n\n```asm\n# Swap nums if the former one \u003e= the latter one\n    .pos 0\n    irmovq stack, %rsp\n\n    irmovq nums, %rdi\n    mrmovq (%rdi), %rdx\n    mrmovq 8(%rdi), %rcx\n    rrmovq %rdx, %rbp\n    subq %rcx, %rbp # $rbp \u003c= $rcx ?\n    # if so, then do not swap\n    jle done\n    rmmovq %rdx, 8(%rdi)\n    rmmovq %rcx, (%rdi)\ndone:\n    halt\n    nop\n    nop\n    nop\n\n    .align 8\nnums:\n    .quad 0xcba\n    .quad 0xbca\n    \n    .pos 0x200\nstack:\n```\n\nBy running `./target/debug/yas swap.ys`, the assembler will generate a binary file `swap.yo`:\n\n```asm\n                             | # Swap nums if the former one \u003e= the latter one\n0x0000:                      |     .pos 0\n0x0000: 30f40002000000000000 |     irmovq stack, %rsp\n                             | \n0x000a: 30f75000000000000000 |     irmovq nums, %rdi\n0x0014: 50270000000000000000 |     mrmovq (%rdi), %rdx\n0x001e: 50170800000000000000 |     mrmovq 8(%rdi), %rcx\n0x0028: 2025                 |     rrmovq %rdx, %rbp\n0x002a: 6115                 |     subq %rcx, %rbp # $rbp \u003c= $rcx ?\n                             |     # if so, then do not swap\n0x002c: 714900000000000000   |     jle done\n0x0035: 40270800000000000000 |     rmmovq %rdx, 8(%rdi)\n0x003f: 40170000000000000000 |     rmmovq %rcx, (%rdi)\n0x0049:                      | done:\n0x0049: 00                   |     halt\n0x004a: 10                   |     nop\n0x004b: 10                   |     nop\n0x004c: 10                   |     nop\n                             | \n0x0050:                      |     .align 8\n0x0050:                      | nums:\n0x0050: ba0c000000000000     |     .quad 0xcba\n0x0058: ca0b000000000000     |     .quad 0xbca\n                             |     \n0x0200:                      |     .pos 0x200\n0x0200:                      | stack:\n                             | \n```\n\n## ISA Simulator Usage\n\nTo simulate a Y86-64 assembly file w.r.t. the Y86 ISA specification, you can execute the following command:\n\n```bash\n./target/debug/yis [input_file].yo\n```\n\nFor example, by running `./target/debug/yis swap.yo`, the simulator will print the following information:\n\n```text\n0x0000  icode: 0x3 (IRMOVQ), ifun: 0, rA: RNONE, rB: RSP, V: 0x200\n0x000a  icode: 0x3 (IRMOVQ), ifun: 0, rA: RNONE, rB: RDI, V: 0x50\n0x0014  icode: 0x5 (MRMOVQ), ifun: 0, rA: RDX, rB: RDI\n0x001e  icode: 0x5 (MRMOVQ), ifun: 0, rA: RCX, rB: RDI\n0x0028  icode: 0x2 (CMOVX), ifun: 0, rA: RDX, rB: RBP\n0x002a  icode: 0x6 (OPQ), ifun: 1, rA: RCX, rB: RBP\n0x002c  icode: 0x7 (JX), ifun: 1, V: 0x49\n0x0035  icode: 0x4 (RMMOVQ), ifun: 0, rA: RDX, rB: RDI\n0x003f  icode: 0x4 (RMMOVQ), ifun: 0, rA: RCX, rB: RDI\n0x0049  icode: 0x0 (HALT), ifun: 0\n\ntotal instructions: 10\nax 0000000000000000 bx 0000000000000000 cx 0000000000000bca dx 0000000000000cba\nsi 0000000000000000 di 0000000000000050 sp 0000000000000200 bp 00000000000000f0\n0x0050: ba0c000000000000 -\u003e ca0b000000000000\n0x0058: ca0b000000000000 -\u003e ba0c000000000000\n```\n\n## Pipeline Simulator Usage\n\nTo simulate a Y86-64 assembly file over the default architecture (`seq_std`), execute the following command:\n\n```bash\n./target/debug/ysim [input_file].ys\n```\n\nThis will print the state of the processor at each cycle to the standard output. If you want to read tht output from start to end, you can pipe a `less` command to the output (To quit `less`, press `q`):\n\n```bash\n./target/debug/ysim [input_file].ys | less\n```\n\nTo print more information you can use the `-v` option, which will display the value of each signal in each stage of the cycle:\n\n```bash\n./target/debug/ysim [input_file].ys -v\n```\n\nWe provide different architectures for the simulator. To view available architectures, you can run\n\n```bash\n./target/debug/ysim --help\n```\n\nTo specify an architecture, you can use the `--arch` option. For example, to run the simulator with the `seq_plus_std` architecture, you can run:\n\n```bash\n./target/debug/ysim [input_file].ys --arch seq_plus_std\n```\n\nYou can also inspect an architecture via `-I` option:\n\n```bash\n./target/debug/ysim --arch seq_plus_std -I\n```\n\nIts output will be like:\n\n```text\npropagate order:\nlv.1: pc\nlv.2: imem align icode ifun instr_valid mem_read mem_write need_regids need_valC set_cc alufun\nlv.3: ialign pc_inc dstM srcA srcB valC valP\nlv.4: reg_read aluA mem_data aluB\nlv.5: alu valE mem_addr\nlv.6: reg_cc dmem cc valM stat prog_term\nlv.7: cond cnd dstE\nlv.8: reg_write\ndependency graph visualization is generated at: seq_plus_std_dependency_graph.html\n```\n\nHere an HTML file is generated to visualize the dependency graph of the architecture. You can open the HTML file in a browser to view the dependency graph. In the graph, blue blocks are hardware components, and red blocks are signals. You can drag each block to change its position.\n\n![visualization](assets/visualization-screenshot.png)\n\n## Debugger Usage\n\nTo provide a friendly coding experience, we develop a debugger server for the Y86 assembly language. This debugger server is used along with the `y86-debugger` VSCode extension.\n\nFirst you should install `y86-debugger` extension from `assets/y86-debugger-0.2.0.vsix` (choose \"Install from VSIX...\"). To install the extension on SSH remote servers, you can first install it on your local machine, then open a remote host VSCode window and choose \"Install in SSH:...\" to install the extension on the remote server.\n\nThen you should start the debugger server:\n\n```bash\n./target/debug/ydb -p 2345 # -p specifies the port number\n```\n\nAfter that you can start debugging in VSCode. You can set breakpoints, step through the code, and inspect the registers and memory. Click the debug icon at the right side of the menu bar to start debugging.\n\nBy default, your assembly file is simulated with the `seq_std` architecture. If you want to change the architecture, you may use the `--arch` option:\n\n```bash\n# specify another architecture to debug\n# both builtin and extra architectures are supported\n./target/debug/ydb -p 2345 --arch seq_plus_std\n```\n\nRefer to [y86-debugger](https://github.com/sshwy/y86-debugger) for more information.\n\n![debugger](assets/debugger-screenshot.png)\n\n## HCL-rs Specification\n\nPlease refer to this [attachment](assets/hcl-rs.pdf) for detailed description of the HCL-rs syntax.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshwy%2Fy86-pipe-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshwy%2Fy86-pipe-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshwy%2Fy86-pipe-rs/lists"}