From 76103215711d268b4b02f62e900f2be3032cf295 Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Fri, 31 Jul 2026 02:18:30 +0200
Subject: Initial commit: raisernics toy kernel

- Bare-metal x86_64 UEFI kernel (PE32+, no libc)
- GOP framebuffer + 8x16 bitmap font
- PS/2 keyboard (polling, scancode set 1)
- UART 16550 serial driver (COM1, 115200 8N1)
- Bump allocator as #[global_allocator] (alloc::String, Vec, format!)
- UEFI memory map capture (static buffer, ADR 0001)
- Shell with 7 commands (help, echo, clear, hello, info, mem, halt)
- Dual output: GOP framebuffer + serial console
- Makefile: run, run-gui, debug, release, image targets
- tools/: qemu.sh, boot-image.sh, debug-kernel.py
---
 CONTEXT.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 CONTEXT.md

(limited to 'CONTEXT.md')

diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..283467a
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,100 @@
+# CONTEXT.md — raisernics Kernel Glossary
+
+## raisernics
+
+Custom x86_64 kernel for the RNG ecosystem.  Toy project — self-contained,
+no strict userspace separation, TempleOS-inspired design philosophy.
+Built in Rust, compiled for the `x86_64-unknown-uefi` target (nightly).
+
+## Boot interface
+
+The kernel is a **PE32+ EFI application** loaded via UEFI `LoadImage`/`StartImage`.
+The existing bootloader (rsbl) loads us from `\bzImage` and passes the UEFI
+system table.  No bootloader changes needed.
+
+## Output strategy
+
+Two-phase console model:
+
+- **Phase 1 (boot services alive):** UEFI `con_out->OutputString()` — works
+  with whatever UEFI firmware routes (serial + framebuffer).
+- **Phase 2 (native):** Raw serial UART 16550 driver on COM1 (I/O port
+  `0x3F8`).  Activated after `ExitBootServices` when we own the hardware.
+
+## Dependency philosophy
+
+Aligns with RNG philosophy: minimal dependencies.  Freestanding Rust,
+no libc, no external crates at the kernel/core level.  UEFI protocol
+structs are hand-defined (not from `uefi-rs` crate) to stay lightweight.
+
+## Paging strategy
+
+Long mode mandates paging (`CR0.PG = 1`), so we accept that tax but keep it
+simple.  Retain UEFI's identity-mapped 4-level page tables.  No higher-half,
+no demand paging, no guard pages.  When the kernel needs more physical pages,
+entries are added 1:1 to the existing page tables.
+
+## Physical memory
+
+Before `ExitBootServices`, the kernel reads the UEFI memory map to know
+which physical regions are free.  Post-`ExitBootServices`, a simple physical
+page allocator (bitmap or free-stack) manages free pages.  A bump allocator
+serves as the initial kernel heap.
+
+## Input strategy
+
+**PS/2 keyboard polling.** Port I/O to `0x60`/`0x64`.  Scancode set 1
+(US QWERTY layout in the initial build).  No interrupts — polling loop
+inside the shell.
+
+## Display strategy
+
+Two-phase model matching output:
+
+- **Phase 1:** UEFI `con_out->OutputString()` (framebuffer + serial handled
+  by firmware).
+- **Phase 2:** GOP (Graphics Output Protocol) framebuffer obtained before
+  `ExitBootServices`, driven by a built-in 8×16 bitmap font.  Text rendered
+  by drawing glyphs directly into the framebuffer.
+
+The framebuffer address stays valid after `ExitBootServices` — the GPU's
+linear frame buffer is system memory that we own once boot services are gone.
+
+## Keyboard layout
+
+Scancode set 1, US QWERTY layout.  Hardcoded scancode→ASCII table.
+Other layouts can be added later by swapping the translation table.
+
+## Development loop
+
+Standalone project — no integration with the RNG initramfs build system.
+Testing via QEMU with OVMF.  The kernel PE binary is placed on a FAT
+image as `\bzImage` (matching rsbl's expected path).
+
+## Project layout
+
+Single Rust crate (`x86_64-unknown-uefi` target).  Module breakdown:
+
+- `main.rs` — entry point, panic handler, top-level init
+- `uefi.rs` — UEFI protocol type definitions
+- `serial.rs` — UART 16550 driver
+- `paging.rs` — identity page table helpers
+- `memory.rs` — physical page allocator + heap
+- `gop.rs` — framebuffer access and text rendering
+- `font.rs` — 8×16 bitmap font data
+- `ps2.rs` — PS/2 keyboard driver (polling)
+- `shell.rs` — command loop and built-in commands
+
+## Milestone status (v0.1)
+
+✅ **Booting** — kernel loads via rsbl, prints banner via UEFI console
+✅ **ExitBootServices** — memory map captured via static `.bss` buffer
+  (see `docs/adr/0001-static-buffer-for-memory-map.md`)
+✅ **Serial** — UART 16550 at COM1, 115200 8N1
+✅ **Framebuffer** — GOP located, 8×16 bitmap font renders text
+✅ **Keyboard** — PS/2 polling, scancode set 1, US QWERTY
+✅ **Shell** — commands: `help`, `echo`, `clear`, `hello`, `info`, `mem`, `halt`
+
+## Target audience
+
+Learning exercise and toy.  Not a Linux replacement.  Not POSIX-compatible.
-- 
cgit v1.2.3