boot: separate BIOS from UEFI

boot/bios/ now holds the MBR, the El Torito stub and the real-mode stage
2; boot/uefi/ is empty and documented.

Separate directories rather than #ifdefs, because the two share almost
nothing. A BIOS loader lives in 16-bit real mode, reaches the firmware
through software interrupts, and walks itself up into long mode. A UEFI
loader is a 64-bit PE that the firmware has already placed in long mode
with paging on, calling services through a table of function pointers.
What they do share is the hand-off contract, which boot/README.md now
writes down: ELF segments placed, long mode, a 24-byte-entry memory map
at E820_MAP_ADDR, framebuffer geometry at VBE_INFO_ADDR.

That contract is the point of documenting it now. UEFI's GetMemoryMap
returns EFI_MEMORY_DESCRIPTORs, and the right move is to translate them
into the entries kernel/arch/x86_64/e820.c already parses rather than
teach the kernel a second format.

Build output paths under $(BUILD)/boot are unchanged; only sources moved.

boot/README.md

@@ -0,0 +1,64 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Booting SchOS
+
+Two firmware paths, kept apart on purpose:
+
+```
+boot/
+  bios/    legacy BIOS: MBR, El Torito CD stub, real-mode stage 2
+  uefi/    UEFI application (not written yet)
+```
+
+They are separate directories rather than `#ifdef`s in one because they share
+almost nothing. A BIOS loader lives in 16-bit real mode, talks to the firmware
+through software interrupts, and has to walk itself up into long mode. A UEFI
+loader is a 64-bit PE executable that the firmware has *already* placed in long
+mode with paging on, and it asks for services by calling through a table of
+function pointers. The only things genuinely in common are the logo bitmap, the
+menu's appearance, and the hand-off contract below.
+
+## What the loader must hand the kernel
+
+Whichever path runs, the kernel expects the same things. This is the contract;
+a second loader is correct exactly when it satisfies it.
+
+| | Where | Notes |
+|---|---|---|
+| Kernel image | loaded per its ELF program headers | entry at `entry64` |
+| CPU state | long mode, paging on, interrupts off | BIOS path builds this itself |
+| Memory map | `E820_MAP_ADDR`, 24-byte entries, count at `E820_COUNT_ADDR` | `kernel/arch/x86_64/e820.c` reads it |
+| Framebuffer | `VBE_INFO_ADDR` | address, pitch, width, height, depth |
+| Verbose flag | `BOOT_VERBOSE_FLAG_ADDR` | set by the F8 menu |
+
+The addresses are defined once, in `include/memlayout.h` and
+`boot/bios/stage2main.c`. A UEFI loader must fill the same structures — the
+kernel does not care which firmware produced them, and that is what keeps the
+split cheap.
+
+`e820.c` reads a *BIOS* memory map. UEFI hands out a different structure
+(`EFI_MEMORY_DESCRIPTOR`, from `GetMemoryMap`), so the UEFI loader has to
+translate it into the same 24-byte entries rather than inventing a second
+format for the kernel to learn.
+
+## The BIOS path today
+
+1. **`bios/bootasm.S`** — the literal MBR sector. Signed to 512 bytes by
+   `tools/sign.pl`, loads stage 2 from LBA 1 and jumps.
+2. **`bios/cdboot.S`** — the same job for optical media, as an El Torito
+   no-emulation image. Separate because the loader never uses INT 13h and so
+   needs a real ATAPI read.
+3. **`bios/stage2.S`** — collects the E820 map, sets a VBE mode, enters
+   protected mode.
+4. **`bios/stage2main.c`** — the boot menu and splash, then loads the kernel
+   and enters long mode.
+
+`STAGE2_SECTORS` is defined **once**, in the Makefile, and passed to both the
+assembler and the `dd` that writes the image. It used to be written out by hand
+in five places and silently truncated the loader when they disagreed.
+
+## Why UEFI is worth doing
+
+Everything since roughly 2012 boots UEFI by default, and Secure Boot machines
+will not run the BIOS path at all without firmware settings most people never
+touch. The BIOS loader stays regardless: it is what QEMU's default machine and
+older hardware use, and it costs nothing to keep once the two are separated.

boot/bios/stage2main.c

@@ -46,7 +46,7 @@ _Static_assert(0x7E00 + STAGE2_SECTORS * 512 <= 0x10000,
 // kind of thing that turns into one later.
 #define BOOT_VERBOSE_FLAG_ADDR (VBE_INFO_ADDR + 0x100)
 
-// Set by boot/cdboot.S when we were booted from optical media. One byte past
+// Set by boot/bios/cdboot.S when we were booted from optical media. One byte past
 // the verbose flag, for the same reason that one sits where it does: clear of
 // the 256-byte VBE mode info block at VBE_INFO_ADDR.
 #define BOOT_MEDIA_FLAG_ADDR   (VBE_INFO_ADDR + 0x101)

boot/uefi/README.md

@@ -0,0 +1,28 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# UEFI loader
+
+Not written yet. This directory exists so the BIOS path could be moved into
+`boot/bios/` without pretending the split was hypothetical.
+
+See `../README.md` for the hand-off contract a loader has to satisfy. The
+short version: the kernel wants long mode with paging on, its ELF segments
+placed, a 24-byte-entry E820-shaped memory map, and framebuffer geometry — and
+it does not care which firmware produced them.
+
+What this will need, in rough order:
+
+1. A PE/COFF target. clang can emit one directly
+   (`--target=x86_64-unknown-windows -fuse-ld=lld-link`), so no new toolchain:
+   the same LLVM install already builds every other target here.
+2. The handful of UEFI structures actually used — the system table, boot
+   services, `LOADED_IMAGE`, `SIMPLE_FILE_SYSTEM`, `GRAPHICS_OUTPUT`. Written
+   from the specification rather than by importing gnu-efi or EDK II, which is
+   both a licence question and a large dependency for something this small.
+3. `GetMemoryMap` translated into the same 24-byte entries `e820.c` already
+   parses. Not a second format for the kernel to learn.
+4. `ExitBootServices` before touching the memory it described.
+5. Graphics Output Protocol for the framebuffer, filling the same
+   `VBE_INFO_ADDR` structure the BIOS path fills.
+
+The image goes at `EFI/BOOT/BOOTX64.EFI` on a FAT ESP, which also means the
+ISO gains an El Torito EFI entry alongside the BIOS one it already has.