{"id":27139501,"url":"https://github.com/ddrcode/riscv-os","last_synced_at":"2026-02-27T13:41:49.857Z","repository":{"id":271288379,"uuid":"905184342","full_name":"ddrcode/riscv-os","owner":"ddrcode","description":"Tiny OS in RISC-V assembly (32-bit)","archived":false,"fork":false,"pushed_at":"2025-02-23T18:47:06.000Z","size":805,"stargazers_count":3,"open_issues_count":30,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T19:35:26.301Z","etag":null,"topics":["baremetal","operating-system","risc-v","risc-v-assembly"],"latest_commit_sha":null,"homepage":"","language":"Assembly","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/ddrcode.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":"2024-12-18T10:24:20.000Z","updated_at":"2025-02-20T18:51:46.000Z","dependencies_parsed_at":"2025-01-06T20:22:54.927Z","dependency_job_id":"6db20602-0cbd-43c3-ace8-46188f39bfdf","html_url":"https://github.com/ddrcode/riscv-os","commit_stats":null,"previous_names":["ddrcode/riscv-os"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrcode%2Friscv-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrcode%2Friscv-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrcode%2Friscv-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddrcode%2Friscv-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddrcode","download_url":"https://codeload.github.com/ddrcode/riscv-os/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247779700,"owners_count":20994573,"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":["baremetal","operating-system","risc-v","risc-v-assembly"],"created_at":"2025-04-08T04:58:24.765Z","updated_at":"2026-02-27T13:41:44.803Z","avatar_url":"https://github.com/ddrcode.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# riscv-os\nRISCV-OS is a tiny OS for 32-bit RISC-V platform implemented entirely in assembly\n(although applications for the system can be implemented in other languages).\n\nCurrently, the OS runs on [virt](https://www.qemu.org/docs/master/system/riscv/virt.html)\nand [SiFive](https://www.qemu.org/docs/master/system/riscv/sifive_u.html)\nmachines under QEMU.\nIt uses very minimalistic configuration of hardware: 4MB of RAM and 1 core.\nIt's also minimalistic in terms of RISC-V instruction set, as it only utilizes the E, M\nand Zicsr extensions.\n\n## Features\n\n\u003c!-- \u003cimg src=\"./screenshots/screen-recording.gif\" /\u003e --\u003e\n![recording](./screenshots/riscv-os.gif)\n\n\nThe OS has riched the MVP state, that means it is complete enough that it allows for loadaing\nand running external programs. It's still in the early stage of development, though, \nand currently conceptually is closer to C64's\n[Kernal](https://en.wikipedia.org/wiki/KERNAL) rather than Linux or any RTOS.\n\n### Implemented features\n\n- framebuffer (80x25 characters text screen, configurable),\n- trivial shell \n- drivers for UART, RTC and PLIC\n- driver/hardware abstraction layer (HAL)\n- keyboard input (UART, interrupts)\n- [system functions](https://github.com/ddrcode/riscv-os/wiki/System-functions) callable via `ecall`\n- interrupt/exception handlers\n- User Mode (for running shell and programs) and Machine Mode (for the system)\n- standard library containing simple string, math and file functions\n- fallbacks for missing M-extension\n- trivial, read-only file system\n- external programs (implemented in Assembly, C and Rust), loadable to the system\n- unicode support (including wide characters)\n\n### Planned features\n\n- system events\n- supervisor mode (currently everything executes in either user or machine mode)\n- dynamic memory / heap\n- running on physical devices \n\n## Building and dependencies\n\nI strongly recommend using [nix](https://nixos.org/download/#download-nix) for handling this project, as it configures all the necessary dependencies.\nIn such case just enter the project's folder and type `nix-shell`, or - if you use\n[nix direnv](https://github.com/nix-community/nix-direnv) - `direnv allow`.\nOtherwise you would need to manually install binutils and QEMU for RISC-V. \n\nTo have a full experience of the system try these:\n```bash\ncd apps\nmake clean disc\ncd ..\nmake run MACHINE=virt OUTPUT_DEV=5 DRIVE=apps/disc.tar\n```\n\nMost important Makefile options:\n- `make run` - runs the system in QEMU (see notes below on building apps disc image)\n- `make run TEST_NAME=math64` - runs a specific test and outputs results to stdout\n- `make debug TEST_NAME=math64` - loads test to QEMU and waits for connection from GDB\n- `make gdb TEST_NAME=math64` - connects GDB with QEMU\n\nTo have fully-functional system, you should run it with a disc image containing the apps.\nTo build it, just `cd` the apps folder and run `make disc`. Then start QEMU with the following command\n(from system repo, not the `apps` folder):\n\n```\nmake run DRIVE=apps/disc.tar\n```\n\nOptionally each command can be provided with `MACHINE` attribute, i.e.\n`make run start MACHINE=sifive_u`. Currently, the available machines are\n`virt` (default), `sifive_u` and `sifive_e` (no drive support on the last one).\n\n### Output options\n\nThe system can be compiled with extra `OUTPUT_DEV` option, that defines how it\nproduces the output, i.e:\n\n```make run OUTPUT_DEV=5```\n\nWhere the options are:\n- `1` - outputs to framebuffer only (can be inspected with GDB)\n- `2` - outputs to serial console\n- `3` - both: framebuffer and the console. In this mode the framebuffer content can be\n        dumped to the serial output with `fbdump` program\n- `5` - it emulates text screen of the system with terminal's action codes\n\n## Credits\nThe initial setup and linker file were inspired by\n[chuckb/riscv-helloworld](https://github.com/chuckb/riscv-helloworld) project\n\n## References\nThis is clearly a learning project, so I used a number of sources and\nreferences that helped me to learn the subject. Here are the key ones:\n\n- [Project F - FPGA \u0026 RISC-V Tutorials](https://projectf.io/posts/) -\n  a collection of great, deep posts by Will Green on various aspects\n  of RISC-V assembly programming. It includes a\n  [cheat sheet](https://projectf.io/posts/riscv-cheat-sheet/) that I use frequently\n- [An Introduction to Assembly Programming with RISC-V](https://riscv-programming.org/book/riscv-book.html) -\n  very helpful free book by Prof. Edson Borin\n- [RISC-V from scratch](https://twilco.github.io/riscv-from-scratch/2019/04/27/riscv-from-scratch-2.html) -\n  Tyler Wilcock post on hardware layouts, linker, etc - very detailed!\n  Other posts on RISC-V worth checking too.\n- [Using as - the GNU Assembler](http://microelectronics.esa.int/erc32/doc/as.pdf) -\n  a book by Dean Elsner, Jay Fenlason \u0026 friends\n- [RISC Assembler Reference](https://michaeljclark.github.io/asm.html) -\n  a very handy list of assembler directives by Michael Clark\n- [Generic Virtual Platform (virt)](https://www.qemu.org/docs/master/system/riscv/virt.html) -\n  A documentation of qemu's virt platform that I use for testing\n- [RISC-V Options (for gcc)](https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Options.html) -\n  very handy list of options for compilation/building. Also, quite clear documentation of\n  RISC-V extensions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddrcode%2Friscv-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddrcode%2Friscv-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddrcode%2Friscv-os/lists"}