{"id":14992162,"url":"https://github.com/bendudson/EuraliOS","last_synced_at":"2025-09-25T14:30:59.520Z","repository":{"id":63601517,"uuid":"493921871","full_name":"bendudson/EuraliOS","owner":"bendudson","description":"A hobby x86-64 operating system written in Rust","archived":false,"fork":false,"pushed_at":"2024-07-26T05:29:28.000Z","size":1830,"stargazers_count":136,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-03T17:37:48.200Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bendudson.png","metadata":{"files":{"readme":"README.org","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":"2022-05-19T04:39:16.000Z","updated_at":"2025-03-18T17:58:54.000Z","dependencies_parsed_at":"2024-07-26T05:48:35.667Z","dependency_job_id":"850cbefc-aaf3-48f5-a67e-1cbf7d28e942","html_url":"https://github.com/bendudson/EuraliOS","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bendudson/EuraliOS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendudson%2FEuraliOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendudson%2FEuraliOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendudson%2FEuraliOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendudson%2FEuraliOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bendudson","download_url":"https://codeload.github.com/bendudson/EuraliOS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendudson%2FEuraliOS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276932091,"owners_count":25730722,"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","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-09-24T15:00:49.940Z","updated_at":"2025-09-25T14:30:59.041Z","avatar_url":"https://github.com/bendudson.png","language":"Rust","readme":"* EuraliOS\n\nA hobby x86-64 operating system written in [[http://rust-lang.org][Rust]]. Named for Euralia in\nA.A. Milne's [[https://en.wikipedia.org/wiki/Once_on_a_Time][Once on a Time]] because I don't know who this is intended\nfor except, to borrow Milne's introduction, \"For those, young or old,\nwho like the things which I like...  Either you will enjoy it, or you\nwon't. It is that sort of +book+ project.\"\n\n#+CAPTION: EuraliOS demonstration\n#+NAME: fig-demo\n[[./doc/euralios.gif]]\n\n*Disclaimer*: This was written by someone who doesn't (or didn't) know\nanything about Rust or operating systems. The result is probably not\nidiomatic Rust or a sensible OS design. If you are looking for a\nusable operating system implemented in Rust then [[https://www.redox-os.org/][Redox OS]] is probably\nwhat you want.\n\nThis started with [[https://os.phil-opp.com/][Philipp Oppermann's amazing blog]] on OS development\nwith Rust (second edition), and makes use of many of the crates that\nPhil maintains (e.g. [[https://docs.rs/x86_64/latest/x86_64/][x86_64]] and [[https://docs.rs/bootloader/latest/bootloader/][bootloader]]). That blog has inspired\nmany other operating system siblings that I've found useful to study\nincluding [[https://github.com/WartaPoirier-corp/ananos][ananos]], the [[https://github.com/sos-os/kernel][Stupid Operating System]], [[https://github.com/intermezzOS][intermezzOS]], and\nespecially [[https://github.com/vinc/moros][MOROS the Obscure Rust Operating System]]. The [[https://github.com/redox-os/kernel][Redox OS\nkernel]] is very readable, and [[https://github.com/betrusted-io/xous-core][Xous]] has a similar focus on message\npassing (This is a more comprehensive [[https://github.com/flosse/rust-os-comparison][comparison of Rust operating\nsystems]]).  Anything useful here was probably borrowed from one of\nthese projects; mistakes and omissions are my own.\n\n** Features\n\nThere are many different directions to explore in building an OS, and\nwith EuraliOS I've focussed mainly on memory management and\npre-emptive multitasking so far. The result is an OS that can't do\nmuch, but it can do it all at the same time.\n\n- The \"Merriwig\" kernel\n  - [X] Pre-emptive multitasking of user and kernel threads, with a round-robin scheduler\n  - [X] Program memory isolation using paging\n  - [X] On-demand memory allocation using page fault handler\n  - [X] Stack and heap memory management\n  - [X] Frame allocator based on a bitmap tree structure\n  - [X] ELF loader using the [[https://crates.io/crates/object][object crate]]\n  - [X] Rendezvous message passing for all inter-process communication.\n        Messages can contain communication handles or transfer ownership of memory regions\n        between processes and threads.\n  - [X] 18 syscalls for memory and process/thread control and inter-process communication\n  - [X] A [[https://man7.org/linux/man-pages/man7/vdso.7.html][vDSO]]-like fast mechanism for access to timing information from user programs\n  - [X] Virtual file systems that can be shared between processes or per-process\n        as a mechanism for capability-based security and user isolation\n\n- Drivers as userspace programs (Ring 3)\n  - [X] Keyboard driver using the [[https://docs.rs/pc-keyboard/latest/pc_keyboard/][pc-keyboard]] crate\n  - [X] Virtual consoles and VGA text output using the [[https://crates.io/crates/vga][vga crate]]\n  - [X] RTL8139 network card driver\n  - [X] TCP network stack using [[https://docs.rs/smoltcp/latest/smoltcp/][smoltcp]] in user space, with DHCP and DNS\n  - [ ] Virtio network driver\n\n- User programs\n  - [X] Login process and multiple users\n  - [X] A basic shell\n  - [X] A simple [[https://en.wikipedia.org/wiki/Gopher_(protocol)][Gopher]] browser\n  - [X] A RAM disk for temporary files\n  - [X] A text editor\n  - [ ] Virtio 9P to access host filesystems\n\nThere is no disk driver yet, so user programs are compiled and then\nthe ELF files are included in the =init= binary using Rust's\n[[https://doc.rust-lang.org/std/macro.include_bytes.html][include_bytes]] macro (another idea taken from [[https://github.com/vinc/moros][MOROS]]).\n\n** Building and running\n\nEuralios depends on the [[https://github.com/rust-osdev/vga][vga]] crate, with some modifications in [[https://github.com/bendudson/vga/tree/euralios][a branch\nhere]] as a git submodule.  Either clone with submodules (with e.g the\n=--recurse-submodules= option) or run:\n#+begin_src bash\n  $ git submodule update --init --recursive\n#+end_src\n\nAfter setting up Rust, Cargo and QEMU (see [[https://os.phil-opp.com/minimal-rust-kernel/][phil-opp blog]]), running\n#+begin_src bash\n  $ make run\n#+end_src\nshould download dependencies, build everything, and launch qemu.\n\n*Notes*\n\n1. You'll probably need to use the Rust nightly build. EuraliOS was\n   originally developed using Rustc =1.61-nightly (6a7055661 2022-02-27)= and\n   is known to work with =1.79.0-nightly (7f2fc33da 2024-04-22)=.\n2. Rust needs to build =core= and =compiler_builtins= libraries for\n   the =x86_64-euralios= target. To do that cargo needs the rust source code,\n   which can be installed by running =rustup component add rust-src=.\n\n** Documentation\n\nI've tried to document the steps to build EuraliOS, starting from the\nend of [[https://os.phil-opp.com/heap-allocation/][post 10 (heap allocation)]] of Phil Opp's blog (2nd Ed). At that\npoint the kernel had a heap and a bump frame allocator (so could\nallocate but not free memory), some code to handle pages,\nexceptions, and VGA output. [[https://os.phil-opp.com/async-await/][Post 11]] went on to add Async/Await\ncooperative multitasking, but here we go in a slightly different\ndirection...\n\n- [[file:doc/journal/01-interrupts-processes.org][1. Interrupts and processes]] in which kernel multi-threading is\n  introduced by modifying the timer interrupt handler to capture and\n  change the context (registers etc).\n- [[file:doc/journal/02-userspace.org][2. Userspace]] in which a program is loaded into memory and run in\n  Ring 3 (user space). Syscall/sysret is used to implement a simple\n  way to print from user programs.\n- [[file:doc/journal/03-memory.org][3. Memory management]] in which we create separate page tables for\n  user processes and stacks for each thread.\n- [[file:doc/journal/04-more-syscalls.org][4. Syscalls for thread control]] which adds syscalls to spawn new\n  threads and to exit from a thread. We also learn how to use the\n  [[https://www.felixcloutier.com/x86/swapgs][swapgs]] and [[https://www.felixcloutier.com/x86/wrmsr][wrmsr]] instructions to switch stacks inside syscalls.\n- [[file:doc/journal/05-memory-returns.org][5. Memory returns]] which implements a better frame allocator that\n  can keep track of available frames, so that memory can be freed when\n  threads and processes exit.\n- [[file:doc/journal/06-user-memory.org][6. User space memory management]] in which we create a heap for each\n  user process so that user programs can use =Box=, =Vec= etc, using a\n  linked list allocator. As a bonus this allows a threading API with\n  closures as in the Rust stdlib. We also re-organise the repository\n  into a Cargo Workspace, with separate crates for the kernel and user\n  program.\n- [[file:doc/journal/07-ipc.org][7. Inter-process communication (IPC)]] where a simple \"[[https://en.wikipedia.org/wiki/Rendezvous_(Plan_9)][rendezvous]]\"\n  communication method is implemented, enabling a user program to\n  get input from the keyboard.\n- [[file:doc/journal/08-faster-ipc.org][8. Faster IPC]] in which we switch tasks in syscalls and keyboard\n  interrupt handler, to minimise delays in the communication.\n- [[file:doc/journal/09-message-sending.org][9. Sending messages]] which adds the =send= syscall, allowing the user\n  program to send messages to a VGA output kernel thread.\n- [[file:doc/journal/10-stdlib.org][10. A standard library]] in which we start a =euralios_std= \"standard\"\n  library, moving code out of the user program into a separate crate.\n- [[file:doc/journal/11-messages.org][11. More messages]]\n- [[file:doc/journal/12-devices.org][12. PCI devices]] where we start working on input/output to PCI\n  devices and discovering which devices are available.\n- [[file:doc/journal/13-return-to-sender.org][13. Return to sender]] where we add the =send_receive= syscall to make\n  remote procedure calls more reliable, and start to develop a Virtual\n  File System (VFS) with a new =open= syscall.\n- [[file:doc/journal/14-network.org][14. RTL8139 network card]] where we develop a basic driver for the\n  [[https://wiki.osdev.org/RTL8139][RTL8139]] card, adapting [[https://github.com/vinc/moros/blob/trunk/src/sys/net/rtl8139.rs][the MOROS driver]]. In the process we wrap the\n  =send_receive= system call into an =rcall= remote procedure call,\n  and add frame allocation of consecutive physical frames for direct\n  memory access.\n- [[file:doc/journal/15-messages.org][15. Message error handling]] where we add error handling and send retries to\n  make messaging more robust. We also add a =thread_yield= system call\n  to yield control of the processor when waiting and recovering from errors.\n- [[file:doc/journal/16-arp.org][16. Address Resolution Protocol]] implementation: Writing a simple program\n  to send and receive an ARP packet through the network.\n- [[file:doc/journal/17-tcp-stack.org][17. TCP stack]] where the [[https://docs.rs/smoltcp/latest/smoltcp/][smoltcp]] crate is used to provide a TCP stack\n  in user-space which communicates with the network card driver by\n  messaging.\n- [[file:doc/journal/18-gopher.org][18. Gopher]]: Developing a simple Gopher protocol browser, and in the\n  process improving the Virtual File System (VFS) to handle more\n  complicated OPEN messages, and the TCP program to READ and WRITE\n  sockets.\n- [[./doc/journal/19-timing.org][19. Timing]]: Adding functions to get time since system start. To\n  speed up access to timer calibration data we map a page read-only\n  into every user program, as the [[https://man7.org/linux/man-pages/man7/vdso.7.html][Linux virtual dynamic shared object\n  (vDSO)]] does.\n- [[./doc/journal/20-dns.org][20. Domain Name System (DNS)]], adding the ability to look up IP addresses\n  from host names.\n- [[./doc/journal/21-vga.org][21. VGA driver and terminals]] in user space, using the [[https://crates.io/crates/vga][vga\n  crate]]. Allows separate consoles for system programs and user\n  programs like the Gopher browser.\n- [[./doc/journal/22-ramdisk.org][22. RAMdisk driver]] to store files and develop the filesystem API,\n  starting a basic interactive shell able to list files and run\n  programs.\n- [[./doc/journal/23-keyboard.org][23. Interrupts and a better keyboard]]: Enabling user programs to receive\n  hardware interrupts, and moving the keyboard driver out of the kernel\n  into a user-space driver.\n- [[./doc/journal/24-directories.org][24. Directories]] to hierarchically organise files\n- [[./doc/journal/25-multiple-users.org][25. Multiple users]] and login process, using separate virtual file systems\n  to control user capabilities\n- [[./doc/journal/26-servers.org][26. Servers]], generalising the RAMdisk server code\n- [[./doc/journal/27-text-editor.org][27. Text editor]]. Writing a text editor to run on EuraliOS.\n\n\n** Notes\n\n- [[./doc/journal/xx-shell.org][A shell]]\n- [[./doc/journal/xx-usb.org][USB]] (xHCI)\n- [[./doc/journal/xx-wifi.org][WiFi]]\n\n** Bibliography\n\nUseful reference material includes:\n\n- [[https://wiki.osdev.org/Expanded_Main_Page][The OSDev.org wiki]]\n- [[https://www.amd.com/system/files/TechDocs/24593.pdf][AMD64 Architecture Programmer's Manual (Vol 2: System programming)]]\n- [[https://0xax.gitbooks.io/linux-insides/content/][Linux insides]] by [[https://twitter.com/0xAX][@0xAX]]\n- [[https://www.kernel.org/doc/html/latest/][The Linux Kernel documentation]]\n\nOther relevant links\n\n- [[https://osblog.stephenmarz.com/index.html][The Adventures of OS: Making a RISC-V Operating System using Rust]]\n- [[https://github.com/nuta/resea][The resea micro-kernel based OS]] written in C\n- [[https://github.com/nuta/kerla/][The kerla monolithic kernel]] written in Rust\n- [[https://github.com/thepowersgang/rust_os][The \"Tifflin\" kernel]] written in Rust\n- [[https://github.com/IsaacWoods/poplar][Poplar]] operating system in Rust\n\n","funding_links":[],"categories":["General Operating System"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbendudson%2FEuraliOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbendudson%2FEuraliOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbendudson%2FEuraliOS/lists"}