{"id":17500452,"url":"https://github.com/offlinemark/spym","last_synced_at":"2025-03-17T12:30:52.523Z","repository":{"id":31176327,"uuid":"34736778","full_name":"offlinemark/spym","owner":"offlinemark","description":"MIPS ISA toolchain including a (dis)assembler, debugger, and vm.","archived":false,"fork":false,"pushed_at":"2015-09-06T02:57:37.000Z","size":311,"stargazers_count":18,"open_issues_count":6,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-19T22:19:47.610Z","etag":null,"topics":["assembly","binaries","emulator","mips","python"],"latest_commit_sha":null,"homepage":"","language":"Python","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/offlinemark.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":"2015-04-28T14:51:09.000Z","updated_at":"2024-06-27T06:43:18.000Z","dependencies_parsed_at":"2022-09-08T15:22:37.153Z","dependency_job_id":null,"html_url":"https://github.com/offlinemark/spym","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/offlinemark%2Fspym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offlinemark%2Fspym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offlinemark%2Fspym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offlinemark%2Fspym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/offlinemark","download_url":"https://codeload.github.com/offlinemark/spym/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243864609,"owners_count":20360355,"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":["assembly","binaries","emulator","mips","python"],"created_at":"2024-10-19T18:14:09.384Z","updated_at":"2025-03-17T12:30:52.192Z","avatar_url":"https://github.com/offlinemark.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spym\n\nA MIPS ISA toolchain including a (dis)assembler, debugger, and runtime.\n\nThe following utilities are included:\n\n- `spym`: The spym virtual machine, emulating a subset of the MIPS ISA. Capable\n  of executing MIPS assembly source files *and* binaries produced by `spasm`.\n  Includes a basic GDB-style debugger and REPL mode.\n- `spasm`: The spym assembler/linker. Produces SPYM format binaries.\n- `spread`: The spym reader. Displays information about and disassembles SPYM\n  binaries.\n\nFor fun, inside the `linux/` directory resides the source for a kernel module\nthat enables native execution of SPYM binaries on Linux.\n\n\u003e Note: spym does not include a lexer or parser, because they are outside the\n\u003e scope of this learning exercise. Thus, it does not perform any kind of syntax\n\u003e validation and will likely crash if you give it poorly formatted code. You\n\u003e have been warned.\n\n## Building\n\nTo build these utilities as location independent executables, make sure you\nhave `python2.7` and `zip` available, and run\n\n```bash\nmake\n```\n\nThis will create a `bin/` directory with the above three executables.\n\n## Usage\n\n```\n$ ./spym -h\nusage: spym [-h] [--stack STACK] [--debug] [-v] [--assemble] [FILE]\n\nSpym MIPS Interpreter. Starts in interactive shell mode, unless given MIPS\nsource file as argument.\n\npositional arguments:\n  FILE           MIPS source file\n\noptional arguments:\n  -h, --help     show this help message and exit\n  --stack STACK  Stack memory size. Default: 64 bytes\n  --debug        Activate debugger. Implies verbose.\n  -v, --verbose  Verbose output\n\n$ ./spasm -h\nusage: spasm [-h] [-o OUTPUT] FILE\n\nSpym MIPS Assembler. Generates \"spym\" format binaries.\n\npositional arguments:\n  FILE                  MIPS source file\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -o OUTPUT, --output OUTPUT\n                        File to write output to. Default is a.out\n\n$ ./spread -h\nusage: spread [-h] FILE\n\nDisplay information about SPYM format files.\n\npositional arguments:\n  FILE        SPYM binary\n\noptional arguments:\n  -h, --help  show this help message and exit\n```\n\n## Example\n\n```\n$ cat test.s\n# mips factorial calculator\n\n# pseudo-C:\n#\n# int input = 5;\n#\n# main() {\n#     int count = input;\n#     int tmp = 1;\n#\n#     while (count) {\n#         tmp *= count;\n#         count--;\n#     }\n#\n#     print_int(tmp);\n# }\n\n.data\ninput: .word 5\n\n.text\n\nmain:\n    addi $sp, $sp, -8\n    move $t0, $sp  # count\n    addi $t1, $sp, 4  # tmp\n\n    la $s0, input\n    lw $s0, 0($s0)\n\n    sw $s0, 0($t0)\n    li $t3, 1\n    sw $t3, 0($t1)\n\ncond:\n    lw $t3, 0($t0)\n    bne $t3, $zero, body\n    j end\n\nbody:\n    lw $t4, 0($t1)\n    mult $t4, $t3\n    mflo $t5\n    sw $t5, 0($t1)\n    addi $t3, $t3, -1\n    sw $t3, 0($t0)\n    j cond\n\nend:\n    li $v0, 1\n    lw $t2, 0($t1)\n    move $a0, $t2\n    syscall\n$ ./spym.py test.s --stack 8 -v\n=== CPU Start===\n\n[0] addi $sp, $sp, -8\n[1] move $t0, $sp\n[2] addi $t1, $sp, 4\n[3] la $s0, input\n[4] lw $s0, 0($s0)\n[5] sw $s0, 0($t0)\n[6] li $t3, 1\n[7] sw $t3, 0($t1)\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[10] j end\n[18] li $v0, 1\n[19] lw $t2, 0($t1)\n[20] move $a0, $t2\n[21] syscall\n120\n*** pc [22] outside instruction memory ***\n\n=== CPU Dump ===\n\nRegisters\n\n$a0/4 : 120\n$a1/5 : 0\n$a2/6 : 0\n$a3/7 : 0\n$fp/30 : 0\n$gp/28 : 0\n$k0/26 : 0\n$k1/27 : 0\n$ra/31 : 0\n$s0/16 : 5\n$s1/17 : 0\n$s2/18 : 0\n$s3/19 : 0\n$s4/20 : 0\n$s5/21 : 0\n$s6/22 : 0\n$s7/23 : 0\n$sp/29 : 4\n$t0/8 : 4\n$t1/9 : 8\n$t2/10 : 120\n$t3/11 : 0\n$t4/12 : 120\n$t5/13 : 120\n$t6/14 : 0\n$t7/15 : 0\n$t8/24 : 0\n$t9/25 : 0\n$v0/2 : 1\n$v1/3 : 0\n$zero/0 : 0\npc : 22\nhi : 0\nlo : 120\n\nData/Stack Memory\n\n0000: 05000000 00000000  .... ....\n0008: 78000000           x...\n```\n\n## Debug Mode\n\n```\n$ ./spym.py test.s --stack 8 --debug -v\n=== CPU Start===\n\n*** debug mode enabled. '?' for help ***\n\n[0] addi $sp, $sp, -8\n(debug) n\n[1] move $t0, $sp\n(debug)\n[2] addi $t1, $sp, 4\n(debug)\n[3] la $s0, input\n(debug)\n[4] lw $s0, 0($s0)\n(debug)\n[5] sw $s0, 0($t0)\n(debug)\n[6] li $t3, 1\n(debug) p $s0\n5\n(debug) dump\n\n=== CPU Dump ===\n\nRegisters\n\n$a0/4 : 0\n$a1/5 : 0\n$a2/6 : 0\n$a3/7 : 0\n$fp/30 : 0\n$gp/28 : 0\n$k0/26 : 0\n$k1/27 : 0\n$ra/31 : 0\n$s0/16 : 5\n$s1/17 : 0\n$s2/18 : 0\n$s3/19 : 0\n$s4/20 : 0\n$s5/21 : 0\n$s6/22 : 0\n$s7/23 : 0\n$sp/29 : 4\n$t0/8 : 4\n$t1/9 : 8\n$t2/10 : 0\n$t3/11 : 0\n$t4/12 : 0\n$t5/13 : 0\n$t6/14 : 0\n$t7/15 : 0\n$t8/24 : 0\n$t9/25 : 0\n$v0/2 : 0\n$v1/3 : 0\n$zero/0 : 0\npc : 6\nhi : 0\nlo : 0\n\nData/Stack Memory\n\n0000: 05000000 05000000  .... ....\n0008: 00000000           ....\n(debug) c\n[7] sw $t3, 0($t1)\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[11] lw $t4, 0($t1)\n[12] mult $t4, $t3\n[13] mflo $t5\n[14] sw $t5, 0($t1)\n[15] addi $t3, $t3, -1\n[16] sw $t3, 0($t0)\n[17] j cond\n[8] lw $t3, 0($t0)\n[9] bne $t3, $zero, body\n[10] j end\n[18] li $v0, 1\n[19] lw $t2, 0($t1)\n[20] move $a0, $t2\n[21] syscall\n120\n*** pc [22] outside instruction memory ***\n\n=== CPU Dump ===\n\nRegisters\n\n$a0/4 : 120\n$a1/5 : 0\n$a2/6 : 0\n$a3/7 : 0\n$fp/30 : 0\n$gp/28 : 0\n$k0/26 : 0\n$k1/27 : 0\n$ra/31 : 0\n$s0/16 : 5\n$s1/17 : 0\n$s2/18 : 0\n$s3/19 : 0\n$s4/20 : 0\n$s5/21 : 0\n$s6/22 : 0\n$s7/23 : 0\n$sp/29 : 4\n$t0/8 : 4\n$t1/9 : 8\n$t2/10 : 120\n$t3/11 : 0\n$t4/12 : 120\n$t5/13 : 120\n$t6/14 : 0\n$t7/15 : 0\n$t8/24 : 0\n$t9/25 : 0\n$v0/2 : 1\n$v1/3 : 0\n$zero/0 : 0\npc : 22\nhi : 0\nlo : 120\n\nData/Stack Memory\n\n0000: 05000000 00000000  .... ....\n0008: 78000000           x...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofflinemark%2Fspym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fofflinemark%2Fspym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofflinemark%2Fspym/lists"}