{"id":18791790,"url":"https://github.com/phip1611/phipsboot","last_synced_at":"2025-07-29T18:05:04.724Z","repository":{"id":178235787,"uuid":"661366440","full_name":"phip1611/phipsboot","owner":"phip1611","description":"PhipsBoot is a relocatable x86_64 bootloader for legacy boot written in Rust and assembly.","archived":false,"fork":false,"pushed_at":"2025-03-02T12:07:23.000Z","size":183,"stargazers_count":11,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T14:41:51.244Z","etag":null,"topics":["kernel","multiboot","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phip1611.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"phip1611"}},"created_at":"2023-07-02T16:09:21.000Z","updated_at":"2025-03-02T12:07:27.000Z","dependencies_parsed_at":"2025-03-02T13:20:01.980Z","dependency_job_id":null,"html_url":"https://github.com/phip1611/phipsboot","commit_stats":null,"previous_names":["phip1611/relocatable-multiboot2-chain-loader","phip1611/phipsboot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/phip1611/phipsboot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phip1611%2Fphipsboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phip1611%2Fphipsboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phip1611%2Fphipsboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phip1611%2Fphipsboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phip1611","download_url":"https://codeload.github.com/phip1611/phipsboot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phip1611%2Fphipsboot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267729716,"owners_count":24135374,"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-07-29T02:00:12.549Z","response_time":2574,"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":["kernel","multiboot","x86-64"],"created_at":"2024-11-07T21:16:52.691Z","updated_at":"2025-07-29T18:05:04.687Z","avatar_url":"https://github.com/phip1611.png","language":"Rust","funding_links":["https://github.com/sponsors/phip1611"],"categories":[],"sub_categories":[],"readme":"# PhipsBoot\n\n⚠️ Work in progress. This is more proof-of-concept than production-ready. ⚠️\n\nDisclaimer: _This project combines a lot of toolchain and binary knowledge and\nexperience I collected and gained in recent years about legacy x86_64 boot. The\nmain contribution IMHO is how the binary is assembled and that the thing boots\nwith all the properties described below, but not the high-level functionality\nitself._\n\n_I am especially proud of the well-commented structure of the assembly files.\nFor example the whole page-table mappings are done IMHO very nicely even though\nit is assembly language. Also, I think it turned out quite cool how I configured\nthe linker script. I hope this can be a learning resource for others!_\n\n_Further: This project is a solution for a niche use-case, especially in 2024._\n\nPhipsBoot is a relocatable x86_64 bootloader written in Rust and assembly that\nloads a kernel into 64-bit mode. It abstracts a lot of boot-related x86_64\ncomplexity away.\n\nThe main advantage of PhipsBoot is seen when loaded by GRUB via Multiboot2 in\nlegacy BIOS boot systems, where it can be relocated in physical memory even\nthough the kernel binary is a static ELF. However, PhipsBoot also supports\nMultiboot1 and XEN PVH entries.\n\n## About\n\n### Supported Boot Environments\n\nPhipsBoot expects an 32-bit protected mode without paging machine state at is\nentry. This corresponds to the Multiboot2 i386 machine state definition.\n\n| Firmware  | Hand-Off by   | Status | Comment                                 |\n|-----------|---------------|--------|-----------------------------------------|\n| BIOS/UEFI | Firmware      | ❌      | Use existing projects as chainloader.   |\n| BIOS/UEFI | Multiboot 1/2 | ✅      | Recommended (BIOS + GRUB + Multiboot 2) |\n| *         | Xen PVH       | ✅      |                                         |\n\n\n### Why Relying On GRUB + Multiboot2?\n\nEffectively, in the open-source world you are limited to GRUB when you want to\nboot your custom kernel on legacy BIOS x86_64 systems, while keeping up a\ncertain level of user and developer experience. By reusing all the abstracted\naway complexity that GRUB comes with, PhipsBoot can be much simpler and easier\nto program, install, adopt, and use.\n\n### Which problems does PhipsBoot solve?\n\nIt solves several problems every 64-bit kernel has to perform anyway, such as\nperforming the transition into 64-bit long mode while also being relocatable in\nphysical memory to never clash with firmware code, MMIO regions or otherwise\nreserved addresses. Kernels using this bootloader can massively simplify their\nbuild setup and boot code as much complexity is outsourced to PhipsBoot, such as\nseveral CPU state transitions and intermediate identity page mappings.\n\nBy far the biggest contribution of PhipsBoot is that it is relocatable in\nphysical memory when it is loaded by GRUB. Here, you can read more of the\n[overall challenges](https://phip1611.de/blog/x86-kernel-development-relocatable-binaries/).\n\n### Related Projects \u0026 Practical Alternatives\n\nFirst of all: If you are targeting UEFI and only UEFI, you need none of this!\nThe world is much simpler there. However, for legacy BIOS, the bootloader\ndeveloper and user experience is just difficult. To not be forced to use GRUB,\none can also write an\n[entire bootloader supporting legacy BIOS boot in Rust](https://github.com/rust-osdev/bootloaderz).\nThat's awesome! However, installing legacy BIOS stage 1 bootloaders on\ndisk is much more complicated, as one has to patch the MBR instead of just\nputting a file on disk. By using GRUB however, it is relatively easy to put\nPhipsBoot or other Multiboot payloads on disk and reference them from the GRUB\nconfig.\n\nIf you are targeting legacy x86 boot and have the freedom to choose and install\nyour own stage 1 bootloader, you can also have a look at\n[Limine](https://limine-bootloader.org/), which is superior to GRUB and\nproduction ready. It also brings your kernel into 64-bit mode right away, making\nPhipsBoot obsolete.\n\n### Trivia\n\nI'm kind of proud of the way I set up page-tables from assembly using\ndescriptive GNU as macros! I didn't see anything like that so far. IMHO it is\na great approach as low-level programming and assembly doesn't necessarily has\nto be ugly. 🤓\n\n## Developer Guide\n\n- General description about the architecture: [ARCHITECTURE.md](phipsboot/ARCHITECTURE.md)\n- Build and run test: `$ make \u0026\u0026 make integration-test`\n\nArtifacts are in `./build`.\n\n## User Guide\n\n### Boot PhipsBoot (for testing)\n\nYou have multiple options, for example:\n\n- `$ cloud-hypervisor --debug-console file=log.txt --kernel ./build/phipsboot.elf64` (using Xen PVH)\n- `$ qemu-system-x86_64 -kernel ./build/phipsboot.elf32 -debugcon stdio` (using Multiboot 1)\n\n### Supported Kernel Payloads\n\nSupported payloads that PhipsBoot can boot are ELF executables (static and dyn).\nThe hand-off to the kernel follows the PhipsBoot protocol.\n\n### PhipsBoot protocol\n\nThis protocol describes the hardware state and the handover to your kernel when\nit is booted by PhipsBoot.\n\n#### Kernel Entry\n\nThe kernel entry is taken from the ELF entry. It is invoked using the SystemV\nx86_64 calling convention. First argument passed to your kernel is a point to\nthe boot information.\n\n#### Machine State after hand-off\n\n- PhipsBoot is still mapped and occupies (at most) 2 MiB of virtual address\n  space\n- BSP in 64-bit long mode with 4-level paging\n- APs are still asleep\n- control registers\n    - `%cr0`: PE (0), MP (1), WP (16), PG (31)\n    - `%cr4`: PAE (5), OSFXSR (9), OSXMMEXCPT (10)\n    - `%cr3`: holds the physical address of the root page table\n- MSRs\n    - `efer`: LME (8), NX (11)\n- GDT, which is living in the physical address space of PhipsBoot, is set with\n  two selectors:\n    - null selector\n    - (64-bit, code segment, ring 0)-selector\n- `%rsp` is set to a valid 128 KiB stack\n- `%rdi` has pointer to boot information\n- All load segments of the kernel are loaded with their corresponding page-table\n  rights. The NX bits are set for all non-executable LOAD segments.\n\n#### Boot Information\n\nTODO implement\n\n### Booting Your Kernel with PhipsBoot\n\nTODO implement\n\nYou can use the following GRUB configuration:\n\n```\nmenuentry \"Kernel\" {\n    multiboot2 /phipsboot\n    module2 /your-kernel\n    boot\n}\n```\n\n#### Binary Formats of PhipsBoot\n\nThe build itself produces `phipsboot.elf32` and `phipsboot.elf64`. Both are\nidentical except for the ELF header. You usually always want to use the `.elf64`\nversion except for when booting it via Multiboot1, where compliant bootloaders\nonly accept 32-bit ELFs.\n\n\u003c!--\nTODO\nFurthermore, the build also produces a `.iso` variant that is bootable on\nlegacy BIOS systems. The `.iso` variant uses a GRUB standalone image that\nchainloads PhipsBoot via Multiboot 2. GRUB2 will physically relocate PhipsBoot.\nThe `.iso` variant is used for testing and for you as inspiration for on how\nyou can package PhipsBoot along with your kernel.\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphip1611%2Fphipsboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphip1611%2Fphipsboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphip1611%2Fphipsboot/lists"}