{"id":13740780,"url":"https://github.com/stakach/uefi-bootstrap","last_synced_at":"2025-05-12T13:29:09.933Z","repository":{"id":45990869,"uuid":"413672576","full_name":"stakach/uefi-bootstrap","owner":"stakach","description":"experiments with bootstrapping a kernel with UEFI","archived":false,"fork":false,"pushed_at":"2021-11-22T13:51:19.000Z","size":60,"stargazers_count":36,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T22:34:53.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stakach.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}},"created_at":"2021-10-05T04:26:15.000Z","updated_at":"2025-02-16T01:00:30.000Z","dependencies_parsed_at":"2022-08-29T20:40:54.767Z","dependency_job_id":null,"html_url":"https://github.com/stakach/uefi-bootstrap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakach%2Fuefi-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakach%2Fuefi-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakach%2Fuefi-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakach%2Fuefi-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stakach","download_url":"https://codeload.github.com/stakach/uefi-bootstrap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253747439,"owners_count":21957757,"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":[],"created_at":"2024-08-03T04:00:52.145Z","updated_at":"2025-05-12T13:29:09.907Z","avatar_url":"https://github.com/stakach.png","language":"Zig","funding_links":[],"categories":["Applications"],"sub_categories":[],"readme":"# OS DEV\n\nThis should be a very simple jumping off point to modern kernel development.\n\nThe idea behind this project is to provide an easy to understand, minimalist bootstrap that lowers the barrier to entry for any new comers.\n\nCode works for both\n\n* x86_64\n* AArch64\n\nrun `./build.sh` and you can boot the resulting example kernel on both x86_64 and AArch64\n\n\n### Crystal Kernel\n\nThis bootstrap is being used to load this hobby OS\nhttps://github.com/stakach/crystal-kernel\n\n\n## Getting started\n\nVery easy to test and run on Windows with [VirtualBox](https://www.virtualbox.org/) see [Crystal Kernel](https://github.com/stakach/crystal-kernel#development-on-macos) for details on how to test and even step through debug your kernel on macOS.\n\n* Compile on Win Linux layer, macOS or Linux\n* Clang + LLVM toolchain\n* requires [Zig lang](https://ziglang.org/download/)\n\n\n## Building an EFI bootable executable\n\nEFI expects the bootable file to be in COFF/PE32+ format\n\n* run `./build.sh` to clean and build for all architectures\n\nyou can also do this manually\n\n1. run `make -f makefile_x86_64`\n2. this will output\n   * `bin/efi/boot/bootx64.efi`\n   * `bin/kernelx64.elf`\n3. you can inspect symbols in the object files using `nm -C bin/uefi_bootstrap.obj` (or `kernelx64.elf`)\n   * anything with a `U` tag, i.e. `U memcpy` means memcpy needs to be defined in your project\n\n\n## Create a disk image for booting\n\nVery simple to do this on Windows, for macOS see [Crystal Kernel](https://github.com/stakach/crystal-kernel#development-on-macos) which builds disk images as part of the build script\n\n* Disk Management (`diskmgmt.msc`)\n  * Action -\u003e Create VHD\n  * Initialize disk (GPT GUID Partition Table)\n  * Format as FAT32\n* create the following folder:\n  * `/efi/boot`\n  * add bootstrap file as `bootx64.efi`\n* OR just copy the `bin` folder contents to the VHD\n\nunmount the disk before booting it in VirtualBox\n\u003cimg src=\"https://user-images.githubusercontent.com/368013/136745462-d5793f29-e85a-4642-9854-98ea047e3bf9.png\" alt=\"unmount\" width=\"300\"/\u003e\n\n\n## Create a VM\n\n* Install VirtualBox\n* Create new VM\n  * Type: Other\n  * Version: Other/Unknown (64bit)\n  * Don't add a HD\n* Edit Settings\n  * System -\u003e Check \"Enable EFI\"\n  * Storage -\u003e Add default IDE + select VHD image from above\n\nStarting the VM will now boot the bootx64.efi file\n\n\u003cimg src=\"https://user-images.githubusercontent.com/368013/136746021-11f16641-0666-4cdc-bd5a-5d9975eba328.png\" alt=\"unmount\" width=\"700\"/\u003e\n\n\n## Diving into the code\n\nThe process of booting should be fairly simple to follow along looking at `uefi_bootstrap.zig`\nThe real trick with UEFI code is that\n\n* it needs to be in PE/COFF format (think Windows .exe files)\n* conform to a particular entrypoint format (`-Wl,-entry:efi_main` in the make file)\n\nThe bootstrap code likewise expects a few things of the kernel.elf file:\n\n* Segments need to be 4kb aligned - for paging support\n* the entry point takes no params and returns void\n* the boot_info structure is going to be stored at address 1MB\n  * (no matter where the elf segments request to be loaded)\n\nTake a look at `kernel.ld` to see how this is laid out.\nFor instance I currently have the `boot_info` label in the `text` section. But I could probably swap around the text and data sections if I wanted boot_info as part of data or bss\n\n### Accessing the full address space\n\nhttps://eli.thegreenplace.net/2012/01/03/understanding-the-x64-code-models\n\n* this flag is set in the makefile\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstakach%2Fuefi-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstakach%2Fuefi-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstakach%2Fuefi-bootstrap/lists"}