Merge pull request 'feature/boot.mgr' (#71) from feature/boot.mgr into develop

Reviewed-on: #71
Reviewed-by: Aaron Hance <[email protected]>

doc/src/app/app.mgr.md

@@ -17,6 +17,10 @@ Central initialization manager for all baked-in terminal programs and kernel-lev
 - `core.version`, `arch.x86.cpu`
 - `app.diskcmd`, `driver.bus.usb.core`, `app.diskutil`, `app.notepad`, `app.partcmd`, `app.volcmd`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `app.mgr` at the `late` barrier.
+
 ## Functions and Procedures
 
 ### init

doc/src/app/wasm/app.wasm.md

@@ -0,0 +1,28 @@
+# app.wasm
+
+WebAssembly VM backend initialiser.
+
+## Overview
+
+This unit initialises the Wasuro WebAssembly virtual machine backend. It wires up the VM's character output to the syslog interface and calls the main `wasm_init` entry point.
+
+## Boot Registration
+
+Registered with `boot.mgr` as `app.wasm` at the `final` barrier.
+
+## Dependencies
+
+- `boot.mgr`
+- `io.syslog`
+- `wasm.vm.io`
+- `wasm`
+
+## Procedures
+
+### init
+
+```pascal
+procedure init;
+```
+
+Sets the WASM VM's write-character callback to `io.syslog.logchar` and calls `wasm.wasm_init` to initialise the VM runtime.

doc/src/arch/x86/arch.x86.cpu.md

@@ -13,6 +13,10 @@ This unit probes the processor using the CPUID instruction to discover the vendo
 - `driver.timer.rtc`
 - `io.stdio`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.cpu` at the `early` barrier.
+
 ## Types
 
 ### TCapabilities_Old / PCapabilities_Old

doc/src/arch/x86/arch.x86.gdt.md

@@ -10,6 +10,10 @@ This unit defines the GDT data structures and provides procedures to set individ
 
 - `io.syslog`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.gdt` at the `early` barrier.
+
 ## Types
 
 ### TGDT_Entry / PGDT_Entry

doc/src/arch/x86/arch.x86.idt.md

@@ -12,6 +12,10 @@ This unit defines the 256-entry IDT used by the x86 interrupt system. It provide
 - `arch.x86.util`
 - `io.syslog`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.idt`, depending on `arch.x86.gdt`.
+
 ## Constants
 
 ### ISR_RING_0

doc/src/arch/x86/arch.x86.irq.md

@@ -12,6 +12,10 @@ This unit reinitialises and remaps the two 8259A Programmable Interrupt Controll
 - `arch.x86.util`
 - `io.syslog`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.irq`, depending on `arch.x86.idt`.
+
 ## Functions and Procedures
 
 ### init

doc/src/arch/x86/arch.x86.isr.md

@@ -6,6 +6,10 @@ ISR driver initialisation stub.
 
 This is a minimal stub unit that satisfies compile-time dependencies on an ISR initialisation entry point. The `init` procedure body is empty; actual ISR handler registration and IDT gate setup are performed by `arch.x86.isr.mgr` and the individual handler units in the `isr/` and `fault/` subdirectories.
 
+## Boot Registration
+
+Registered with `boot.mgr` as `asuro.x86.isr`, depending on glob `driver.storage.*.mgr` (waits for all matching entries).
+
 ## Functions and Procedures
 
 ### init

doc/src/arch/x86/arch.x86.panic.md

@@ -12,6 +12,10 @@ This unit acts as the glue layer between the x86 interrupt subsystem and the arc
 - `arch.x86.util` (implementation)
 - `arch.x86.isr.types` (implementation)
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.panic`, depending on glob `driver.video*` (waits for all matching entries).
+
 ## Functions and Procedures
 
 ### init

doc/src/arch/x86/arch.x86.v86.md

@@ -22,6 +22,10 @@ A minimal TSS is installed in GDT gate 5 so the CPU can locate the ring-0 stack
 - `arch.x86.idt`
 - `arch.x86.isr.types`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.v86` at the `early` barrier.
+
 ## Constants
 
 | Constant          | Value    | Description |

doc/src/arch/x86/fault/arch.x86.fault.md

@@ -28,6 +28,10 @@ This unit is the single entry point for registering all x86 CPU exception handle
 - `arch.x86.fault.snpe`
 - `arch.x86.fault.uie`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.fault`, depending on `arch.x86.isr.mgr`.
+
 ## Functions and Procedures
 
 ### init

doc/src/arch/x86/isr/arch.x86.isr.mgr.md

@@ -18,6 +18,10 @@ Each ISR stub is declared with the Free Pascal `interrupt` directive, which caus
 - `io.syslog` (implementation)
 - `arch.x86.isr.ioapic` (implementation)
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.isr.mgr`, depending on `arch.x86.irq`.
+
 ## Constants
 
 `MAX_HOOKS` is imported from `arch.x86.isr.types` and defines the maximum number of callbacks per vector.

doc/src/arch/x86/memory/arch.x86.memory.physical.md

@@ -16,6 +16,10 @@ During initialisation, the Multiboot memory map is walked to populate `PhysPrese
 - `core.util`
 - `arch.x86.util`
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.memory.physical`, depending on `arch.x86.idt`.
+
 ## Constants
 
 | Constant     | Value | Description |

doc/src/arch/x86/memory/arch.x86.memory.virtual.md

@@ -17,6 +17,10 @@ During `init`, the current page directory loaded by the bootloader is adopted as
 - `debug.tracer`
 - `memory.heap` (implementation)
 
+## Boot Registration
+
+Registered with `boot.mgr` as `arch.x86.memory.virtual`, depending on `arch.x86.memory.physical`.
+
 ## Types
 
 ### TPageDirEntry / PPageDirEntry

doc/src/arch/x86/system.md

@@ -93,8 +93,44 @@ A bitpacked array of 8 Booleans.
 | FileRec       | Internal file descriptor record |
 | TextRec       | Internal text file record with buffer |
 
+### INITFINAL Table Types
+
+#### TInitFinalRec
+
+```pascal
+TInitFinalRec = packed record
+    InitProc : CodePointer;
+    FinalProc: CodePointer;
+end;
+```
+
+A single entry in the compiler-generated INITFINAL table. `InitProc` points to the unit's `initialization` section code (or nil if the unit has no initialization section). `FinalProc` points to the `finalization` section code (or nil).
+
+#### TInitFinalTable / PInitFinalTable
+
+```pascal
+TInitFinalTable = packed record
+    TableCount : longint;
+    Procs      : array[1..1] of TInitFinalRec;
+end;
+```
+
+The top-level INITFINAL table structure. `TableCount` is the number of entries. `Procs` is declared as a single-element array but the compiler generates `TableCount` entries (accessed via 1-based indexing up to `TableCount`).
+
+#### TProcedure
+
+`TProcedure = procedure` — Procedure type used to cast `CodePointer` values from the INITFINAL table before calling them.
+
 ## Variables
 
+### InitFinalTable
+
+```pascal
+var InitFinalTable : TInitFinalTable; external name 'INITFINAL';
+```
+
+The compiler-generated INITFINAL table. Contains one `TInitFinalRec` for every unit in the program that has an `initialization` or `finalization` section. Referenced by `fpc_initializeunits` to walk and call each unit's initialization code before `kmain` runs.
+
 ### AK_START / AK_END
 
 ```pascal
@@ -152,7 +188,7 @@ All `compilerproc` stubs are mapped to their standard `FPC_*` aliases:
 
 | Procedure | Alias | Description |
 |-----------|-------|-------------|
-| fpc_initializeunits | FPC_INITIALIZEUNITS | No-op; boot sequence handles unit init |
+| fpc_initializeunits | FPC_INITIALIZEUNITS | Walks the INITFINAL table and calls each unit's initialization procedure |
 | fpc_do_exit | FPC_DO_EXIT | CLI + HLT |
 | fpc_handleerror | FPC_HANDLEERROR | Sets ErrorCode, CLI + HLT |
 | fpc_rangeerror | FPC_RANGEERROR | HandleErrorInternal(201) |

doc/src/asuro.md

@@ -1,43 +1,24 @@
 # asuro
 
-Kernel main entry point implementing the full Asuro boot sequence.
+Kernel main entry point.
 
 ## Overview
 
-`asuro` contains `kmain`, the first Pascal-level function called by the bootloader after the assembly stub hands off control. It performs the complete linear boot sequence: hardware initialization, memory management setup, driver loading, filesystem mounting, process manager initialization, desktop launch, and final transition into the timer-driven idle loop.
+`asuro` contains `kmain`, the first Pascal-level function called by the bootloader after the assembly stub hands off control. It stores the Multiboot info pointer and magic value, initialises the FPC system unit, then delegates the entire boot sequence to `boot.mgr.run`. Once all registered boot entries have executed, it calls `yield` to enable preemptive scheduling and idle the CPU.
 
-`kmain` accepts the Multiboot2 info pointer and magic value directly from the bootloader. It validates the magic number immediately; a mismatch triggers a kernel panic before any further initialization proceeds.
-
-The boot sequence is instrumented with `boot.splash` progress updates from 5% through 100%, giving visual feedback during the lengthy driver and unit-test phases. All logging is routed through `io.syslog` from the very first line after serial initialization.
-
-After all subsystems are initialized the function calls `yield`, which enables interrupts and halts the CPU in a loop. All subsequent work is driven by the timer ISR and the preemptive scheduler.
+The unit also registers its own `init` procedure with `boot.mgr` (depending on `io.syslog`). This procedure validates the Multiboot magic number — panicking if it does not match — and logs the framebuffer address and dimensions from the Multiboot info structure.
 
 ## Dependencies
 
-- `arch.x86.gdt`, `arch.x86.idt`, `arch.x86.irq`, `arch.x86.isr`, `arch.x86.isr.mgr`, `arch.x86.isr.tmr0`
-- `arch.x86.fault`, `arch.x86.cpu`, `arch.x86.memory.physical`, `arch.x86.memory.virtual`
-- `arch.x86.v86`, `arch.x86.proc.sched`, `arch.x86.panic`, `arch.x86.bda`
-- `memory.heap`, `io.stdio`, `io.syslog`, `debug.tracer`
-- `driver.io.serial`, `driver.timer.rtc`
-- `driver.video`, `driver.video.gpu`, `driver.video.vesa`, `driver.video.doublebuffer`, `driver.video.bga`
-- `driver.video.lvgl`, `driver.video.desktop`, `driver.video.windows`
-- `driver.hid.ps2.keyboard`, `driver.hid.ps2.mouse`
-- `driver.bus.pci`, `driver.bus.usb` (and sub-units: ehci, ohci, uhci, xhci, hub, core, types)
-- `driver.hid.usb.keyboard`, `driver.hid.usb.mouse`
-- `driver.storage.mgr`, `driver.storage.vol.mgr`, `driver.storage.fs.mgr`
-- `driver.storage.fs.fat32`, `driver.storage.fs.flatfs`, `driver.storage.fs.iso9660`
-- `driver.storage.ctl.ahci`, `driver.storage.ctl.usb`, `driver.storage.vfs`, `driver.storage.test`
-- `driver.net`, `driver.net.dev.e1000`
-- `driver.mgr`, `driver.exp.testdriver`
-- `proc.mgr`, `proc.testprocs`
-- `app.mgr`, `app.vterminal`, `app.partcmd`, `app.volcmd`, `app.uidebug`
-- `boot.splash`
-- `core.panic`, `core.rand`, `core.strings`, `core.util`
-- `core.enc.base64`, `core.enc.md5`, `core.enc.fnv1a`, `core.enc.djb2`
-- `core.ds.*` (fifo, cfifo, cfifols, circ, lifo, lists, hashmap, bloom, minh, maxh, prio)
-- `core.gfx.color`, `core.gfx.fonts`
-- `svc.gfxd`, `svc.usbd`
-- `wasm`, `wasm.vm.io`, `wasm.test`, `wasm.test.framework`
+- `boot.mgr`
+- `io.syslog`
+- `core.panic`
+- `arch.x86.multiboot`
+- `arch.x86.proc.sched`
+
+## Boot Registration
+
+Registered with `boot.mgr` as `asuro`, depending on `io.syslog`.
 
 ## Functions and Procedures
 
@@ -47,15 +28,20 @@ After all subsystems are initialized the function calls `yield`, which enables i
 procedure kmain(mbinfo: Pmultiboot_info_t; mbmagic: uint32); stdcall;
 ```
 
-Exported as `kmain` (public alias). Executes the full boot sequence in the order listed below.
+Exported as `kmain` (public alias). Performs three steps:
 
-### terminal_command_bsod (internal)
+1. Stores the Multiboot info pointer and magic value into module-level globals.
+2. Calls `System.init()` — FPC RTL initialisation (runs all unit `initialization` sections, which populates `boot.mgr`'s registration table).
+3. Calls `boot.mgr.run` — executes all registered boot entries in dependency-resolved order.
+4. Calls `yield` — enables preemptive scheduling and enters the idle loop.
+
+### init (internal)
 
 ```pascal
-procedure terminal_command_bsod(params: PParamList; stdin_buf, stdout_buf, stderr_buf: POutBuf);
+procedure init;
 ```
 
-Registered as the `BSOD` shell command. Requires exactly two parameters (error title and info string); passes them to `core.panic.panic`. Writes a usage error to stderr if the parameter count is wrong.
+Registered with `boot.mgr` as `asuro`. Validates that the Multiboot magic number matches `MULTIBOOT_BOOTLOADER_MAGIC`, panicking if it does not. Logs the assigned framebuffer address and dimensions from the Multiboot info structure.
 
 ### yield (internal)
 
@@ -63,51 +49,9 @@ Registered as the `BSOD` shell command. Requires exactly two parameters (error t
 procedure yield;
 ```
 
-Enables interrupts with `STI` then enters an infinite `HLT` loop. Called as the last statement in `kmain` to idle the CPU; all subsequent execution is driven by timer and device interrupts.
-
-## Boot Sequence
-
-The steps performed by `kmain` in order:
-
-1. `System.init` — FPC RTL initialization.
-2. `driver.io.serial.init` — serial port for early logging.
-3. `io.syslog.init` — kernel log system.
-4. Multiboot magic validation — panics if not `MULTIBOOT_BOOTLOADER_MAGIC`.
-5. `arch.x86.gdt.init` — GDT load; validates CS = `$08` or panics.
-6. `arch.x86.idt.init`, `arch.x86.irq.init`, `arch.x86.isr.mgr.init`, `arch.x86.fault.init`, `driver.timer.rtc.init` — interrupt infrastructure.
-7. `arch.x86.memory.physical.init`, `arch.x86.memory.virtual.init`, `memory.heap.init` — memory management.
-8. `arch.x86.v86.init` — Virtual 8086 monitor.
-9. `io.stdio.init` — command registry; registers `BSOD` command.
-10. `arch.x86.cpu.init` — CPUID detection.
-11. `debug.tracer.init` — call trace ring buffer.
-12. `driver.mgr.init`, GPU/video/VESA/double-buffer/BGA initialization — display subsystem.
-13. `lvgl_init` — LVGL initialized with front buffer dimensions.
-14. `arch.x86.panic.init` — LVGL-based BSOD panic screen.
-15. `boot.splash.init` — boot splash screen.
-16. `driver.storage.vfs.init`, `driver.storage.test.init` — VFS.
-17. WASURO VM initialization (`wasm.vm.io`, `wasm.wasm_init`).
-18. Storage manager, volume manager, filesystem manager initialization.
-19. `STI` + timer hook (`arch.x86.isr.tmr0.hook`) — interrupts enabled.
-20. Filesystem drivers: FAT32, FlatFS, ISO 9660.
-21. `proc.mgr.init` — process manager (first call, before device drivers).
-22. Device drivers: PS/2 keyboard, PS/2 mouse, test driver, e1000 NIC, AHCI.
-23. Bus drivers: USB, PCI.
-24. `driver.storage.vfs.auto_mount_volumes` — auto-mount discovered volumes.
-25. `driver.net.init` — network stack.
-26. `app.mgr.init` — application and command registration.
-27. `proc.mgr.init` — second call (re-initializes process table for post-driver state).
-28. `core.rand.srand` — RNG seeded from RTC date/time.
-29. Unit test suite — runs tests for strings, USB layers, data structures, WASM, and VFS.
-30. `boot.splash.teardown`, `driver.video.desktop.init` — desktop environment launched.
-31. `app.vterminal.init` — visual terminal registered with desktop.
-32. `svc.gfxd.init`, `svc.usbd.init` — graphics and USB daemon processes spawned.
-33. `arch.x86.proc.sched.init` — preemptive context switching enabled (replaces ISR_32).
-34. `yield` — CPU enters idle HLT loop.
+Logs "Boot complete", calls `arch.x86.proc.sched.init` to enable preemptive context switching (replaces ISR_32), then enters an infinite `STI` / `HLT` loop. All subsequent execution is driven by timer and device interrupts.
 
 ## Notes
 
-`proc.mgr.init` is called twice: once before device drivers (so that `submit_io` has a valid `CurrentProcess` pointer) and again after `app.mgr.init` to reset the process table to a clean post-initialization state.
-
-The `debug.tracer.freeze` call at the top of `kmain` disables tracing before the call stack is established; `debug.tracer.init` re-enables it later with the initial `'kmain'` trace entry.
-
-The WASURO I/O write-char hook is pointed at `io.syslog.logchar` so WASM VM diagnostic output is routed through the kernel log before the process manager is up.
+- The old hardcoded boot sequence previously in `kmain` has been replaced entirely by `boot.mgr`. Individual units now self-register their init procedures and dependencies; `kmain` only bootstraps the framework and idles.
+- `System.init()` triggers `FPC_INITIALIZEUNITS`, which runs every unit's `initialization` section. This is what populates `boot.mgr`'s entry table before `run` is called.

doc/src/boot/boot.splash.md

@@ -20,6 +20,11 @@ The logo is decoded at runtime from a TGA file that is embedded in the kernel bi
 - `core.gfx.texture`
 - `memory.heap`
 
+## Boot Registration
+
+- `boot.splash` depending on `core.panic` — initialises the splash screen.
+- `boot.splash.teardown` at the `final` barrier — tears down the splash screen after boot completes.
+
 ## Constants
 
 ### LV_IMAGE_HEADER_MAGIC

doc/src/core/core.md

@@ -0,0 +1,27 @@
+# core
+
+Core subsystem late initialiser.
+
+## Overview
+
+This unit performs late-stage core initialisation that depends on the RTC being available. Currently it seeds the pseudo-random number generator from the real-time clock.
+
+## Boot Registration
+
+Registered with `boot.mgr` as `core` at the `late` barrier.
+
+## Dependencies
+
+- `boot.mgr`
+- `core.rand`
+- `driver.timer.rtc`
+
+## Procedures
+
+### init
+
+```pascal
+procedure init;
+```
+
+Seeds `core.rand.srand` with a value derived from the current RTC date/time (seconds, minutes, hours, day), ensuring the PRNG produces different sequences across reboots.

doc/src/core/core.panic.md

@@ -29,6 +29,10 @@ If `init` has not been called before a panic (early boot panic), the unit gracef
 - `core.strings` — string comparison for gfxd process detection
 - `core.gfx.color` — TRGB32 colour type for direct pixel drawing
 
+## Boot Registration
+
+Registered with `boot.mgr` as `core.panic`, depending on glob `arch.*.panic` (waits for all matching entries).
+
 ## Constants
 
 ### MAX_REGISTER_ENTRIES

doc/src/debug/debug.tracer.md

@@ -17,6 +17,11 @@ A `TRACER` shell command allows runtime inspection and toggling of the trace buf
 - `io.stdio`
 - `io.syslog`
 
+## Boot Registration
+
+- `debug.tracer.freeze` depending on `io.syslog` — freezes the tracer ring buffer.
+- `debug.tracer` depending on `io.stdio` — full tracer initialisation.
+
 ## Constants
 
 ### MAX_TRACE