SchOS/include/arch/schboot.h

// SPDX-License-Identifier: GPL-2.0-or-later
#pragma once
#ifndef SCHBOOT_H
#define SCHBOOT_H

// The loader/kernel hand-off, in one place.
//
// Included by kernel/arch/x86_64/entry.S and by boot/uefi/main.c, so the two
// cannot disagree about the magic or the layout. Defining it twice is exactly
// how a loader ends up scanning for bytes the kernel never wrote — the first
// attempt here searched for "SCH6" while the assembler had stored 0x53434836,
// which lands in the file as "6HCS".
//
// Keep this header assembler-safe: no typedefs, no structs outside the C
// guard, nothing entry.S cannot preprocess.

// Scanned for in the first 16 KB of the kernel image, 8-byte aligned, exactly
// as the BIOS loader scans for the multiboot magic. Followed by a little-endian
// 64-bit physical address: the kernel's 64-bit entry point.
//
// The values spell "SCH6" "4BOO" when stored little-endian, which is what
// makes them findable by eye in a hex dump of the image.
#define SCH64_MAGIC0 0x36484353   /* "SCH6" */
#define SCH64_MAGIC1 0x4f4f4234   /* "4BOO" */

// ---------------------------------------------------------------------------
// The hand-off block.
//
// One page of low memory that a loader fills in and the kernel reads. Every
// field below was previously #defined in whichever file happened to need it --
// five of them, across two loaders and two kernel files -- which is the same
// hazard as defining the magic twice, only quieter: nothing breaks until one
// copy moves.
//
// 0x30000 is clear of stage2 (loaded at 0x7E00 and well under 0xA000), the
// multiboot kernel-search buffer at 0x10000-0x14000, and the kernel's own load
// address at KERNPHYS, 16 MB.
//
// Both loaders write it, so a field's meaning must not depend on which one did.
// Where they genuinely differ -- the BIOS path knows what medium it booted
// from, UEFI does not -- the field is defined as "0 when unknown" rather than
// left for the reader to guess.
#define SCHBOOT_BASE          0x30000

// A VBE mode info block, 256 bytes. The UEFI loader fills the same four fields
// out of GOP rather than translating a structure it never saw, so the kernel
// cannot tell which firmware booted it.
#define SCHBOOT_VBE_INFO      (SCHBOOT_BASE + 0x000)
#define SCHBOOT_VBE_STRIDE    (SCHBOOT_VBE_INFO + 16)   /* uint16, bytes/line */
#define SCHBOOT_VBE_WIDTH     (SCHBOOT_VBE_INFO + 18)   /* uint16 */
#define SCHBOOT_VBE_HEIGHT    (SCHBOOT_VBE_INFO + 20)   /* uint16 */
#define SCHBOOT_VBE_BPP       (SCHBOOT_VBE_INFO + 25)   /* uint8  */
#define SCHBOOT_VBE_LFB       (SCHBOOT_VBE_INFO + 40)   /* uint32, physical */

// Non-zero if the loader was asked for a verbose boot.
#define SCHBOOT_VERBOSE_FLAG  (SCHBOOT_BASE + 0x100)

// What the system booted from. SCHBOOT_MEDIA_CD matters because the ISO path
// reads through ATAPI rather than ATA; 0 means "not stated", which is what the
// UEFI loader leaves, since it does not read the kernel through either.
#define SCHBOOT_MEDIA_FLAG    (SCHBOOT_BASE + 0x101)

// Remote debugging, chosen at the boot menu.
//
// A byte, set by the loader when somebody picks it out of the F8 menu, read by
// the kernel and published as /proc/bootdebug so that schinit can act on it.
//
// **It exists because the machines that need debugging are the ones that
// cannot be debugged.** A laptop has no serial port, so a kernel that stops
// before it can draw has nowhere to say why; the answer is a debugger reachable
// over the network, and the answer to "when should that be listening" cannot be
// "always" -- schdbgd can read the process table, and a listener nobody asked
// for is not a thing to ship. Choosing it at the boot menu is a deliberate act
// by somebody standing at the machine, which is the strongest consent this
// system can ask for and the weakest one that is any use on hardware that will
// not boot.
//
// Zero on every ordinary boot, including every boot of a build made without
// DEBUG=1 -- where the menu entry does not exist and nothing can set it.
#define SCHBOOT_DEBUG_FLAG    (SCHBOOT_BASE + 0x102)
#define SCHBOOT_MEDIA_CD      1

// Real-mode spelling of the same byte, for cdboot.S which has no 32-bit
// addressing yet. Segment and offset, not a flat address.
#define SCHBOOT_MEDIA_SEG     0x3000
#define SCHBOOT_MEDIA_OFF     0x101

// The E820 memory map: a uint32 count at BASE+0x200, and the entries, 24 bytes
// each, in a page-and-a-half of their own from BASE+0x1000.
//
// The entries used to sit between the count and the RSDP field, which left
// room for 40. A laptop's UEFI map is 60 to 150 descriptors, and even after
// the loader merges neighbours of the same type the RAM above 4 GB -- which
// the firmware lists last -- was what fell off the end: a 16 GB machine came
// up with 2 or 3 of it. 256 is more than any map seen merges to, and the area
// it takes, 0x31000-0x32800, is clear of everything else at BASE.
#define SCHBOOT_E820_COUNT    (SCHBOOT_BASE + 0x200)
#define SCHBOOT_E820_MAP      (SCHBOOT_BASE + 0x1000)
#define SCHBOOT_E820_MAX      256

// Where the loader leaves the ACPI RSDP, as a little-endian 64-bit physical
// address. Zero means "not provided, go and look for it yourself".
//
// The kernel's own search scans the EBDA and 0xE0000-0x100000, which is a BIOS
// convention. UEFI publishes the RSDP in its configuration table instead and is
// under no obligation to leave a copy anywhere in particular; OVMF does not.
// Without it the kernel finds no MADT, so no IOAPIC, so no interrupt routing --
// the machine boots to a prompt on polled serial output and then ignores every
// key, which looks like a broken console rather than a missing table.
//
#define SCHBOOT_RSDP_ADDR     (SCHBOOT_BASE + 0x600)

// A console typeface, read off the boot volume by the loader.
//
// Zero length means "there was none" and the kernel uses the one linked into
// its own image. That fallback is not a degraded mode: an early panic has to
// be readable, and the only font guaranteed to exist before any filesystem
// does is the one in the image.
//
// **Loaded by the loader rather than by the kernel**, which is the whole
// design decision here. The kernel could read the file itself once the root
// filesystem is mounted -- but the console is drawing before that, so
// switching then means re-measuring the cell and re-laying out every terminal
// mid-boot. That wipes the kernel log off the screen at exactly the moment a
// machine being brought up for the first time needs it. Choosing the font
// before the first line is drawn costs one file read and changes nothing
// afterwards.
//
// The pages are allocated as EfiReservedMemoryType, so the E820 handoff marks
// them reserved and the page allocator never hands them out -- the font is
// used *in place*, and nothing in the kernel has to find room for 100 KB of
// contiguous memory.
#define SCHBOOT_FONT_ADDR     (SCHBOOT_BASE + 0x608)   /* uint64, physical */
#define SCHBOOT_FONT_LEN      (SCHBOOT_BASE + 0x610)   /* uint32, bytes    */

// The display, described by the loader in its own words rather than in VBE's.
//
// The VBE mode-info block above is a *BIOS* structure, and the UEFI loader has
// been filling one in because the kernel already knew how to read it. Three of
// its fields cannot describe a real machine:
//
//   - the framebuffer address is **32 bits**. A laptop with a discrete GPU
//     routinely puts its aperture above 4 GB, and the loader was casting
//     `(UINT32)gop->Mode->FrameBufferBase` -- so the splash was drawn into a
//     truncated address, nothing appeared, and the firmware's own text cursor
//     was left blinking on an otherwise black screen. That is the whole of the
//     "it boots to a white underscore" report.
//   - the stride is 16 bits, which runs out at 16383 pixels of 32-bit colour.
//   - there is nowhere to say whether the pixels are RGBX or BGRX, and GOP
//     reports both.
//
// So the UEFI path says it properly. The VBE block is still written, for the
// BIOS loader and for any kernel that has not been taught to look here; a
// non-zero FB_BASE means this block is authoritative and the other is a copy.
//
// FB_BASE is *physical*, and deliberately not translated: above 4 GB it is
// outside the kernel's direct map and has to be ioremap()ed, which cannot
// happen until there are page tables to put it in.
#define SCHBOOT_FB_BASE       (SCHBOOT_BASE + 0x618)   /* uint64, physical */
#define SCHBOOT_FB_SIZE       (SCHBOOT_BASE + 0x620)   /* uint64, bytes    */
#define SCHBOOT_FB_WIDTH      (SCHBOOT_BASE + 0x628)   /* uint32, pixels   */
#define SCHBOOT_FB_HEIGHT     (SCHBOOT_BASE + 0x62C)   /* uint32, pixels   */
#define SCHBOOT_FB_STRIDE     (SCHBOOT_BASE + 0x630)   /* uint32, bytes    */
// 0 = RGBX8888, 1 = BGRX8888 -- the two GOP formats with a linear layout, in
// EFI's own numbering. Everything in the kernel draws 0x00RRGGBB, which is
// BGRX in memory, so format 0 is the one that needs its channels swapped.
#define SCHBOOT_FB_FORMAT     (SCHBOOT_BASE + 0x634)   /* uint32           */

// The SMBIOS entry point, from the UEFI configuration table: the 64-bit
// "_SM3_" one when the firmware has it, else the 32-bit "_SM_". Zero means
// none was handed over, and the kernel scans 0xF0000-0xFFFFF the BIOS way.
// It is what names the machine -- vendor, model, firmware version -- in
// /sys/class/dmi/id, and on UEFI the scan alone finds nothing on most laptops.
#define SCHBOOT_SMBIOS_ADDR   (SCHBOOT_BASE + 0x638)   /* uint64, physical */
// SCHBOOT_EFI_MAGIC when the UEFI loader booted this kernel, which is what
// /sys/firmware/efi existing means on Linux.
#define SCHBOOT_EFI_FLAG      (SCHBOOT_BASE + 0x640)   /* uint32           */
#define SCHBOOT_EFI_MAGIC     0x21494645u              /* "EFI!"           */

#ifndef __ASSEMBLER__

struct sch64_header {
    unsigned int       magic0;    // SCH64_MAGIC0
    unsigned int       magic1;    // SCH64_MAGIC1
    unsigned long long entry;     // physical address, entered in long mode
};

#endif /* !__ASSEMBLER__ */

#endif /* SCHBOOT_H */