{"id":22140060,"url":"https://github.com/thepuzzlemaker/river","last_synced_at":"2026-03-06T01:01:24.860Z","repository":{"id":62970933,"uuid":"499992560","full_name":"ThePuzzlemaker/river","owner":"ThePuzzlemaker","description":"A very WIP RISCV64 OS written in Rust to learn about low-level and OS development. Read-only mirror from sr.ht","archived":false,"fork":false,"pushed_at":"2024-01-27T00:05:16.000Z","size":685,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-26T03:48:16.753Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sr.ht/~thepuzzlemaker/river","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThePuzzlemaker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES","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":"2022-06-05T03:40:58.000Z","updated_at":"2024-01-26T22:39:23.000Z","dependencies_parsed_at":"2024-12-01T20:38:06.765Z","dependency_job_id":null,"html_url":"https://github.com/ThePuzzlemaker/river","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ThePuzzlemaker/river","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePuzzlemaker%2Friver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePuzzlemaker%2Friver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePuzzlemaker%2Friver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePuzzlemaker%2Friver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThePuzzlemaker","download_url":"https://codeload.github.com/ThePuzzlemaker/river/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePuzzlemaker%2Friver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30156842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"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":[],"created_at":"2024-12-01T20:26:19.168Z","updated_at":"2026-03-06T01:01:24.837Z","avatar_url":"https://github.com/ThePuzzlemaker.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# river\n\nRiver is an experimental capability-based operating system written in\nRust for RISCV64. (For those wondering, the name is taken from RISC-V:\n\"**RI**sc**V**\" + \"**ER**\"). This project is not intended to be used\nin production, but instead just as a project for learning about\nadvanced OS concepts and existing kernels.\n\nRiver takes inspiration from [repnop][1]'s [Vanadinite][2], the\n[seL4][3] project, [GWU Composite][4] (which has some [very helpful\naccompanying lectures][5]), [Fucshia/Zircon][6], and\n[XV6/RISC-V][7]. Thanks goes to all the amazing people who have helped\nme through my insanity as I try to figure this stuff out.\n\n[1]: https://github.com/repnop\n[2]: https://github.com/repnop/vanadinite\n[3]: https://seL4.systems\n[4]: https://github.com/gwsystems/composite\n[5]: https://www.youtube.com/watch?v=a8V2d33KvaE\u0026list=PLVW70f0xtTUwPxQXXcQBZJps-7n8BclOc\n[6]: https://fuchsia.dev/fuchsia-src/concepts/kernel\n[7]: https://github.com/mit-pdos/xv6-riscv\n\n## Rille\n\nRille is to River as `libc` is to Linux. It's a somewhat opinionated\ninterface library with some additional helpful primitives for building\napplications. For more information, you can see the [module's\ndocumentation](rille/src/lib.rs).\n\nFor those wondering, the name derives from the river-like structures\nfound on the moon (and other celestial bodies) called rilles.\n\n## Building\n\nFirst, ensure submodules are cloned. Then, use `cargo xtask build` to\nbuild. See the help options, or see\n[`xtask/src/main.rs`](xtask/src/main.rs) for help or more info.\n\n### Tips for debugging (especially before paging is enabled)\n\nThe [`.gdbinit`](.gdbinit) provided on this repository works very well\nfor pre-paging debugging.  It requires\n[gef](https://github.com/hugsy/gef) to be installed at\n`~/.gdbinit-gef.py`. If you're going to debug userspace programs, set\na breakpoint at the start of the user program. Just note that it'll\nstep right into the kernel if you let it, so you may want to set a\nbreakpoint at the end of the trampoline (`river::trap::user_ret`). For\ndebugging the kernel after paging, it helps to break at `kmain`,\ncontinue, then set a breakpoint at your desired position.\n\nUse the wrapper script [`run-debug.sh`](run-debug.sh), as it will\nlaunch QEMU and connect GDB to it.\n\nHere's a quick rundown of some of my custom commands, only for\ndebugging pre-paging code (after that, you can use typical\ncommands--and even have the luxury of stack frames and panics):\n- `addrof \u003csymbol\u003e` gives the physical kernel address of the symbol\n  provided\n- `set-break` is required to set a breakpoint to a symbol before\n  paging is enabled\n- `symof` gets the symbol name of a physical kernel address\n- `lst` lists around the current physical kernel address\n- `p2v` converts a physical kernel address to a virtual one (that can\n  be used to look up addresses with `addr2line` and `info addr` \u0026 co.)\n- `v2p` converts a virtual kernel address to a physical one (that can\n  be used to examine memory with `x/...` when given a virtual address)\n- `until_ret` is like `finish`, but just goes until the next `ret`\n- `until_ret_ni` is `until_ret` then an `ni`\n- `sio` steps over the next instruction (it does this by setting a\n  breakpoint, disabling other breakpoints, and continuing, then\n  reenabling other breakpoints), do note that it may re-enable\n  breakpoints you had previously disabled, I have not checked the code\n  completely as it was copied from StackOverflow (developer moment)\n\nVirtual kernel addresses start with `0xFFFFFFD0` or higher, whereas\nphysical kernel addresses start with `0x802`.\n\nOnce paging is enabled, you can generally use the addresses that GDB\ngives you. It's recommended, if you're debugging something after\npaging is enabled, which will be the case in most of the time, to do\n`break kmain`, then continue until `kmain`. This is the only\nbreakpoint I've been able to set starting with a stopped QEMU, and\nonce you get to it, you should be able to set any other breakpoint as\nthe addresses will be correctly resolved in GDB's mind.\n\nAdditionally to virtual kernel addresses, there are 64GiB of virtual\ndirect-mapped (i.e. contiguous pages) addresses starting at\n`0xFFFF_FFC0_0000_0000` mapped to `0x0` (physical memory) and ending\nat `0xFFFF_FFCF_C000_0000`, mapped to `0x10_0000_0000` (physical\nmemory).\n\nThis can be helpful to know if you just need to probe or poke and prod\nat a specific address, as it will always be readable and writable.\n\n(I'll probably add a command to help with converting direct-mapped\naddresses in the `.gdbinit` at some point.)\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0 ([LICENSES](LICENSES) or\n   http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSES](LICENSES) or\n   http://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the\nApache-2.0 license, shall be dual licensed as above, without any\nadditional terms or conditions.\n\nSome files, explicitly marked with a header, are licensed individually\nunder [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/). This is\nbecause they have a large portion of code taken from\n[vanadinite](https://github.com/repnop/vanadinite), licensed under\nthese terms. Any contribution to these marked files will be licensed\nunder these terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepuzzlemaker%2Friver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthepuzzlemaker%2Friver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthepuzzlemaker%2Friver/lists"}