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.