### Limine GUID Resource Path Example

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using the 'guid' resource with a filesystem or partition GUID.

```plaintext
guid(736b5698-5ae1-4dff-be2c-ef8f44a61c52):/...
```

--------------------------------

### Limine TFTP Resource Path Example

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using the 'tftp' resource for network booting. If the argument is empty, it uses the server Limine booted from.

```plaintext
tftp():/...
```

--------------------------------

### Install Limine on ISO Image

Source: https://github.com/limine-bootloader/limine/blob/v12.x/USAGE.md

After creating the ISO image, run this command to install Limine onto it, making it bootable.

```bash
limine bios-install image.iso
```

--------------------------------

### Limine Path Syntax Examples

Source: https://context7.com/limine-bootloader/limine/llms.txt

Illustrates Limine's path syntax for accessing files across various storage resources like boot partitions, hard drives, optical drives, GUIDs, volume labels, and TFTP servers. It also shows how to include BLAKE2B hashes for integrity checking and use a '$' prefix for transparent gzip decompression.

```ini
# Boot partition (partition containing the config file)
path: boot():/boot/vmlinuz

# Specific partition on the boot drive (partition 2)
path: boot(2):/kernels/vmlinuz-6.x

# Hard drive 1, partition 3
path: hdd(1:3):/boot/kernel.elf

# Optical drive 1, whole disc (ISO9660)
path: odd(1:):/boot/kernel

# By GPT/filesystem GUID
path: guid(736b5698-5ae1-4dff-be2c-ef8f44a61c52):/boot/vmlinuz

# By filesystem label
path: fslabel(BOOT):/vmlinuz

# PXE/TFTP from boot server
path: tftp():/kernels/pxe-kernel

# PXE from specific server IP
path: tftp(192.168.1.10):/vmlinuz

# With BLAKE2B hash for integrity (required under Secure Boot)
path: boot():/boot/vmlinuz#ca6914d2c8b4b2a2d4e2b7a9f33e44b1a1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef446b470a

# Transparent gzip decompression
path: $boot():/boot/vmlinuz.gz

# Compressed + hash (hash covers the compressed bytes)
path: $boot():/boot/vmlinuz.gz#abcdef1234567890...
```

--------------------------------

### Install Limine

Source: https://github.com/limine-bootloader/limine/blob/v12.x/INSTALL.md

Execute this command to install Limine files to the specified prefix after building. Use 'gmake' if 'make' is not available or aliased.

```bash
make install    # (or gmake where applicable)
```

--------------------------------

### Limine Boot Resource Path Example

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using the 'boot' resource to specify a partition on the boot drive. If omitted, it defaults to the partition containing the configuration file.

```plaintext
boot(2):/...
```

```plaintext
boot():/...
```

--------------------------------

### Print Limine Data Directory

Source: https://context7.com/limine-bootloader/limine/llms.txt

Use this command to find the installation path of Limine's bootloader binaries. This is useful for automating the copying of boot files during system setup. It's only available when Limine is installed as part of a full system, not in standalone builds.

```bash
limine --print-datadir
# Output: /usr/share/limine

# Use to locate boot files automatically
DATADIR=$(limine --print-datadir)
cp "$DATADIR/BOOTX64.EFI" /boot/efi/EFI/BOOT/BOOTX64.EFI
cp "$DATADIR/limine-bios.sys" /boot/limine/limine-bios.sys
```

--------------------------------

### Install Limine for BIOS/GPT

Source: https://github.com/limine-bootloader/limine/blob/v12.x/USAGE.md

Use this command to install Limine on a GPT formatted device. Specify the 1-based partition number for the stage 2 files.

```bash
limine bios-install <path to device/image> <1-based stage 2 partition number>
```

--------------------------------

### Limine HDD Resource Path Example

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using the 'hdd' resource to specify a hard drive and partition. Omitting the partition accesses the entire volume.

```plaintext
hdd(3:1):/...
```

```plaintext
hdd(2:):/...
```

--------------------------------

### Limine Boot Configuration File (`limine.conf`)

Source: https://context7.com/limine-bootloader/limine/llms.txt

This is a comprehensive example of the `limine.conf` file, which configures the Limine boot menu. It covers global options, interface branding, wallpaper, terminal settings, security features, editor settings, macros, and definitions for various bootable entries including Limine protocol, Linux boot protocol, Multiboot2, EFI chainloading, EFI boot entry redirection, BIOS chainloading, and subdirectory entries.

```ini
# limine.conf — Comprehensive example

# ── Global options ──────────────────────────────────────────────────────────
timeout: 5
default_entry: 1
remember_last_entry: yes
quiet: no
serial: no
verbose: no
graphics: yes

# Interface branding and colours (RRGGBB hex)
interface_branding: My Custom OS Loader
interface_branding_colour: 00aaff
interface_help_colour: 00cc44
interface_resolution: 1920x1080

# Wallpaper (BMP, PNG, JPEG, QOI supported; multiple = random pick)
wallpaper: boot():/boot/wallpaper.png
wallpaper_style: stretched

# Graphical terminal font and palette
term_font: boot():/boot/font.bin
term_font_size: 8x16
term_font_scale: 1x1
term_background: 80000000
term_foreground: ffffff

# Security
hash_mismatch_panic: yes
measured_boot: no

# Editor
editor_enabled: yes
editor_highlighting: yes

# Macros
${KERNEL_ARGS}=quiet loglevel=3 rw

# ── Limine protocol kernel ───────────────────────────────────────────────────
/Arch Linux (Limine protocol)
    comment: Boots Arch Linux using the native Limine protocol
    protocol: limine
    path: boot():/boot/vmlinuz-linux
    cmdline: ${KERNEL_ARGS} root=/dev/sda2
    module_path: boot():/boot/initramfs-linux.img
    module_string: Initial RAM disk
    kaslr: no
    resolution: 1920x1080x32

# ── Linux boot protocol ──────────────────────────────────────────────────────
/Linux (standard protocol)
    protocol: linux
    path: boot():/boot/vmlinuz
    module_path: boot():/boot/initrd.img
    cmdline: root=/dev/sda2 ro splash
    resolution: 1280x720

# ── Multiboot 2 kernel ───────────────────────────────────────────────────────
/GRUB/Multiboot2 OS
    protocol: multiboot2
    path: boot():/boot/kernel.elf
    module_path: boot():/boot/module1.bin
    module_string: mymodule

# ── EFI Chainload ────────────────────────────────────────────────────────────
/Windows Boot Manager
    protocol: efi
    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi

# ── EFI Boot Entry redirect ──────────────────────────────────────────────────
/Reboot to Firmware Setup
    protocol: efi_boot_entry
    entry: Setup

# ── BIOS Chainload ───────────────────────────────────────────────────────────
/Legacy BIOS partition
    protocol: bios
    drive: 1
    partition: 2

# ── Subdirectory (directory entry) ──────────────────────────────────────────
/Advanced Options
//Arch Linux (fallback initramfs)
    protocol: linux
    path: boot():/boot/vmlinuz-linux
    module_path: boot():/boot/initramfs-linux-fallback.img
    cmdline: ${KERNEL_ARGS} root=/dev/sda2

//Boot from USB (partition 1)
    protocol: limine
    path: hdd(2:1):/boot/vmlinuz
```

--------------------------------

### Limine Optical Drive Resource Path Example

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using the 'odd' resource for optical drives. Similar to 'hdd', omitting the partition accesses the entire volume.

```plaintext
odd(3:1):/...
```

```plaintext
odd(2:):/...
```

--------------------------------

### Install Limine EFI Executables and Configuration

Source: https://context7.com/limine-bootloader/limine/llms.txt

Copy Limine EFI executables to the EFI System Partition (ESP) and place the configuration file. Registers the boot entry with UEFI NVRAM using efibootmgr.

```bash
# Mount ESP and copy Limine files
mount /dev/sda1 /mnt/esp

mkdir -p /mnt/esp/EFI/BOOT
cp /usr/share/limine/BOOTX64.EFI /mnt/esp/EFI/BOOT/BOOTX64.EFI   # x86-64
# cp /usr/share/limine/BOOTAA64.EFI /mnt/esp/EFI/BOOT/BOOTAA64.EFI  # aarch64
# cp /usr/share/limine/BOOTRISCV64.EFI /mnt/esp/EFI/BOOT/BOOTRISCV64.EFI

# Place config on the ESP or on any other partition
mkdir -p /mnt/esp/EFI/BOOT
cat > /mnt/esp/EFI/BOOT/limine.conf << 'EOF'
timeout: 5
/My OS
    protocol: linux
    path: boot():/vmlinuz
    module_path: boot():/initrd.img
    cmdline: root=/dev/sda2 ro quiet
EOF

# Register with UEFI NVRAM (optional; boot from removable media works without this)
efibootmgr --create --disk /dev/sda --part 1 \
    --label "Limine" \
    --loader "\EFI\BOOT\BOOTX64.EFI"
```

--------------------------------

### Install Limine on BIOS/MBR

Source: https://github.com/limine-bootloader/limine/blob/v12.x/USAGE.md

Installs Limine onto a MBR device or raw image file. Ensure the boot device contains the necessary Limine files in a supported directory structure.

```bash
limine bios-install <path to device/image>
```

--------------------------------

### Install Limine BIOS Bootloader to MBR/GPT Disk

Source: https://context7.com/limine-bootloader/limine/llms.txt

Installs Limine's BIOS boot code to a disk image or block device. For GPT disks, a dedicated BIOS boot partition is required. Supports uninstall data saving, forced installation, and disabling automatic GPT-to-MBR conversion for ISOHYBRIDs.

```bash
# MBR disk: install directly
limine bios-install /dev/sda
```

```bash
# GPT disk: partition 1 is the BIOS boot partition (type: BIOS boot, ≥32 KiB)
limine bios-install /dev/sda 1
```

```bash
# Save uninstall data so the install can be reversed later
limine bios-install /dev/sda --uninstall-data-file=limine-uninstall.dat
```

```bash
# Reverse a prior installation using saved uninstall data
limine bios-install /dev/sda --uninstall --uninstall-data-file=limine-uninstall.dat
```

```bash
# Force installation even if safety checks detect NTFS/FAT/ext4 magic bytes
limine bios-install /dev/sda --force
```

```bash
# Suppress all diagnostic output
limine bios-install /dev/sda --quiet
```

```bash
# Disable automatic GPT→MBR conversion on ISOHYBRIDs
limine bios-install image.iso --no-gpt-to-mbr-isohybrid-conversion
```

```bash
# Full ISO creation workflow: build ISO, then install BIOS boot code
xorriso -as mkisofs -R -r -J \
        -b boot/limine-bios-cd.bin \
        -no-emul-boot -boot-load-size 4 -boot-info-table \
        -hfsplus -apm-block-size 2048 \
        --efi-boot boot/limine-uefi-cd.bin \
        -efi-boot-part --efi-boot-image --protective-msdos-label \
        iso_root/ -o image.iso
limine bios-install image.iso
# Expected: "Limine BIOS stages installed successfully."
```

--------------------------------

### Build Limine from Source (Release Tarball)

Source: https://context7.com/limine-bootloader/limine/llms.txt

Compile Limine from a release tarball using Autoconf and Make. Requires enabling specific architecture ports via configure flags. Installs to specified prefix.

```bash
# From a release tarball
./configure --enable-bios --enable-uefi-x86-64 --prefix=/usr
make
sudo make install
# Installs to /usr/share/limine/, /usr/bin/limine, /usr/include/limine.h
```

--------------------------------

### Build Limine with Out-of-Tree Compilation

Source: https://context7.com/limine-bootloader/limine/llms.txt

Perform an out-of-tree build of Limine by creating a separate build directory. Configure and make commands are run from this directory. Installs to specified prefix.

```bash
# Out-of-tree build
mkdir build && cd build
../configure --enable-bios --enable-uefi-x86-64 --prefix=/usr
make -j$(nproc)
sudo make install
```

--------------------------------

### Limine Macro Definition

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of defining a custom macro in the Limine configuration file.

```plaintext
${MY_MACRO}=Some text
```

--------------------------------

### Build Limine from Source (Git Checkout)

Source: https://context7.com/limine-bootloader/limine/llms.txt

Compile Limine from a git checkout, requiring bootstrap to generate configure script. Enables multiple architecture ports and installs to a specified prefix. Uses parallel build.

```bash
# From a git checkout (requires autoconf, git)
./bootstrap
./configure --enable-bios \
            --enable-uefi-x86-64 \
            --enable-uefi-aarch64 \
            --enable-uefi-riscv64 \
            --enable-uefi-loongarch64 \
            --prefix=/usr/local
make -j$(nproc)
sudo make install
```

--------------------------------

### Get SMBIOS Entry Points with `acpi_get_smbios`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Retrieves pointers to both 32-bit and 64-bit SMBIOS entry points. This is necessary for systems that provide SMBIOS information via ACPI.

```c
// Get SMBIOS entry points (both 32-bit and 64-bit)
void *smbios32 = NULL, *smbios64 = NULL;
acpi_get_smbios(&smbios32, &smbios64);

```

--------------------------------

### Enumerate Storage Volumes with `volume_get_by_*`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Provides multiple ways to locate storage volumes and partitions by coordinate, GUID, or filesystem label. These functions are used by the config path parser.

```c
#include <lib/part.h>
#include <lib/guid.h>

// By drive/partition coordinate
// optical=false, drive=0 (first HDD), partition=1 (first partition)
struct volume *vol = volume_get_by_coord(false, 0, 1);

// By GUID (filesystem UUID or GPT partition GUID)
struct guid guid;
string_to_guid_mixed(&guid, "736b5698-5ae1-4dff-be2c-ef8f44a61c52");
struct volume *vol_by_guid = volume_get_by_guid(&guid);

// By filesystem label
struct volume *vol_by_label = volume_get_by_fslabel("BOOT");

```

--------------------------------

### Limine Macro Usage

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of using a defined macro within the Limine configuration file. Macros are enclosed in ${...}.

```plaintext
CMDLINE=something before ${MY_MACRO} something after
```

--------------------------------

### Configure EFI and BIOS Chainloading for Limine

Source: https://context7.com/limine-bootloader/limine/llms.txt

Set up Limine to chainload other EFI applications or BIOS boot sectors. Supports identifying targets by path, GPT GUID, or MBR ID.

```ini
# EFI: Boot Windows via shim
/Windows 11
    protocol: efi
    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi

# EFI: Boot rEFInd
/rEFInd
    protocol: efi
    path: boot():/EFI/refind/refind_x64.efi

# EFI Boot Entry: reboot into a named UEFI boot entry
/Reboot to BIOS/UEFI Firmware Setup
    protocol: efi_boot_entry
    entry: Setup

# BIOS: Chainload MBR of drive 1
/Legacy BIOS (Drive 1 MBR)
    protocol: bios
    drive: 1
    partition: 0

# BIOS: Chainload partition 1 of drive 1
/Legacy partition
    protocol: bios
    drive: 1
    partition: 1

# BIOS: Identify drive by GPT GUID
/Legacy by GUID
    protocol: bios
    gpt_uuid: 736b5698-5ae1-4dff-be2c-ef8f44a61c52
    partition: 1

# BIOS: Identify drive by MBR disk ID
/Legacy by MBR ID
    protocol: bios
    mbr_id: 12345678
    partition: 2
```

--------------------------------

### Limine Path with Hash Suffix

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Example of appending a blake2b hash to a Limine path for file integrity verification, required for Secure Boot.

```plaintext
boot():/somemodule.tar#ca6914d2...446b470a
```

--------------------------------

### Limine Path Syntax

Source: https://github.com/limine-bootloader/limine/blob/v12.x/CONFIG.md

Defines the structure for specifying file paths within the Limine configuration. Supports various resources like boot partitions, hard drives, optical drives, GUIDs, and TFTP servers.

```plaintext
resource(argument):/path
```

--------------------------------

### volume_get_by_* — Volume and partition enumeration

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for locating storage volumes and partitions by various identifiers such as coordinates, GUIDs, labels, or BIOS drive numbers. It's used for resolving boot path resources.

```APIDOC
## `volume_get_by_*` — Volume and partition enumeration

Internal C API for locating storage volumes by various identifiers: coordinate (drive/partition index), filesystem GUID or GPT partition GUID, filesystem label, or BIOS drive number. Used by the config path parser to resolve `boot()`, `hdd()`, `guid()`, and `fslabel()` path resources.

```c
#include <lib/part.h>
#include <lib/guid.h>

// By drive/partition coordinate
// optical=false, drive=0 (first HDD), partition=1 (first partition)
struct volume *vol = volume_get_by_coord(false, 0, 1);

// By GUID (filesystem UUID or GPT partition GUID)
struct guid guid;
string_to_guid_mixed(&guid, "736b5698-5ae1-4dff-be2c-ef8f44a61c52");
struct volume *vol_by_guid = volume_get_by_guid(&guid);

// By filesystem label
struct volume *vol_by_label = volume_get_by_fslabel("BOOT");

// Read data directly from a volume (sector-level)
uint8_t mbr[512];
bool ok = volume_read(vol, mbr, 0, sizeof(mbr));

// Iterate all partitions of a drive
volume_iterate_parts(vol, {
    // _PART is a struct volume * pointing to each partition
    struct guid part_guid;
    if (gpt_get_guid(&part_guid, _PART)) {
        char guid_str[37];
        guid_to_string(&part_guid, guid_str);
        printf("Partition GUID: %%s\n", guid_str);
    }
});

// Get MBR disk ID
uint32_t mbr_id = mbr_get_id(vol);
printf("MBR ID: %08x\n", mbr_id);
```
```

--------------------------------

### Configure Limine for PXE Boot with TFTP

Source: https://context7.com/limine-bootloader/limine/llms.txt

This section outlines the steps to set up a TFTP server and configure Limine to boot a kernel and initrd over the network. It includes copying necessary Limine files and creating a limine.conf file with TFTP paths.

```bash
cp /usr/share/limine/limine-bios-pxe.bin /var/lib/tftpboot/
cp /usr/share/limine/limine-bios.sys /var/lib/tftpboot/
cp limine.conf /var/lib/tftpboot/
```

```bash
cp /boot/vmlinuz /var/lib/tftpboot/vmlinuz
cp /boot/initrd.img /var/lib/tftpboot/initrd.img
```

```bash
cat > /var/lib/tftpboot/limine.conf << 'EOF'
timeout: 5
/PXE Boot
    protocol: linux
    path: tftp():/vmlinuz
    module_path: tftp():/initrd.img
    cmdline: root=/dev/nfs nfsroot=192.168.1.1:/exports/root ip=dhcp
EOF
```

--------------------------------

### Build Limine

Source: https://github.com/limine-bootloader/limine/blob/v12.x/INSTALL.md

Run this command to compile the Limine bootloader after configuration. Use 'gmake' if 'make' is not available or aliased.

```bash
make    # (or gmake where applicable)
```

--------------------------------

### Check Available Limine Configure Options

Source: https://context7.com/limine-bootloader/limine/llms.txt

Display all available configuration options for the Limine build process using the configure script.

```bash
# Check available configure options
./configure --help
```

--------------------------------

### Configure BIOS PXE Boot with Dnsmasq

Source: https://context7.com/limine-bootloader/limine/llms.txt

Set up dnsmasq to serve Limine's BIOS PXE boot image and configuration files. Configures DHCP ranges, boot file, and TFTP root directory.

```bash
# BIOS PXE: Configure dnsmasq to serve limine-bios-pxe.bin
cat >> /etc/dnsmasq.conf << 'EOF'
dhcp-range=192.168.1.100,192.168.1.200,12h
dhcp-boot=limine-bios-pxe.bin
enable-tftp
tftp-root=/var/lib/tftpboot
EOF
```

--------------------------------

### Validate ACPI Checksum with `acpi_checksum`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Calculates and validates the checksum of an ACPI table, starting from the RSDP. A checksum of 0 indicates a valid table.

```c
// Compute ACPI checksum (validation)
uint8_t sum = acpi_checksum(rsdp, sizeof(struct rsdp));
// sum == 0 means checksum is valid

```

--------------------------------

### Get MBR Disk ID with `mbr_get_id`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Retrieves the MBR disk ID for a given volume. This is a unique identifier for the disk in MBR partitioning schemes.

```c
// Get MBR disk ID
uint32_t mbr_id = mbr_get_id(vol);
printf("MBR ID: %08x\n", mbr_id);

```

--------------------------------

### Create Hybrid ISO with xorriso

Source: https://github.com/limine-bootloader/limine/blob/v12.x/USAGE.md

This command creates a hybrid ISO image with Limine support for both BIOS and UEFI. Ensure Limine's boot files are placed in the root directory or subdirectories as specified.

```bash
xorriso -as mkisofs -R -r -J -b <relative path of limine-bios-cd.bin> \
        -no-emul-boot -boot-load-size 4 -boot-info-table -hfsplus \
        -apm-block-size 2048 --efi-boot <relative path of limine-uefi-cd.bin> \
        -efi-boot-part --efi-boot-image --protective-msdos-label \
        <root directory> -o image.iso
```

--------------------------------

### Rebuild Standalone Host Tool

Source: https://context7.com/limine-bootloader/limine/llms.txt

Rebuild the standalone host tool from a binary release of Limine. Includes commands to build, and check the version of the tool.

```bash
# Rebuild the host tool standalone (from a binary release)
cd limine-binary-*
make
./limine version
```

--------------------------------

### Print Limine Version Information

Source: https://context7.com/limine-bootloader/limine/llms.txt

Displays Limine's version, copyright, and license. The `--version-only` flag is useful for scripting to obtain just the version number.

```bash
limine version
# Output:
# Limine 12.2.0
# Copyright (C) 2019-2026 mintsuki and contributors.
# Limine is distributed under the terms of the BSD-2-Clause license.
# There is ABSOLUTELY NO WARRANTY, to the extent permitted by law.
```

```bash
limine version --version-only
# Output: 12.2.0
```

```bash
# Use in scripts
LIMINE_VER=$(limine version --version-only)
echo "Using Limine $LIMINE_VER"
```

--------------------------------

### Read Files with Limine Filesystem Abstraction (C API)

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for reading files from Limine-supported volumes and filesystems. Use `fopen`, `fread`, and `fclose` with `struct file_handle` for uniform access. `alloc_and_read` reads the entire file.

```c
#include <fs/file.h>
#include <lib/part.h>

// Open a file on a specific volume
struct volume *vol = volume_get_by_coord(false, 0, 1); // drive 0, partition 1
struct file_handle *fh = fopen(vol, "/boot/vmlinuz");
if (fh == NULL) {
    panic(true, "Could not open kernel file.");
}
```

```c
// Read the entire file into a buffer
uint8_t *buf = alloc_and_read(fh);  // fh->size bytes needed
```

```c
// Or read a specific range
uint8_t header[64];
uint64_t bytes_read = fread(fh, header, 0, sizeof(header));
if (bytes_read != sizeof(header)) {
    panic(true, "Short read on kernel header.");
}
```

```c
// Access metadata
uint64_t file_size = fh->size;
bool is_network = fh->pxe;

fclose(fh);
```

```c
// Filesystem-level helpers
struct guid fs_guid;
bool have_guid = fs_get_guid(&fs_guid, vol);    // get filesystem UUID
char *label    = fs_get_label(vol);              // get volume label
```

--------------------------------

### Configure Multiboot 1 & 2 Kernels for Limine

Source: https://context7.com/limine-bootloader/limine/llms.txt

Define boot entries for kernels compatible with Multiboot 1 and Multiboot 2 protocols. Specifies kernel path, module paths, command line arguments, and display resolution.

```ini
# Multiboot 1
/GRUB-era kernel (Multiboot 1)
    protocol: multiboot1
    path: boot():/boot/kernel-mb1.elf
    module_path: boot():/boot/module.bin
    module_string: argument string for module
    cmdline: some=option
    resolution: 1024x768x32

# Multiboot 2
/Multiboot2 kernel
    protocol: multiboot2
    path: boot():/boot/kernel-mb2.elf
    module_path: boot():/boot/mod1.bin
    module_string: first module string
    module_path: boot():/boot/mod2.bin
    module_string: second module string
    cmdline: debug=yes
    resolution: 1280x720
    # textmode: yes   # BIOS only

# The multiboot1_info structure passed to the kernel includes:
#   flags, mem_lower/upper, boot_device, cmdline ptr,
#   mods_count/addr, mmap_length/addr, fb_addr/pitch/width/height/bpp
```

--------------------------------

### Manage Framebuffers with Limine (C API)

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for initializing graphical framebuffers, clearing them, and flushing cache. `fb_init` negotiates resolution and obtains framebuffer parameters. `fb_clear` sets the screen to black, and `fb_flush` updates memory.

```c
#include <lib/fb.h>

// Initialise framebuffers at a requested resolution
struct fb_info *fbs = NULL;
size_t fbs_count = 0;
fb_init(&fbs, &fbs_count,
        1920,   // target width  (0 = auto)
        1080,   // target height (0 = auto)
        32,     // bits per pixel
        false); // preserve_screen: keep current contents

if (fbs_count == 0) {
    // Fall back to text mode or EFI console
}
```

```c
// Inspect the first framebuffer
struct fb_info *fb = &fbs[0];
printf("FB: %lux%lu, bpp=%u, pitch=%lu, addr=%p\n",
       fb->framebuffer_width,
       fb->framebuffer_height,
       fb->framebuffer_bpp,
       fb->framebuffer_pitch,
       (void *)(uintptr_t)fb->framebuffer_addr);
```

```c
// Clear framebuffer to black
fb_clear(fb);
```

```c
// Flush a modified region from cache to memory
volatile void *base = (volatile void *)(uintptr_t)fb->framebuffer_addr;
fb_flush(base, fb->framebuffer_pitch * fb->framebuffer_height);
```

--------------------------------

### Enroll BLAKE2B Config Hash for Secure Boot

Source: https://context7.com/limine-bootloader/limine/llms.txt

Embeds a BLAKE2B-512 checksum of the `limine.conf` file into a Limine EFI executable for Secure Boot verification. Use `--reset` to remove an enrolled hash. The EFI binary must be signed with a firmware-trusted key.

```bash
# Compute the BLAKE2B-512 hash of the config file (128 hex characters)
HASH=$(b2sum -l 512 limine.conf | awk '{print $1}')
echo "Hash: $HASH"
```

```bash
# Enroll the hash into the EFI executable
limine enroll-config BOOTX64.EFI "$HASH"
# Expected: "Config file BLAKE2B successfully enrolled."
```

```bash
# Verify enrollment was successful (quiet mode: exit 0 = success)
limine enroll-config --quiet BOOTX64.EFI "$HASH"
```

```bash
# Remove a previously enrolled hash (allows booting without integrity check)
limine enroll-config --reset BOOTX64.EFI
# Expected: "Config file BLAKE2B successfully reset."
```

```bash
# Full Secure Boot workflow
cp /usr/share/limine/BOOTX64.EFI esp/EFI/BOOT/BOOTX64.EFI
cp limine.conf esp/EFI/BOOT/limine.conf
HASH=$(b2sum -l 512 limine.conf | awk '{print $1}')
limine enroll-config esp/EFI/BOOT/BOOTX64.EFI "$HASH"
# Sign with your key:
sbsign --key db.key --cert db.crt --output esp/EFI/BOOT/BOOTX64.EFI esp/EFI/BOOT/BOOTX64.EFI
```

--------------------------------

### Limine Protocol Entry Configuration

Source: https://context7.com/limine-bootloader/limine/llms.txt

Configure a Limine protocol entry for kernels implementing the Limine protocol specification. Supports structured boot information, multiple modules, framebuffer resolution, paging mode, KASLR, and device tree override.

```ini
# Full Limine protocol entry
/My OS Kernel
    protocol: limine
    path: boot():/boot/kernel.elf
    cmdline: debug serial=COM1

    # Multiple modules
    module_path: boot():/boot/initrd.tar
    module_string: Main initrd archive
    module_path: boot():/boot/drivers.ko
    module_string: Extra drivers

    # Framebuffer resolution (width x height x bpp; bpp defaults to 32)
    resolution: 1920x1080x32

    # Paging mode (x86-64/aarch64: 4level or 5level)
    paging_mode: 4level
    # Or constrain with min/max:
    # min_paging_mode: 4level
    # max_paging_mode: 5level

    # KASLR for relocatable ELF/PE kernels (disabled by default)
    kaslr: no
    randomise_hhdm_base: no

    # Override device tree (aarch64/riscv64/loongarch64)
    dtb_path: boot():/boot/custom.dtb
```

--------------------------------

### Load 64-bit ELF Kernel with `elf64_load`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Use this function to load a 64-bit ELF executable into physical memory. It handles segment loading, relocations, and optional KASLR. Ensure the kernel file bytes are read into `elf_data` and `elf_size` before calling.

```c
#include <lib/elf.h>

uint8_t *elf_data = /* read kernel file bytes */;
size_t elf_size   = /* file size */;

uint64_t entry_point, slide;
uint64_t phys_base, virt_base;
uint64_t image_size, image_size_before_bss;
struct mem_range *ranges;
uint64_t ranges_count;
bool is_reloc;

bool ok = elf64_load(
    elf_data, elf_size,
    &entry_point,
    &slide,
    MEMMAP_BOOTLOADER_RECLAIMABLE, // alloc_type
    false,                         // kaslr: randomise slide
    &ranges, &ranges_count,
    &phys_base, &virt_base,
    &image_size, &image_size_before_bss,
    &is_reloc
);

if (!ok) {
    panic(true, "Failed to load ELF kernel.");
}

printf("Entry: %#lx, phys: %#lx, virt: %#lx, size: %lu\n",
       entry_point, phys_base, virt_base, image_size);

```

--------------------------------

### Define and Use Macros in Limine Config

Source: https://context7.com/limine-bootloader/limine/llms.txt

Define custom macros for string substitution and use them in option values. Built-in macros like ${ARCH} and ${FW_TYPE} can be used for conditional entry visibility.

```ini
# Define custom macros
${ROOT}=root=/dev/nvme0n1p2
${COMMON_ARGS}=rw quiet splash loglevel=3
${KERNEL_PATH}=boot():/boot/vmlinuz-linux

# Use macros in options
/Arch Linux
    protocol: limine
    path: ${KERNEL_PATH}
    cmdline: ${ROOT} ${COMMON_ARGS}
    module_path: boot():/boot/initramfs-linux.img

# Conditional entry visibility using built-in macros
/UEFI Shell (UEFI only)
    if_fw_type: UEFI
    protocol: efi
    path: boot():/EFI/Shell/Shell.efi

/Legacy option (x86 BIOS only)
    if_fw_type: BIOS
    if_arch: ia-32 x86-64
    protocol: bios
    drive: 1
    partition: 1

# Architecture-specific entry
/ARM64 Kernel
    if_arch: aarch64
    protocol: limine
    path: boot():/boot/Image
    cmdline: ${ROOT} ${COMMON_ARGS}
    dtb_path: boot():/boot/my-board.dtb
```

--------------------------------

### Linux Protocol Entry Configuration

Source: https://context7.com/limine-bootloader/limine/llms.txt

Configure a Linux protocol entry for loading a standard Linux kernel. Supports initramfs/initrd modules, kernel command line, framebuffer resolution, and device tree override for non-x86 platforms. Includes options for BIOS text mode boot.

```ini
/Ubuntu 24.04
    protocol: linux
    path: boot():/boot/vmlinuz-6.8.0-generic
    module_path: boot():/boot/initrd.img-6.8.0-generic
    cmdline: root=UUID=3a6b1c2d-... ro quiet splash
    resolution: 1920x1080

# BIOS text mode boot
/Ubuntu (text mode)
    protocol: linux
    path: boot(2):/vmlinuz
    module_path: boot(2):/initrd.img
    cmdline: root=/dev/sda2 ro text
    textmode: yes

# aarch64 with device tree
/ARM64 Linux
    protocol: linux
    path: boot():/Image
    module_path: boot():/initrd.img
    cmdline: root=/dev/mmcblk0p2 rw
    dtb_path: boot():/rpi4.dtb
```

--------------------------------

### Internal filesystem abstraction

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for reading files from any Limine-supported volume and filesystem. It provides a uniform `struct file_handle` abstraction for local disk, memory, and network files.

```APIDOC
## `fopen` / `fread` / `fclose` — Internal filesystem abstraction

Internal C API for reading files from any Limine-supported volume and filesystem (FAT12/16/32, ISO9660). All boot protocol loaders use these functions. The `struct file_handle` abstraction covers local disk files, memory files, and PXE/TFTP files uniformly.

```c
#include <fs/file.h>
#include <lib/part.h>

// Open a file on a specific volume
struct volume *vol = volume_get_by_coord(false, 0, 1); // drive 0, partition 1
struct file_handle *fh = fopen(vol, "/boot/vmlinuz");
if (fh == NULL) {
    panic(true, "Could not open kernel file.");
}

// Read the entire file into a buffer
uint8_t *buf = alloc_and_read(fh);  // fh->size bytes needed

// Or read a specific range
uint8_t header[64];
uint64_t bytes_read = fread(fh, header, 0, sizeof(header));
if (bytes_read != sizeof(header)) {
    panic(true, "Short read on kernel header.");
}

// Access metadata
uint64_t file_size = fh->size;
bool is_network = fh->pxe;

fclose(fh);

// Filesystem-level helpers
struct guid fs_guid;
bool have_guid = fs_get_guid(&fs_guid, vol);    // get filesystem UUID
char *label    = fs_get_label(vol);              // get volume label
```
```

--------------------------------

### Framebuffer management

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for initializing graphical framebuffers, clearing them, and flushing cache lines. Used by boot protocols to negotiate display resolutions and obtain framebuffer parameters.

```APIDOC
## `fb_init` / `fb_clear` / `fb_flush` — Framebuffer management

Internal C API for initialising graphical framebuffers (via UEFI GOP or BIOS VBE), clearing them, and flushing cache lines. Boot protocols use `fb_init` to negotiate a display resolution and obtain framebuffer parameters to pass to the kernel.

```c
#include <lib/fb.h>

// Initialise framebuffers at a requested resolution
struct fb_info *fbs = NULL;
size_t fbs_count = 0;
fb_init(&fbs, &fbs_count,
        1920,   // target width  (0 = auto)
        1080,   // target height (0 = auto)
        32,     // bits per pixel
        false); // preserve_screen: keep current contents

if (fbs_count == 0) {
    // Fall back to text mode or EFI console
}

// Inspect the first framebuffer
struct fb_info *fb = &fbs[0];
printf("FB: %lux%lu, bpp=%u, pitch=%lu, addr=%p\n",
       fb->framebuffer_width,
       fb->framebuffer_height,
       fb->framebuffer_bpp,
       fb->framebuffer_pitch,
       (void *)(uintptr_t)fb->framebuffer_addr);

// Clear framebuffer to black
fb_clear(fb);

// Flush a modified region from cache to memory
volatile void *base = (volatile void *)(uintptr_t)fb->framebuffer_addr;
fb_flush(base, fb->framebuffer_pitch * fb->framebuffer_height);
```
```

--------------------------------

### Iterate Partitions with `volume_iterate_parts`

Source: https://context7.com/limine-bootloader/limine/llms.txt

Iterates through all partitions of a given volume. Inside the loop, `_PART` is a `struct volume *` pointing to the current partition.

```c
// Iterate all partitions of a drive
volume_iterate_parts(vol, {
    // _PART is a struct volume * pointing to each partition
    struct guid part_guid;
    if (gpt_get_guid(&part_guid, _PART)) {
        char guid_str[37];
        guid_to_string(&part_guid, guid_str);
        printf("Partition GUID: %s\n", guid_str);
    }
});

```

--------------------------------

### Enable Measured Boot with TPM 2.0

Source: https://context7.com/limine-bootloader/limine/llms.txt

Enable measured boot to extend TPM 2.0 PCRs with boot policy and file contents. This follows UAPI Linux TPM PCR Registry conventions. The captured event log is passed to the kernel.

```ini
# Enable measured boot
measured_boot: yes

/Measured Linux Boot
    protocol: linux
    path: boot():/boot/vmlinuz#<sha512-hash>
    module_path: boot():/boot/initrd.img#<sha512-hash>
    cmdline: root=/dev/sda2 ro

# PCR 8 will be extended with (in order):
#   "cmdline: root=/dev/sda2 ro"          (strlen bytes, no NUL)
#   "path: boot():/boot/vmlinuz"           (hash suffix stripped)
#   "module_path: boot():/boot/initrd.img" (hash suffix stripped)
#
# PCR 9 will be extended with (in order):
#   "limine_cfg": raw bytes of limine.conf on disk
#   "path: boot():/boot/vmlinuz": full kernel image bytes
#   "module_path: boot():/boot/initrd.img": full initrd bytes

# To verify PCR values externally:
# tpm2_pcrread sha256:8+9
# Compare against: sha256(cmdline_string_no_nul), etc.
```

--------------------------------

### Parse Limine Config Entry Values (C API)

Source: https://context7.com/limine-bootloader/limine/llms.txt

Internal C API for reading values from a parsed Limine config entry body. Use `config_get_value` to read the first occurrence of a key or iterate through repeated keys. `config_get_tuple` reads paired keys.

```c
#include <lib/config.h>

// Read the first occurrence of a key from an entry's config body
char *kernel_path = config_get_value(entry->body, 0, "PATH");
if (kernel_path == NULL) {
    panic(true, "Missing 'path' option in entry.");
}
```

```c
// Iterate all module_path entries (index 0, 1, 2, ...)
for (size_t i = 0; ; i++) {
    char *module_path = config_get_value(entry->body, i, "MODULE_PATH");
    if (module_path == NULL) break;  // no more entries

    char *module_str = config_get_value(entry->body, i, "MODULE_STRING");
    // module_str may be NULL if not specified

    load_module(module_path, module_str);
}
```

```c
// Read a paired tuple (key1 at index i, key2 at index i)
struct conf_tuple res = config_get_tuple(entry->body, 0,
                                         "MODULE_PATH", "MODULE_STRING");
// res.value1 = module path, res.value2 = module string (may be NULL)
```

--------------------------------

### elf64_load — ELF kernel loader

Source: https://context7.com/limine-bootloader/limine/llms.txt

Loads a 64-bit ELF executable into physical memory, resolves segments and relocations, and optionally randomizes the load address. It returns the entry point, base addresses, and memory ranges.

```APIDOC
## `elf64_load` — ELF kernel loader

Internal C function that loads a 64-bit ELF executable (ET_EXEC or relocatable ET_DYN) into physical memory, resolving PT_LOAD segments, applying RELR/RELA/GLOB_DAT/JUMP_SLOT relocations, and optionally randomising the kernel load address (KASLR). Returns the entry point, physical and virtual base addresses, and a list of memory ranges for the page table builder.

```c
#include <lib/elf.h>

uint8_t *elf_data = /* read kernel file bytes */;
size_t elf_size   = /* file size */;

uint64_t entry_point, slide;
uint64_t phys_base, virt_base;
uint64_t image_size, image_size_before_bss;
struct mem_range *ranges;
uint64_t ranges_count;
bool is_reloc;

bool ok = elf64_load(
    elf_data, elf_size,
    &entry_point,
    &slide,
    MEMMAP_BOOTLOADER_RECLAIMABLE, // alloc_type
    false,                         // kaslr: randomise slide
    &ranges, &ranges_count,
    &phys_base, &virt_base,
    &image_size, &image_size_before_bss,
    &is_reloc
);

if (!ok) {
    panic(true, "Failed to load ELF kernel.");
}

printf("Entry: %%#lx, phys: %%#lx, virt: %%#lx, size: %%lu\n",
       entry_point, phys_base, virt_base, image_size);

// Load a named ELF section (e.g., .limine_requests)
uint8_t section_data[4096];
bool found = elf64_load_section(elf_data, elf_size, section_data,
                                ".limine_requests", sizeof(section_data), slide);
```
```