08a1a9033a
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.
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
<!-- 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.
|