{"id":13692114,"url":"https://github.com/davmac314/tosaithe","last_synced_at":"2026-02-27T10:22:33.250Z","repository":{"id":111578143,"uuid":"407533032","full_name":"davmac314/tosaithe","owner":"davmac314","description":"Very minimalistic UEFI boot menu / kernel bootloader","archived":false,"fork":false,"pushed_at":"2024-09-07T23:50:54.000Z","size":418,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-09-08T00:36:01.405Z","etag":null,"topics":["bootloader","osdev","uefi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davmac314.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-17T12:30:45.000Z","updated_at":"2024-09-07T23:50:58.000Z","dependencies_parsed_at":"2024-07-19T14:07:49.007Z","dependency_job_id":null,"html_url":"https://github.com/davmac314/tosaithe","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davmac314%2Ftosaithe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davmac314%2Ftosaithe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davmac314%2Ftosaithe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davmac314%2Ftosaithe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davmac314","download_url":"https://codeload.github.com/davmac314/tosaithe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224328512,"owners_count":17293270,"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","osdev","uefi"],"created_at":"2024-08-02T17:00:53.853Z","updated_at":"2026-02-27T10:22:32.380Z","avatar_url":"https://github.com/davmac314.png","language":"C++","funding_links":[],"categories":["Projects"],"sub_categories":["Bootloaders"],"readme":"# Tosaithe\n\n_Version 1.0_\n\nTosaithe is a minimalistic UEFI-firmware menu/bootloader. It can chain-load other EFI programs\nand loaders, including Linux kernels, and has basic support for a bespoke boot protocol and\nkernel image format (the \"Tosaithe boot protocol\" or \"TSBP\"). It is currently x86-64 only.\n\nThis is free software, with as few restrictions as legally possible. It comes with no warranty\nand no guarantee of support from the author. Use it at your own risk.\n\n## Introduction\n\nTosaithe is a very simple, but fully functional, bootloader/menu for systems with a UEFI firmware.\nIt mainly serves as the reference implementation for the Tosaithe Boot Protocol (TSBP).\n\nIt is also:\n\n* An example UEFI bootloader / boot menu\n* ... written in C++, exceptions and all\n* ... that can be built using standard SysV ELF toolchain (eg GCC and GNU binutils on Linux)\n* ... that doesn't require EDK II or GNU-EFI\n\nIt also serves as an example client of the bmcxxabi, bmunwind, and libbmcxx libraries which\ntogether provide a C++ runtime and standard library.\n\n![A screenshot of Tosaithe displaying a boot menu](/screenshot/tosaithe-screenshot.png?raw=true \"Tosaithe in action\")\n\n## The Tosaithe boot protocol (TSBP)\n\nThere is a [specification document](doc/TSBP.md) for the protocol in this repository.\n\nA \"Bare Bones\" [example](https://github.com/davmac314/tosaithe-bb/) is also available in a\nseparate repository.\n\nKey features:\n\n* Uses ELF format kernels, easily constructed with commonly available toolchains\n* Kernels are loaded and mapped into the \"high half\" (or \"negative\") address space by the loader\n* Memory map, firmware information, and framebuffer details are passed to the kernel\n* Supports passing kernel command line and initial ramdisk image\n\nSee the specification document for details.\n\n## Building Tosaithe\n\nBuilding requires GCC or Clang, or another compatible compiler, targeting SysV-ABI ELF (eg Linux)\nand either:\n\n* GNU binutils \"ld\" with support for the PE+ format as well as ELF (this is usually the case with\n  distro-provided Binutils, use `--enable-targets=x86_64-none-pe,x86_64-none-pep` when configuring\n  if building it yourself); or\n* Both a linker such as GNU binutils \"ld\", or any other compatible linker such as LLVM's \"lld\"\n  (`ld.lld`) or Gold (`ld.gold`), and the \"elf2efi64\" utility. The linker must support GNU ld\n  linker scripts and various GNU ld command-line options but does not need PE+ support.\n\nBuilds using the first option have been tested with GCC 11.4.0 and Binutils 2.39. I recommend not\ntrying to use older Binutils as there have been bugs with the PE+ output format support.\n\nTo build:\n\n1. `sh clone-libs.sh` or `sh clone-libs.sh https` to clone the dependencies. Use the latter to\n    clone via https, which avoids needing to have your ssh public key enrolled with Github.\n2. `sh rebuild-libs.sh` to build the dependencies (in-tree)\n3. `make` to build Tosaithe (using binutils with PE+ support) or `make USE_ELF2EFI=yes` to build\n   using ELF2EFI (`elf2efi64`). In the latter case `LD=...` can be specified to name an\n   alternative linker, if desired: `ld.lld` or `ld.gold` should work, if available.\n\n## Installing Tosaithe\n\nCopy `tosaithe.efi` (generated in the `src` directory) to your EFI system partition. You can copy\nit over `\\EFI\\BOOT\\bootx64.efi` in order to boot with it (maybe), but I highly recommend you don't\ndo that until you're sure that it works; copy it somewhere else and run it via Grub or the UEFI\nshell for example. Documentation for these is found elsewhere.\n\nYou will need a `tosaithe.conf` text file (UTF-8) in the root directory of the same partition. This\nshould look something like:\n\n```\nentry: {\n    description = 'Linux - 5.10.47'\n    type = chain\n    exec = '\\linux-5.10.47'\n    cmdline = 'root=/dev/sda1 initrd=initrd.img'\n}\n\nentry: {\n    description = 'EFI Shell'\n    type = chain\n    exec = '\\EFI\\Shell.efi'\n    cmdline = 'Shell.efi'\n}\n\nentry: {\n    description = 'My Tosaithe Kernel'\n    type = tosaithe\n    exec = '\\mykernel.elf'\n    cmdline = ''\n}\n```\n\nNote that when chaining to an EFI program (when `type = chain`) the command line should include\nthe program name as first argument to emulate the EFI shell, but this is not what all programs\nexpect (eg Linux kernel doesn't want it). Paths are on the boot partition (or rather, the\npartition that Tosaithe itself is run from) or specified as full EFI device paths.\n\nIf using a full device path, note the textual form of device paths as documented in the UEFI\nspecification (at least up until 2.10) is very wrong. Notable deviations by UEFI implementations\n(including EDK2) from the spec include:\n\n* Device paths do not begin with a leading slash or backslash, i.e. the first device node in a\n  device path is not preceded by a slash, despite that the UEFI spec claim that \"each [node is]\n  preceded by a [slash]\".\n* There is a forward-slash between device path nodes in a device path, never a backslash, contrary\n  to the spec which claims either slash or backslash character may separate nodes.\n* Device paths do not accumulate leading slashes as each node is appended. The grammar in the spec\n  is completely wrong; the slash goes between device nodes.\n* A file path device node (at the end of the device path) uses backslash as path element separator\n  and is preceded by a leading backslash (immediately following the forward slash which separates\n  the file path node from the previous node in the path).\n  \nSee for example:\n* https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiDevicePathLib/DevicePathFromText.c\n* https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiDevicePathLib/DevicePathToText.c\n\nAn example path looks something like:\n```\nPciRoot(0x0)/Pci(0x3,0x0)/Sata(0x0,0xFFFF,0x0)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBC1)/\\some\\file.txt\n```\n(Yes, UEFI paths are unwieldy!).\n\n## Using Tosaithe\n\nWhen Tosaithe runs it reads the configuration file, prints a banner and lists the entries found in\norder. The entries are numbered and to select an entry you press the corresponding number on the\nkeyboard.\n\nUse the 'n' and 'p' to navigate to the next and previous page, respectively, if there are more\nthan 10 entries in the menu. Use 'x' to exit Tosaithe, 's' to shut down the system. Press space\nto refresh the display of menu items.\n\n## Alternatives\n\nIf you are looking for a boot menu / bootloader / protocol and Tosaithe doesn't cut it for you,\nI strongly recommend checking out [Limine](https://github.com/limine-bootloader/limine); see its\nprotocol specification [here](https://github.com/limine-bootloader/limine/blob/trunk/PROTOCOL.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavmac314%2Ftosaithe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavmac314%2Ftosaithe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavmac314%2Ftosaithe/lists"}