{"id":13937141,"url":"https://github.com/GedRap/xs-vm","last_synced_at":"2025-07-19T23:30:42.517Z","repository":{"id":70293853,"uuid":"37790739","full_name":"GedRap/xs-vm","owner":"GedRap","description":"eXtremely small virtual machine -- for educational purposes :)","archived":false,"fork":false,"pushed_at":"2015-08-18T17:03:37.000Z","size":249,"stargazers_count":156,"open_issues_count":1,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-27T05:32:24.402Z","etag":null,"topics":["python","virtual-machine","virtualization"],"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/GedRap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-21T00:16:38.000Z","updated_at":"2024-10-25T16:06:19.000Z","dependencies_parsed_at":"2023-03-02T18:16:12.393Z","dependency_job_id":null,"html_url":"https://github.com/GedRap/xs-vm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GedRap/xs-vm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GedRap%2Fxs-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GedRap%2Fxs-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GedRap%2Fxs-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GedRap%2Fxs-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GedRap","download_url":"https://codeload.github.com/GedRap/xs-vm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GedRap%2Fxs-vm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266041682,"owners_count":23867944,"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":["python","virtual-machine","virtualization"],"created_at":"2024-08-07T23:03:19.568Z","updated_at":"2025-07-19T23:30:42.215Z","avatar_url":"https://github.com/GedRap.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# xs-vm [![Build Status](https://travis-ci.org/GedRap/xs-vm.svg)](https://travis-ci.org/GedRap/xs-vm)\n## eXtremely Simple Virtual Machine\n\nThe purpose of this project is to implement a simple virtual machine, capable of executing assembly code similar to ARM.\nI will keep it simple (so probably no operation modes, interrupt handling, etc) because I built it for educational\n purposes. Yet, it's powerful enough to do things like recursion (see the [Fibonacci example](https://github.com/GedRap/xs-vm/blob/master/demos/fibonacci.s) ). Why Python? Development speed, as opposed to performance, is the key priority for this project so Python\n fits in perfectly.\n\nIt is distributed under MIT license (see license.txt for the details).\n\nAll Python versions from 2.7 up to 3.4 are supported.\n \n## Installing and running\n \n### Executing code\n\n```\n$ cat demos/function_call.s\nmov r1, #1\nmov r2, #3\nbl func1\nswi #0\n\nfunc1    push lr\n         add r0, r1, r2\n         pop pc\n         \n$ python run.py demos/function_call.s\nInstructions executed: 7\nInstructions executed by type:\n╒═══════════════╤═════════╤═══════════════╤═════════╕\n│ Instruction   │   Count │ Instruction   │   Count │\n╞═══════════════╪═════════╪═══════════════╪═════════╡\n│ swi           │       1 │ bl            │       1 │\n├───────────────┼─────────┼───────────────┼─────────┤\n│ mov           │       2 │ pop           │       1 │\n├───────────────┼─────────┼───────────────┼─────────┤\n│ add           │       1 │ push          │       1 │\n╘═══════════════╧═════════╧═══════════════╧═════════╛\nRegister bank after halting:\n╒═════╤═══╤═════╤══════════╕\n│ r0  │ 4 │ r1  │        1 │\n├─────┼───┼─────┼──────────┤\n│ r2  │ 3 │ r3  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r4  │ 0 │ r5  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r6  │ 0 │ r7  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r8  │ 0 │ r9  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r10 │ 0 │ r11 │        0 │\n├─────┼───┼─────┼──────────┤\n│ r12 │ 0 │ r13 │ 16777215 │\n├─────┼───┼─────┼──────────┤\n│ r14 │ 3 │ r15 │        4 │\n╘═════╧═══╧═════╧══════════╛\n```\n\nUsing `-d` or `--debug` will enable the debugging mode, in which the values of the register bank will be dumped after executing every instruction:\n\n```\n$ python run.py --debug demos/function_call.s\nDebug mode: True\nExecuting mov r1, #1 from 0\nRegister bank after executing the instruction:\n╒═════╤═══╤═════╤══════════╕\n│ r0  │ 0 │ r1  │        1 │\n├─────┼───┼─────┼──────────┤\n│ r2  │ 0 │ r3  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r4  │ 0 │ r5  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r6  │ 0 │ r7  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r8  │ 0 │ r9  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r10 │ 0 │ r11 │        0 │\n├─────┼───┼─────┼──────────┤\n│ r12 │ 0 │ r13 │ 16777215 │\n├─────┼───┼─────┼──────────┤\n│ r14 │ 0 │ r15 │        1 │\n╘═════╧═══╧═════╧══════════╛\nExecuting mov r2, #3 from 1\nRegister bank after executing the instruction:\n╒═════╤═══╤═════╤══════════╕\n│ r0  │ 0 │ r1  │        1 │\n├─────┼───┼─────┼──────────┤\n│ r2  │ 3 │ r3  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r4  │ 0 │ r5  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r6  │ 0 │ r7  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r8  │ 0 │ r9  │        0 │\n├─────┼───┼─────┼──────────┤\n│ r10 │ 0 │ r11 │        0 │\n├─────┼───┼─────┼──────────┤\n│ r12 │ 0 │ r13 │ 16777215 │\n├─────┼───┼─────┼──────────┤\n│ r14 │ 0 │ r15 │        2 │\n╘═════╧═══╧═════╧══════════╛\nExecuting bl func1 from 2\n.......................\n```\n\n### Installing and running tests\n\nJust clone this repository and install the dependencies (`pip install -r requirements.txt`).\n\nYou can run the tests simply by running `nosetests` from the project root directory.\n\n## Architecture\n\nThe VM has 16 registers (R0-R15). Most of the are general purpose, with a few special ones:\n\n* SP (R13). Stack pointer. Points to the last element pushed to the stack (or 0xFFFFFF if nothing has been pushed yet).\n\n* LR (R14). Link register. Holds a return address of the function call.\n\n* PC (R15). Program counter. Holds the address of the instruction in memory which will be executed next.\n\nFor function calls, the result is stored in R0, and R1-R3 are normally used to pass the parameters.\n\n### Supported instructions\n\n| Instruction | Example            | Description                                                                       |\n|-------------|--------------------|-----------------------------------------------------------------------------------|\n| mov         | mov r1, #5         | Move some value (either other register or a constant) to the register.            |\n|             | mov r1, r2         |                                                                                   |\n| add         | add r0, r1, #3     | r0 = r1 + 3                                                                       |\n| sub         | sub r0, r1, #3     | r0 = r1 - 3                                                                       |\n| mul         | mul r0, r1, #4     | r0 = r1 * 4                                                                       |\n| mla         | mla r0, r1, #3, #5 | r0 = r1 * 3 + 5                                                                   |\n| cmp         | cmp r0, r1         | Compare 2 numerical values and store the difference in comparison register (comp_reg = r0 - r1). The value is used later for conditional branching. |\n| b           | b main             | Always branch. Set PC to the instruction to which the given label is pointing to. |\n|             | b 0x001            | Instead of label, memory location can be also passed.                             |\n| beq         | beq main           | Branch if equal, the result of cmp instruction is used.                           |\n| bne         | bne main           | Branch if not equal.                                                              |\n| blt         | blt foo            | Branch if less than (comp_reg \u003c 0).                                               |\n| bgt         | bgt foo            | Branch if greater than (comp_reg \u003e 0).                                            |\n| bl          | bl printf          | Branch and link. Stores PC in LR, equivalent of a function call.                  |\n| nop         | nop                | No OPeration. Do nothing.                                                         |\n| push        | push r0            | Push the value of r0 to the stack.                                                |\n| pop         | pop r1             | Pop the element from the stack and store the value in r1.                         |\n| swi         | swi #0             | Software interrupt. See below.                                                    |\n\n#### Software interrupts\n\nIn xs-vm, software interrupts is a method of communication between the application being executed and the virtual \nmachine executing it.\n\nThe list of supported software interrupts:\n\n| Interrupt | Description                                   |\n|-----------|-----------------------------------------------|\n| swi #0    | Halt. Stop executing the application and quit |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGedRap%2Fxs-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGedRap%2Fxs-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGedRap%2Fxs-vm/lists"}