{"id":17680748,"url":"https://github.com/kcreate/stackvm","last_synced_at":"2025-10-23T22:27:15.734Z","repository":{"id":54266251,"uuid":"80375800","full_name":"KCreate/stackvm","owner":"KCreate","description":"Virtual Machine with a 240x160 VRAM display.","archived":false,"fork":false,"pushed_at":"2020-03-23T23:07:22.000Z","size":4707,"stargazers_count":48,"open_issues_count":3,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-07T13:07:23.605Z","etag":null,"topics":["assembler","assembly","compiler","debugger","virtual-machine","vram"],"latest_commit_sha":null,"homepage":"","language":"Crystal","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/KCreate.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-01-29T22:01:33.000Z","updated_at":"2025-03-27T12:38:52.000Z","dependencies_parsed_at":"2022-08-13T10:30:44.043Z","dependency_job_id":null,"html_url":"https://github.com/KCreate/stackvm","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/KCreate%2Fstackvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCreate%2Fstackvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCreate%2Fstackvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KCreate%2Fstackvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KCreate","download_url":"https://codeload.github.com/KCreate/stackvm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252883204,"owners_count":21819160,"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":["assembler","assembly","compiler","debugger","virtual-machine","vram"],"created_at":"2024-10-24T09:08:45.961Z","updated_at":"2025-10-23T22:27:15.638Z","avatar_url":"https://github.com/KCreate.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StackVM\n\nThis is my try at writing a virtual machine from scratch. There are four main design documents\nwhich describe the machine's functionality and how the binary format should look like.\n\n- [Semantic](./design/semantic.md)\n- [Encoding](./design/encoding.md)\n- [Execution](./design/execution.md)\n- [Assembly](./design/assembly.md)\n\nThis repository contains the machine itself, an assembler, a debugger and a virtual display. The machine puts it's main memory section into a memory-mapped file in the current directory where the process was started. The virtual display can load this file and will display the designated VRAM section of the machine's memory as a live video feed.\n\n# Installation\n\nThis installation is written for macOS 10.12.4. You should however be easily able to adapt it to whatever system you're using. It also assumes you already have [homebrew](https://brew.sh/index_de.html) installed on your system.\n\n```bash\nbrew install crystal-lang\nbrew install sdl2\ngit clone https://github.com/KCreate/stackvm.git\ncrystal deps\nmake stackvm\n```\n\nYou will now have the compiled executable at `bin/stackvm` relative to the projects root directory.\n\n# Usage\n\n```\n$ bin/stackvm help\nUsage: asm [command]\n\nCommands:\n    run                 run a file\n    build               assemble a file\n    monitor             start the virtual monitor\n    version             show version\n    help                show this help\n```\n\n## Assemble a file\n\n```bash\n$ touch myfile.asm\n$ vim myfile.asm\n$ bin/stackvm build myfile.asm -o myfile.bc --stats\n```\n\nThe `--stats` option will show you some statistics about the binary you just created. It includes the offsets of each label, the load table which get's embedded in the final executable, the entry address and the size of the file.\n\n```bash\n$ bin/stackvm build examples/boxes.asm -s\nBuilt: out.bc 332 bytes\nEntry Address: 0x00000000\nOffset Table: 12 entries\n  0x00000000: setup, entry_addr\n  0x00000068: main\n  0x00000085: check_zero_reached1\n  0x00000092: check_zero_reached2\n  0x0000009f: loop\n  0x000000af: br1\n  0x000000bb: br2\n  0x000000c0: quit_program\n  0x000000ce: msg_welcome\n  0x000000eb: msg_sleep\n  0x00000105: gfx_draw_pixel\n\nLoad Table: 1 entries\n  Offset      Size        Address\n  0x00000000  0x00000134  0x00000000\n```\n\n## Run a file\n\n```bash\n$ bin/stackvm run myfile.bc\n```\n\n### Using the debugger\n\nStackVM has a built-in debugger you can use to debug (no shit sherlock) your programs. You launch it by normally running the `run` command but this time with the `-d` or `--debugger` option.\n\n```\n$ bin/stackvm run test.bc --debugger\n[0x0:0x007a1200:0x00000000]\u003e help\nDebugger help page\n\nh, help                            show this page\nq, quit                            quit the debugger\ns, stack                           print a hexdump of the stack\nr, registers                       print the contents of all registers\nc, cycle        n                  run *n* cpu cycles (default 1)\nj, jump         adr                jumps to *adr*\nm, memory       start, count       print *count* bytes starting at *start*\ni, instruction                     print the current instruction\nstatus                             print machine status information\ndrain                              run the machine in normal mode\n[0x0:0x007a1200:0x00000000]\u003e r\nR0:    0x0000000000000000 R1:    0x0000000000000000 R2:    0x0000000000000000\nR3:    0x0000000000000000 R4:    0x0000000000000000 R5:    0x0000000000000000\nR6:    0x0000000000000000 R7:    0x0000000000000000 R8:    0x0000000000000000\nR9:    0x0000000000000000 R10:   0x0000000000000000 R11:   0x0000000000000000\nR12:   0x0000000000000000 R13:   0x0000000000000000 R14:   0x0000000000000000\nR15:   0x0000000000000000 R16:   0x0000000000000000 R17:   0x0000000000000000\nR18:   0x0000000000000000 R19:   0x0000000000000000 R20:   0x0000000000000000\nR21:   0x0000000000000000 R22:   0x0000000000000000 R23:   0x0000000000000000\nR24:   0x0000000000000000 R25:   0x0000000000000000 R26:   0x0000000000000000\nR27:   0x0000000000000000 R28:   0x0000000000000000 R29:   0x0000000000000000\nR30:   0x0000000000000000 R31:   0x0000000000000000 R32:   0x0000000000000000\nR33:   0x0000000000000000 R34:   0x0000000000000000 R35:   0x0000000000000000\nR36:   0x0000000000000000 R37:   0x0000000000000000 R38:   0x0000000000000000\nR39:   0x0000000000000000 R40:   0x0000000000000000 R41:   0x0000000000000000\nR42:   0x0000000000000000 R43:   0x0000000000000000 R44:   0x0000000000000000\nR45:   0x0000000000000000 R46:   0x0000000000000000 R47:   0x0000000000000000\nR48:   0x0000000000000000 R49:   0x0000000000000000 R50:   0x0000000000000000\nR51:   0x0000000000000000 R52:   0x0000000000000000 R53:   0x0000000000000000\nR54:   0x0000000000000000 R55:   0x0000000000000000 R56:   0x0000000000000000\nR57:   0x0000000000000000 R58:   0x0000000000000000 R59:   0x0000000000000000\n\nIP:    0x0000000000000000 SP:    0x0000000000400000 FP:    0x00000000007a1200\nFLAGS: 0x0000000000000000\n[0x0:0x007a1200:0x00000000]\u003e\n```\n\n## Using the virtual monitor\n\nPrograms which access the machine's VRAM section are able to drive a virtual display. This display is included in the vm itself and requires SDL 2 to be installed.\n\nA good example of the display is the `examples/vram.asm` file, which iterates over each pixel in the display and increments it's value by one.\n\n```bash\n$ bin/stackvm build examples/vram.asm -o vram.bc\n\n# Run these two commands at the same time (e.g Each in a separate shell)\n$ bin/stackvm run vram.bc\n$ bin/stackvm monitor machine.memory -s 3\n```\n\n# Virtual Display\n\n![Virtual Display](./design/images/virtual-display.gif)\n\n# Debugger\n\n![Debugger](./design/images/debugger.png)\n\n# Assembler\n\n![Assembler](./design/images/assembler.png)\n\n## Contributing\n\n1. Fork it ( https://github.com/KCreate/stackvm/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [KCreate](https://github.com/KCreate) Leonard Schuetz - creator, maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcreate%2Fstackvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkcreate%2Fstackvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcreate%2Fstackvm/lists"}