{"id":15646821,"url":"https://github.com/antonlydike/riscemu","last_synced_at":"2025-09-11T10:37:12.364Z","repository":{"id":45437432,"uuid":"358848720","full_name":"AntonLydike/riscemu","owner":"AntonLydike","description":"RISC-V emulator in python ","archived":false,"fork":false,"pushed_at":"2024-07-07T14:04:20.000Z","size":646,"stargazers_count":55,"open_issues_count":9,"forks_count":15,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-13T08:24:50.600Z","etag":null,"topics":["assembly","cli","python3","risc-v"],"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/AntonLydike.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-04-17T10:26:22.000Z","updated_at":"2025-04-11T10:13:02.000Z","dependencies_parsed_at":"2023-11-28T08:25:57.952Z","dependency_job_id":"c50ace75-7e74-4c9c-9e6e-2c4f9bfe1208","html_url":"https://github.com/AntonLydike/riscemu","commit_stats":{"total_commits":269,"total_committers":4,"mean_commits":67.25,"dds":"0.15613382899628248","last_synced_commit":"1b26497e4cd61156532b3bf6f6190a6ccfbcae32"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonLydike%2Friscemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonLydike%2Friscemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonLydike%2Friscemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonLydike%2Friscemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntonLydike","download_url":"https://codeload.github.com/AntonLydike/riscemu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248682170,"owners_count":21144806,"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","cli","python3","risc-v"],"created_at":"2024-10-03T12:15:12.270Z","updated_at":"2025-04-13T08:25:03.706Z","avatar_url":"https://github.com/AntonLydike.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RiscEmu - RISC-V (userspace) emulator in python\n\n[![Documentation Status](https://readthedocs.org/projects/riscemu/badge/?version=latest)](https://riscemu.readthedocs.io/en/latest/?badge=latest)\n\nImplementing a basic RISC-V emulator, aimed at being easily extendable. Check out the docs at [readthedocs](https://riscemu.readthedocs.io/en/latest/index.html)\nor [riscemu.datenvorr.at](https://riscemu.datenvorr.at/index.html).\n\nThis emulator contains:\n* RISC-V Assembly parser\n* RISC-V Assembly loader\n* Emulation for most parts of the basic RISC-V instruction set and the M and A extensions\n* Naive memory emulator\n* Basic implementation of some syscalls\n* A debugging environment\n\n## Installation:\n\n```bash\n$ pip install riscemu\n```\n\n## Running simple Assembly:\nA couple of basic assembly programs are provided inside `examples/`, such as [`hello-world.asm`](examples/hello-world.asm).\n\nYou can run it by typing `python -m riscemu examples/hello-world.asm`. It will produce output similar to:\n```\n[MMU] Successfully loaded: LoadedExecutable[examples/hello-world.asm](base=0x00000100, size=24bytes, sections=data text, run_ptr=0x00000110)\n[CPU] Started running from 0x00000110 (examples/hello-world.asm)\nHello world\n\nProgram exited with code 0\n```\n\nThe [`read` syscall](docs/syscalls.md) defaults to readline behaviour. Reading \"true chunks\" (ignoring newlines) is currently not supported.\n\nSee the docs on [assembly](docs/assembly.md) for more detail on how to write assembly code for this emulator.\nSee the [list of implemented syscalls](docs/syscalls.md) for more details on how to syscall.\n\nCurrently, symbols (such as `main` or `loop`) are looked-up at runtime. This allows for better debugging, I believe.\n\nBasic IO should work, as open, read, write and close are supported for stdin/stdout/stderr and even arbitrary file paths (if enabled)\n\nWhen trying to run an assembly program, the emulator first tries to find a symbol named `_start`, then a symbol named `main`. if both\nsymbols were not found in the file, it simply starts at the beginning of the `.text` segment.\n\n## Using the CLI:\n*Current CLI is not final, options may change frequently until a stable version is reached*\n\nThis is how the interface is used:\n\n```\nusage: riscemu [-h] [--options OPTIONS] [--syscall-opts SYSCALL_OPTS] [--instruction-sets INSTRUCTION_SETS] [--stack_size stack-size] file.asm [file.asm ...]\n\n\n\nOPTIONS and SYSCALL_OPTIONS is a list of comma-separated flags that will be enabled\n\n--options OPTIONS: (-o)\ndisable_debug           Disable the ebreak and sbreak instructions\nno_syscall_symbols      Don't make syscall symbols globally available\nfail_on_ex              Do not launch an interactive debugger when the CPU loop catches an exception\nadd_accept_imm          accept \"add rd, rs, imm\" instructions, even though they are not standard\n\n--syscall-opts SYSCALL_OPTS: (-so)\n                        Options to control syscall behaviour\nfs_access               Allow access to the filesystem\ndisable_io              Disallow reading/writing from stdin/stdout/stderr\n\n--instruction-sets INSTRUCTION_SETS: (-is)\n                        A list of comma separated instruction sets you want to load:\n                        Currently implemented: RV32I, RV32M\n```\n\nIf multiple files are specified, all are loaded into memory, but only the last one is executed. This might be improved\nlater, maybe the `_init` section of each binary is executed before the main loop starts?\n\nIf `stack_size` is greater than zero, a stack is allocated and initialized, with the `sp` register pointing to the end of the stack.\n\n\n## Debugging\nDebugging is done using the `ebreak` (formerly `sbreak`) instruction, which will launch a debugging session if encountered.\nSee [docs/debugging.md](docs/debugging.md) for more info.\n\n![debugging the fibs program](docs/debug-session.png)\n\n\n## The source code:\nCheck out the [documentation](https://riscemu.readthedocs.io/en/latest/riscemu.html).\n\n## Accessing local documentation:\nTo generate your local documentation, first install everything in `sphinx-docs/requirements.txt`. Then run `./generate-docs.sh`, which will\ngenerate and make all doc files for you. Finally, you can open the docs locall by running `open sphinx-docs/build/html/index.html`.\n\n## Resources:\n  * RISC-V Programmers Handbook: https://github.com/riscv-non-isa/riscv-asm-manual/blob/master/riscv-asm.md\n  * Pseudo ops: https://www.codetd.com/article/8981522\n  * detailed instruction definition: https://msyksphinz-self.github.io/riscv-isadoc/html/rvi.html#add\n  * RISC-V reference card: https://www.cl.cam.ac.uk/teaching/1617/ECAD+Arch/files/docs/RISCVGreenCardv8-20151013.pdf\n\n## TODO:\n * Correctly handle 12 and 20 bit immediate (currently not limited to bits at all)\n * Add a cycle limit to the options and CPU to catch infinite loops\n * Move away from `print` and use `logging.logger` instead\n * Writer proper tests\n\n\n## How To Release:\n\nCreate a new commit that:\n1. Changes the \"Upcoming\" heading to the new versions number\n2. Increments the version in the pyproject.toml to the next version\n\nCommit this, and tag it with `v\u003cversion\u003e`. Push the commit and the tag:\n```bash\ngit push\ngit push origin \"v\u003cversion\u003e\"\n```\n\nOn GitHub, [draft a new release](https://github.com/AntonLydike/riscemu/releases/new), and\nthen approve the workflow run [here](https://github.com/AntonLydike/riscemu/actions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonlydike%2Friscemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonlydike%2Friscemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonlydike%2Friscemu/lists"}