{"id":20639222,"url":"https://github.com/alexdremov/spuasm","last_synced_at":"2026-04-17T18:32:41.414Z","repository":{"id":146181954,"uuid":"306007948","full_name":"alexdremov/SPUAsm","owner":"alexdremov","description":"Processor emulator with assembler-type code","archived":false,"fork":false,"pushed_at":"2020-12-11T11:09:06.000Z","size":49569,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-08T04:57:24.696Z","etag":null,"topics":["assembler","assembly","bytecode","bytecode-generation","processor","processor-simulator","spu","translation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexdremov.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":"2020-10-21T11:51:47.000Z","updated_at":"2021-05-21T13:09:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"8460e121-7165-4c28-8e95-9d3ae96e2b68","html_url":"https://github.com/alexdremov/SPUAsm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexdremov/SPUAsm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdremov%2FSPUAsm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdremov%2FSPUAsm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdremov%2FSPUAsm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdremov%2FSPUAsm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexdremov","download_url":"https://codeload.github.com/alexdremov/SPUAsm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexdremov%2FSPUAsm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31940866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["assembler","assembly","bytecode","bytecode-generation","processor","processor-simulator","spu","translation"],"created_at":"2024-11-16T15:23:01.821Z","updated_at":"2026-04-17T18:32:41.397Z","avatar_url":"https://github.com/alexdremov.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Assembly-type code translator and SPU-executor\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/0ef56e0968ad4689a264716b9becbd09)](https://app.codacy.com/gh/AlexRoar/SPUAsm?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=AlexRoar/SPUAsm\u0026utm_campaign=Badge_Grade)\n[![CodeFactor](https://www.codefactor.io/repository/github/alexroar/spuasm/badge)](https://www.codefactor.io/repository/github/alexroar/spuasm)\n\n## Description\nThis project implements code translation to uneven bytecode, disassembly tool for generated bytecode, and bytecode executor (Soft Processor Unit).\n\nIn addition, I implemented code analyser that checks for syntax mistakes. Analyser outputs info in clang format, so most IDEs highlight wrong expressions and provide descriptions of errors as well as possible solutions when possible.\n\n\u003cimg style=\"max-height: 100px\" src=\"https://github.com/AlexRoar/SPUAsm/raw/main/Images/errors.png\"\u003e\n\nDuring the translation, .lst file is generated. It provides information about bytecode generation and what command at what offset is located.\n\n\u003cimg style=\"max-height: 250px\" src=\"https://github.com/AlexRoar/SPUAsm/raw/main/Images/generalview.png\"\u003e\n\n[**Documentation**](https://alexroar.github.io/SPUAsm/html/)\n\n## Installation\n\nEnter project's directory and execute:\n\n```bash\nmkdir build\ncd build\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build .\n```\nThree files will be created: \n-   **SPU**                  - Soft Processor Unit, executes created programs \n-   **SPUAsm**          - translates source file (.spus) to binary file (.spub) that can be executed by SPU\n-   **SPUDisAsm**     - disassembly for generated binary files\n\n## Usage\n\n**SPUAsm**\n```bash\n$ SPUAsm \u003csource file\u003e\n        --input \u003cfilename.spus\u003e     - source file (can be specified without --input)\n        --output \u003cfilename.spub\u003e    - binary assembled file\n        -E                          - generate preprocessed file\n        --verbose                   - output assembly debug information\n        --lst \u003cfilename.lst\u003e        - listing file of generated code (assembly.lst by default) \n        -h, --help                  - show help message\n```\n\n**SPUDisAsm**\n```bash\n$ SPUDisAsm \u003cbinary file\u003e\n        --input \u003cfilename.spub\u003e     - binary assembled file\n        --output \u003cfilename.spus\u003e    - source file (if not specified, stdout selected)\n        --verbose                   - output assembly debug information\n        -h, --help                  - show help message\n```\n\n**SPU**\n```bash\n$ SPU \u003cbinary file\u003e\n        --input \u003cfilename.spub\u003e     - binary assembled file\n        --output \u003cfilename.spus\u003e    - source file (if not specified, stdout selected)\n        --verbose                   - output assembly debug information\n        --vsync                     - render vram after every command\n        -h, --help                  - show help message\n```\n\n## Examples\n\nAll examples are available [in this dir](https://github.com/AlexRoar/SPUAsm/tree/main/Examples/SPUAsm/SPUAsm).\n\n### Squares of first n numbers\n\u003cdetails\u003e\n  \u003csummary\u003eShow code\u003c/summary\u003e\n  \n```asm\n;\n; Squares\n;\n\nin rbx  ; rbx as counter\n\npush 0\npop rax\n\nloop:\ndec rbx  ; decrease counter\n\n; Calculating square\npush rax\npush rax\nmul\nout\n\n; Prepare for the next loop\npop\ninc rax\n\njm mondayOnly ; exit if it is monday\n\n; Insert conditional jump operands\npush 0\npush rbx\n\njne loop\n\nmondayOnly:\n```\n\u003c/details\u003e\n\n### Popping circles\n\n\u003cimg style=\"max-height: 100px\" src=\"https://github.com/AlexRoar/SPUAsm/raw/main/Images/circles.gif\"\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow code\u003c/summary\u003e\n  \n```asm\n; height 32\n; width  64\n\npush 32\npush 16\npush 10\npush 35\ncall drawCircle\n\nclrscr\n\npush 32\npush 16\npush 4\npush 42\ncall drawCircle\n\nclrscr\n\npush 16\npush 8\npush 2\npush 42\ncall drawCircle\n\nclrscr\nrend\n\npush 40\npush 25\npush 4\npush 48\ncall drawCircle\n\nclrscr\nrend\n\npush 60\npush 13\npush 8\npush 48\ncall drawCircle\n\n\nhlt\n\ndrawCircle: ;(x0, y0, r, symbol)\n    pop [2]\n    pop rcx  ; r\n    pop rbx  ; y0\n    pop rax  ; x0\n\n    mov rdx 0   ; initial angle\n    loop:\n        push rbx\n        push rdx\n        sin\n        push rcx\n        mul\n        add ; y0 + r*sin(alpha)\n\n        pop [0] ; y coordinate\n\n        push rax\n        push rdx\n        cos\n        push rcx\n        push 2\n        mul\n        mul\n        add ; x0 + r*cos(alpha)\n\n        pop [1] ; x coordinate\n\n        pixset [1] [0] [2]\n        \n        rend\n        slp 10000\n    ; loop params\n    mov rdx rdx+0.1\n    push rdx\n    push 3.1415926535897\n    push 2\n    mul\n    jbe loop\n    ret\n```\n\u003c/details\u003e\n\n### Square equation solutions\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow code\u003c/summary\u003e\n  \n```asm\n;\n; Data input\n; (a, b, c)\n;\nin      rax\nin      rbx\nin      rcx\n\n;\n; D calculation\n;\npush    rbx\npush    2\npow\n\npush    4\npush    rax\nmul\npush    rcx\nmul\nsub\nsqrt\npop     rdx\n\n\n;\n; First x\n;\nclear\npush    -1\npush    rbx\nmul\npush    rdx\nsub\npush    2\ndiv\npush    rax\ndiv\npop     rcx\n\n;\n; Second x\n;\nclear\npush    -1\npush    rbx\nmul\npush    rdx\nadd\npush    2\ndiv\npush    rax\ndiv\npop     rax\n\n;\n; Output\n;\nout     rax\nout     rcx\n```\n\u003c/details\u003e\n\n## Algorithm description\n\nBinary generation can be splitted into several parts:\n\n- Cleanup\n- Analysis\n- Final cleanup\n- Translation\n- Final checks\n\nIf process fails on any part, the next parts are not executed.\n\n#### Cleanup\nJust double whitespaces, trailing/leading whitespaces removed. Operations that does not change code structure, lines number etc.\n\n#### Analysis\nAnalyses code for syntax errors, builds temporary code to calculate labels offsets. Prints errors descriptions in clang format.\n\n#### Final cleanup\nAll unnecessary indent symbols removed (comments, blank lines, unneded whitespaces). Code structure will be altered, line numbers are not preserved. \n\n#### Translation\nCode is translated using labels table generated on analysis step. At this point, all errors must be catched by analysis, but still some can make thir way to this point. In this case, generation will fail, dumping wrong instruction and its number.\n\n#### Final checks\nCheck that all operations completed correctly; labels table is complete and not redundant.\n\n## Syntax\n\n### Complex value (cvalue)\nOperators with arguments accept *complex value* argument. Argument can be **assignable** or **not assignable**\n\nComplex value examples:\n-  [rax+5]       - assignable, RAM on adress rax+5 with double adressation \n-  4                - not assignable, immediate value 4 \n-  [5]              - assignable, RAM on adress 5 with double adressation \n-  [rcx]           - assignable, RAM on adress rcx with double adressation \n-  rcx             - assignable, register rcx \n-  (rcx)           - assignable, RAM on adress rcx with **char** adressation\n-  (rcx+10)     - assignable, RAM on adress rcx+10 with **char** adressation\n-  (10)            - assignable, RAM on adress 10 with **char** adressation\n\n**Notice:** whitespaces inside complex value are not allowed and considered as syntax error.\n\n### General purpose\n\n#### push \u003cany cvalue\u003e\nPush value to the stack\n\n#### pop \u003cnothing/assignable cvalue\u003e\nPop value from the stack\n-  no args - just delete\n-  cvalue  - pop and save to assignable cvalue\n\n#### in \u003cnothing/assignable cvalue\u003e\nRequest value from the console\n-  no args - push value to the stack\n-  cvalue   - save to assignable cvalue\n\n#### out \u003cnothing/any cvalue\u003e\nPrints value to the console\n-  no args - last stack value\n-  cvalue  - cvalue value\n\n#### mov \u003cassignable cvalue\u003e  \u003cany cvalue\u003e\ndestination -\u003e source\n\nSets the first argument value to the secon argument's value\n\n#### dump\nDump stack information\n\n#### clear\nClear stack\n\n#### rend\nForce render vram\n\n#### slp      \u003cany cvalue\u003e\nSleep for ... nanoseconds\n\n#### hlt\nFinish the program\n\n#### pixelset \u003cany cvalue\u003e \u003cany cvalue\u003e \u003cany cvalue\u003e\nx y value\n\nSet vram pixel (x, y) to value\n\n#### clrscr\nFill vram with spaces\n\n### Math\n\n#### inc \u003cnothing/assignable cvalue\u003e\nIncrements the value\n-  no args - last stack value\n-  cvalue  - cvalue value\n\n#### dec \u003cnothing/assignable cvalue\u003e\nDecrements the value\n-  no args - last stack value\n-  cvalue  - cvalue value\n\n#### add\nAdd two last stack values and push to the stack\n\n#### sub\nSubstract two last stack values and push to the stack\n\n#### mul\nMultiply two last stack values and push to the stack\n\n#### div\nDivide two last stack values and push to the stack\n\n#### sin\nSin of the last stack value\n\n#### cos\nCos of the last stack value\n\n#### abs\nAbs of the last stack value\n\n#### sqrt\nSquare root of the last stack value\n\n#### pow\nThe pre-last element of the stack to the power of the last one\n\n### Codeflow modifiers\n\n#### call \u003clabel\u003e\nGives execution to the label block. Can be returned to the call instruction using *ret*\n\n#### ret\nReturnes to the last call position.\nMay fail if there were no calls.\n\n#### jmp \u003clabel\u003e\nJump to the label\n\n#### jb \u003clabel\u003e\nJump if last element is bigger than pre-last. \nRemoves both operands from the stack\n\n#### jbe \u003clabel\u003e\nJump if last element is bigger-or-equal than pre-last. \nRemoves both operands from the stack\n\n#### je \u003clabel\u003e\nJump if last element is equal to the pre-last one. \nRemoves both operands from the stack\n\n#### jne \u003clabel\u003e\nJump if last element is not equal to the pre-last one. \nRemoves both operands from the stack\n\n#### ja \u003clabel\u003e\nJump if last element is lower than pre-last. \nRemoves both operands from the stack\n\n#### jae \u003clabel\u003e\nJump if last element is lower-or-equal than pre-last. \nRemoves both operands from the stack\n\n#### jm \u003clabel\u003e\nJump if it's Monday. \n\n#### labelName:\nCreates label\n\n\n## Links\n\n- [SPUAsm code](https://github.com/AlexRoar/SPUAsm/blob/main/SoftProcessorUnit/Assembly/SPUAssembly.cpp)\n- [SPUDisAsm code](https://github.com/AlexRoar/SPUAsm/blob/main/SoftProcessorUnit/Disassembly/SPUDisAssembly.cpp)\n- [SPU code](https://github.com/AlexRoar/SPUAsm/blob/main/SoftProcessorUnit/SPU/SPU.cpp)\n- [Examples](https://github.com/AlexRoar/SPUAsm/tree/main/Examples/SPUAsm/SPUAsm)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdremov%2Fspuasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexdremov%2Fspuasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexdremov%2Fspuasm/lists"}