{"id":13341504,"url":"https://github.com/vresque/esque","last_synced_at":"2025-03-11T21:31:18.441Z","repository":{"id":223109588,"uuid":"432727903","full_name":"vresque/esque","owner":"vresque","description":"A modern microkernel","archived":false,"fork":false,"pushed_at":"2024-02-19T19:52:18.000Z","size":16343,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-10-24T08:31:17.837Z","etag":null,"topics":["bootloader","embedded","kernel","microkernel","operating-system","os","osdev","rust","rust-crate","rust-lang","safe","secure","web-assembly","x86-64"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vresque.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-11-28T14:00:53.000Z","updated_at":"2024-09-28T15:05:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"3e9b5a91-8c3e-45ee-a1c1-b23ce01d76cb","html_url":"https://github.com/vresque/esque","commit_stats":null,"previous_names":["vresque/esque"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vresque%2Fesque","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vresque%2Fesque/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vresque%2Fesque/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vresque%2Fesque/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vresque","download_url":"https://codeload.github.com/vresque/esque/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243115457,"owners_count":20238760,"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":["bootloader","embedded","kernel","microkernel","operating-system","os","osdev","rust","rust-crate","rust-lang","safe","secure","web-assembly","x86-64"],"created_at":"2024-07-29T19:25:28.796Z","updated_at":"2025-03-11T21:31:18.435Z","avatar_url":"https://github.com/vresque.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](binaries/brand/twitter_header_photo_2.png)\r\n\r\n\u003cp align=\"center\"\u003e\r\n    \u003ch1 align=\"center\"\u003eEsque\u003c/h1\u003e\r\n\u003c/p\u003e\r\n\r\n[![If_You_See_This_Tokei_Is_Down_Again](https://tokei.rs/b1/github/visionizer/esque)](https://github.com/visionizer/esque)\r\n[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge\u0026logo=rust\u0026logoColor=white)](https://github.com/visionizer/esque)\r\n[![license](https://img.shields.io/github/license/visionizer/esque?style=for-the-badge)](https://github.com/visionizer/esque)\r\n\r\nA modern exokernel\r\n\r\n\r\n## Building (Using y.py)\r\n\r\n### Esque.toml\r\n\r\nBefore even talking about the hand-written build-system, I need to mention Esque.toml. This is a configuration file with a plethora of options available for customization. Setting this up took a lot of time, which is why it is now the standard for building the Esque OS.\r\n\r\n### Dependencies (On Linux)\r\n- `cargo`\r\n- `rustc`\r\n- `dd`\r\n- `mtools` (mcopy, mmd, ...)\r\n- `dosfstools` (mkfs.vfat)\r\n- `python \u003e= 3`\r\n- `python.toml`\r\n- `python.xbstrap`\r\n\r\n#### Install\r\n```sh\r\n$ sudo apt install cargo rustc binutils mtools dosfstools python3 python3-pip; pip install --user xbstrap toml\r\n```\r\n\r\n### Building (On Linux)\r\n`y.py` is an utility inspired by rustc's `x.py`. You can configure\r\nthe kernel using the `Esque.toml` file that may be found in the sysroot of this directory. This file offers many options, have a look at it before building.\r\n\r\nYou can build the project simply using\r\n```\r\n./y.py build\r\n```\r\nThis system is very configurable. Simply type\r\n```\r\n./y.py --help\r\n```\r\nto see all options.\r\n\r\n### Building (On Windows)\r\n\r\n**First, you must enter `Esque.toml` and change `enable-kvm` to false.**\r\n\r\nBuilding on Windows is not recommended. I am long-time linux user and the entire build process is designed for me, however, building using `winy.ps1`is possible, yet not optimized.\r\n\r\n\r\nOn Windows, only certain `y.py` commands may be executed in the same way as on Linux (Example: `./y.py` build runs `dd` to create an IMG file). Therefore, you are presented with two options\r\n\r\n#### Option A: WSL + Native QEMU\r\nThis may be a preferred option for some. In this scenario, you run *all* commands **except** for `./y.py run` using WSL.\r\n\r\nThis requires all of the dependencies listed above in `Dependencies (On Linux)` section\r\n\r\n##### Pros\r\n- Fast\r\n\r\n##### Cons\r\n- You need to switch terminals each time you want to build and run it\r\n\r\n#### Option B: Using ./winy.ps1\r\n`winy.ps1` is a PowerShell script which decides what to run natively and what not. Usage is equal to `./y.py` e.g. `./winy run` runs the kernel and `./winy build` builds some parts of the kernel using WSL and others natively.\r\n\r\n**_Attention_**\r\nThis requires you to have your ExecutionPolicy to be Bypass. You can temporarily change this by opening a command host with administrator privileges and typing\r\n```ps1\r\nSet-ExecutionPolicy Bypass\r\n```\r\n\r\nThis requires all dependencies listed above *except* for cargo and rustc on WSL. It requires cargo, rustc, and a `tar` binary on on windows. Said dependencies may easily be installed using the rustup binary `rustup.rs`\r\n\r\n###### Installing said dependencies\r\nRun the following command on `WSL` (assumes Ubuntu):\r\n```sh\r\n$ sudo apt install binutils mtools dosfstools python3 python3-pip; pip install --user xbstrap toml\r\n```\r\n\r\n##### Pros\r\n- More user-friendly\r\n\r\n##### Cons\r\n- WSL-Commands have a significant startup time\r\n\r\n## Dependencies\r\n\r\nAn operating system should be close to being dependency free.\r\nUnfortunatley, this system depends on a total of 2 crates:\r\n```\r\nbitflags\r\nspin\r\n```\r\n\r\nOver 10+ of our own dependencies are maintained within the `crates/` subdirectory. These dependencies include a tar loader and much more.\r\n\r\n- Bitflags is used to replace the C bitfields. This is a neccessary dependency. It is used in thousands of projects all over the world. I consider this a completely safe crate.\r\n- Spin is a replacement for Rust's `std::sync::{Mutex,...}`. This is an incredibly helpful crate that is used in nearly all major osdev projects. This crate *might* be dropped in the future.\r\n\r\n## Doesn't rust produce huge binaries?\r\n\r\nWhile it may produce bigger binaries then, let's say, C, it still produces small ones after stripping. The current kernel is just ~300K in size, which is acceptable to me. The bootloader is about 270K big, due to its huge 'uefi' dependency.\r\n\r\n\r\n## Philosophy\r\nEsque is a kernel which seeks to unite aspects of linux and windows, while being an exokernel-like system.\r\nAn exokernel is a kernel which provides just the basic things and any additional things (such as network stacks) are loaded via modules.\r\n\r\n### Linux Compatibility\r\n\r\nDue to the huge availability of software on linux, esque aims to be somewhat compatible with it. It achieves filesystem compatibility due to the use of a `fake-root`. There are two major. The *real root* and the *fake root*. An example of a *fake path* would be `/home/user/` or `/bin/*`. A *real root* path starts with the *device:PATH* scheme. Examples: `initramfs:/myfile`, `C:/Binaries/*`, `B:/BOOT/EFI/BOOTX64.EFI`, `C:/Users/User/`or `proc:/CpuInfo`.\r\n\r\nLinux syscalls are located at their actual location (0, 1, 2, 3, 4...) while esque syscalls are located at (SYS_NUM + 0x1000)\r\n\r\n### Does everything run in Userspace?\r\n\r\nYes - and no. In Esque, there are three different *virtual* 'spaces' for applications. Only two of those are real.\r\nThere is\r\n- Kernel Space (*Only the Kernel* - Has access to the full array of hardware)\r\n- System Space (*Drivers* - *Runs in the Kernel Space of the CPU* Has access to IPC with the kernel and the HAL (Hal = The Hardware Abstraction Layer)\r\n- User Space (*Applications* - Only has access to the system calls)\r\n\r\n\r\n## Contributing\r\n\r\nI understand that not many are willing to use their time on a kernel\r\nsuch as this one. I will still gladly welcome any contribution, no matter how big or small. Please read the [Contributions File](CONTRIBUTING.md) and take a look at the files in the [Documentation Directory](Documentation)\r\n\r\n## The InitRamFs\r\nIn the InitRamFs, as of right now, no directories are supported.\r\nYou can create a new InitRamFs simply by putting files into the `initramfs/` subdirectory.\r\nThen, using `./y.py initramfs` the finished initramfs is going to be found in `build/initramfs.tar`. The bootloader expects this file to be found on the root partition.\r\n\r\nAll files ending with `.system` will then be loaded by the InitRamFs. It is expected that one of said `.system` files loads the FileSystem.\r\n\r\n## About Unsafe\r\nWhile it is true that an operating system without unsafe code is impossible, I tried to limit it in here. At any point, \r\n```\r\n./y.py count-unsafe\r\n```\r\nmay be invoked which will display information about the unsafe-ness of the code.\r\nAt the time of writing, the following output is produced:\r\n```\r\nA total of 52 occurences have been found (1641 LOC, 0.* percent Percent)\r\n```\r\n\r\n\r\n## Roadmap\r\n- [x] Own Bootloader\r\n- [x] Font Loading\r\n- [x] GDT\r\n- [x] IDT\r\n- [x] All Faults Handled\r\n- [x] Port-IO\r\n- [x] Fallback Drivers for Fallback-Shell (For debugging purposes)\r\n- [x] Level 4 Paging\r\n- [x] PS2 Keyboard\r\n- [x] Keyboard Layout Crate\r\n- [x] PS2 Mouse Support\r\n- [x] Memory Allocation\r\n- [x] Load TAR Files\r\n- [x] Support the `alloc` crate\r\n- [x] Remapping the Page Table\r\n- [ ] Syscalls\r\n- [ ] IPC-Messaging\r\n- [ ] PCI Device Descriptors\r\n- [ ] Executables\r\n- [x] Heap\r\n- [x] Load System Space Applications\r\n- [x] Load the InitRamFs\r\n- [ ] MultiTasking\r\n- [ ] Finish the Ext2 driver\r\n- [ ] Release Milestone 1  \r\n- [ ] ACPI\r\n- [ ] RSDP POINTER\r\n- [ ] PCI Bus\r\n- [ ] PCI Enumeration\r\n- [ ] Full PIC Support\r\n- [x] A lot more...\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvresque%2Fesque","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvresque%2Fesque","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvresque%2Fesque/lists"}