MVH Kernel Boot Requirements: Bootloader Setup Guide

Bootloader prerequisites for MVH Kernel: 64-bit Long Mode, identity-mapped first GiB of RAM, total memory size in KiB, and the kernel entry point symbol.

Before you transfer control to MVH Kernel, your bootloader must satisfy three hard prerequisites. The kernel performs no fallback detection and no self-recovery for any of them — if any requirement is unmet when execution reaches _kernel64_start, the CPU will fault. This page describes each requirement, explains what you must pass at the entry point, and shows how any x86_64 bootloader capable of loading an ELF64 image can satisfy all three.

Do not jump to _kernel64_start without satisfying all three requirements listed below. The kernel does not check whether it is in Long Mode, does not attempt to build its own identity map, and does not fall back gracefully if the memory-size argument is zero or missing. Violating any requirement will result in an immediate CPU fault.

---

Kernel Binary Details

Property	Value
Architecture	x86_64
Binary format	ELF64
Entry point symbol	_kernel64_start
Version	1.1.2

Load the MVH Kernel ELF64 image with your bootloader’s standard ELF loader, then resolve the _kernel64_start symbol from the ELF header to find the entry address. Do not hard-code a load address — always read it from the ELF program headers.

---

Requirements

1. x86_64 Long Mode

   The CPU must already be running in 64-bit Long Mode (IA-32e mode) before you call the kernel entry point. This means:

   • A valid Global Descriptor Table (GDT) is loaded with a 64-bit code segment.
   • The CPU is executing with CS pointing to that 64-bit code segment descriptor.
   • CR0.PE (Protected Mode Enable) and CR0.PG (Paging) are both set.
   • EFER.LME and EFER.LMA are both set.

   Most modern bootloaders (GRUB2 with multiboot2, Limine, custom UEFI stubs) enter Long Mode automatically before handing off to a 64-bit kernel. If you are writing a custom bootloader, complete the full Long Mode transition sequence — real mode → protected mode → Long Mode — before jumping to the kernel.

2. Identity-Mapped First GiB

   The first 1 024 MiB (1 GiB) of physical memory must be identity-mapped in the active page tables before you enter the kernel. An identity map means that for every physical address P in [0, 1 GiB), the virtual address P must resolve to physical address P.

   MVH Kernel’s PMM and VMM initialisation code accesses its own data structures through virtual addresses that equal their physical addresses. If the identity map is absent or incomplete, the very first kernel memory access will page-fault before the kernel has had a chance to install its own page tables.

   You may map the first GiB as a single 1 GiB huge page, as 512 × 2 MiB large pages, or as 262 144 × 4 KiB pages — the kernel does not require any particular granularity. After VMM initialisation the kernel rebuilds the page tables under its own control; your bootloader mappings only need to survive until vmm_init completes.

3. Boot Memory Size in KiB

   You must supply the total usable physical RAM in KiB to the kernel. The PMM’s pmm_init function receives this value as its first argument (uint64_t memory_kib) and uses it to size the page-frame bitmap. If you pass zero, the PMM will mark no pages as available and every subsequent pmm_alloc_pages call will fail, causing the kernel to panic during heap or VMM initialisation.

   How you deliver this value depends on your bootloader protocol — see the example below.

---

Passing the Memory Size

The mechanism for passing memory_kib to the kernel depends on your bootloader protocol. The examples below show two common approaches.

GRUB2 / Multiboot2 (C stub)

// In your multiboot2 entry stub, parse the memory map tag
// and accumulate usable RAM before calling the kernel.
#include <multiboot2.h>

extern void _kernel64_start(uint64_t memory_kib);

void multiboot2_entry(uint32_t magic, struct multiboot_info *info)
{
    uint64_t usable_kib = 0;

    struct multiboot_tag *tag = (struct multiboot_tag *)(info + 1);
    while (tag->type != MULTIBOOT_TAG_TYPE_END) {
        if (tag->type == MULTIBOOT_TAG_TYPE_MMAP) {
            struct multiboot_tag_mmap *mmap = (struct multiboot_tag_mmap *)tag;
            multiboot_memory_map_t *entry = mmap->entries;
            while ((uint8_t *)entry < (uint8_t *)mmap + mmap->size) {
                if (entry->type == MULTIBOOT_MEMORY_AVAILABLE)
                    usable_kib += entry->len / 1024;
                entry = (multiboot_memory_map_t *)
                    ((uint8_t *)entry + mmap->entry_size);
            }
        }
        tag = (struct multiboot_tag *)
            ((uint8_t *)tag + ((tag->size + 7) & ~7));
    }

    _kernel64_start(usable_kib);
}

Always derive memory_kib from your bootloader’s memory map rather than from a hard-coded constant. The PMM uses this value to size internal structures; an under-count wastes physical RAM, and an over-count can cause the PMM to mark non-existent or reserved pages as available.

---

What the Kernel Initialises After Entry

Once your bootloader transfers control to _kernel64_start with all three requirements met, MVH Kernel performs the following initialisation sequence automatically — you do not need to call any of these steps yourself:

1. HAL — initialises platform hardware (VGA, serial, PS/2, PCI, RTC, PIT).
2. PMM — builds the physical page-frame bitmap from memory_kib.
3. VMM — installs the kernel page tables with security protections.
4. Kernel Heap — initialises the 1 MiB coalescing heap.
5. Kernel Log — starts the structured ring log.
6. VFS + RAMFS — mounts the volatile RAM filesystem as root.
7. Device Manager — registers all built-in drivers.
8. Interrupt Layer — loads the IDT, remaps the 8259 PIC, and starts the 100 Hz PIT.
9. Interactive Shell — enters the command loop and waits for keyboard input.

---

Compatible Bootloaders

Any x86_64 bootloader that can load an ELF64 binary and enter Long Mode before the handoff is compatible. Tested and recommended options include:

Bootloader	Protocol	Notes
GRUB2	Multiboot2	Use a 64-bit multiboot2 entry stub; GRUB enters Long Mode automatically
Limine	Limine boot protocol	Native 64-bit entry; provides a clean memory map API
Custom UEFI stub	Any	UEFI already runs in Long Mode; parse EFI_MEMORY_DESCRIPTOR for usable RAM
Custom bare-metal loader	Any	Implement Long Mode transition and identity map manually before the jump