doc/compat/lmemorymanager.md

@@ -1 +1,94 @@
-# Placeholder
+# lmemorymanager
+
+Compatibility shim that re-exports the `memory.heap` API under the legacy unit name.
+
+## Overview
+
+The Wasuro WASM VM project references the old unit name `lmemorymanager` for heap memory operations. Because the Wasuro source tree cannot be modified, this shim unit re-exports every public symbol from `memory.heap` so that `uses lmemorymanager` continues to compile without changes. All functions are thin inline wrappers that delegate directly to their `memory.heap` counterparts.
+
+## Dependencies
+
+- `memory.heap` -- the canonical heap allocator implementation in the Asuro kernel.
+
+## Constants
+
+### ALLOC_UNIT
+Re-exported from `memory.heap.ALLOC_UNIT`. The base allocation unit size used by the heap allocator.
+
+### DATA_OFFSET
+Re-exported from `memory.heap.DATA_OFFSET`. Byte offset from a heap block header to the start of user data.
+
+### PAGE_SIZE_LMM
+Re-exported from `memory.heap.PAGE_SIZE_LMM`. Page size used by the lightweight memory manager.
+
+### TOTAL_UNITS
+Re-exported from `memory.heap.TOTAL_UNITS`. Total number of allocation units per heap page.
+
+### BITMAP_DWORDS
+Re-exported from `memory.heap.BITMAP_DWORDS`. Number of 32-bit words in the per-page allocation bitmap.
+
+### SIZE_PREFIX
+Re-exported from `memory.heap.SIZE_PREFIX`. Size of the prefix stored before each allocation to record its length.
+
+### LARGE_ALLOC_MAGIC
+Re-exported from `memory.heap.LARGE_ALLOC_MAGIC`. Magic value used to identify large (multi-page) allocations.
+
+## Types
+
+### PHeapPageHeader / THeapPageHeader
+Re-exported from `memory.heap`. Pointer and record types describing the header structure at the beginning of each heap page.
+
+## Functions and Procedures
+
+### init
+```pascal
+procedure init;
+```
+Initializes the heap memory manager by delegating to `memory.heap.init`.
+
+### kalloc
+```pascal
+function kalloc(size: uint32): void;
+```
+Allocates `size` bytes from the kernel heap and returns a pointer to the allocated memory.
+
+### klalloc
+```pascal
+function klalloc(size: uint32): void;
+```
+Performs a large kernel allocation of `size` bytes and returns a pointer to the allocated memory.
+
+### klfree
+```pascal
+procedure klfree(address: uint32);
+```
+Frees a large allocation previously obtained via `klalloc`.
+
+### kpalloc
+```pascal
+function kpalloc(address: uint32): void;
+```
+Allocates a heap page at the specified address and returns a pointer to it.
+
+### kfree
+```pascal
+procedure kfree(area: void);
+```
+Frees a standard allocation previously obtained via `kalloc`.
+
+### lmm_total_free
+```pascal
+function lmm_total_free: uint32;
+```
+Returns the total number of free bytes available across all heap pages.
+
+### lmm_page_count
+```pascal
+function lmm_page_count: uint32;
+```
+Returns the current number of heap pages managed by the allocator.
+
+## Notes
+
+- Every function and procedure in the implementation section is marked `inline`, so the compiler eliminates the wrapper overhead entirely.
+- This unit exists solely for backward compatibility with the Wasuro WASM VM build. New kernel code should use `memory.heap` directly.

doc/compat/types.md

@@ -1 +1,16 @@
-# Placeholder
+# types
+
+Empty compatibility shim that satisfies `uses types` references from the Wasuro WASM VM project.
+
+## Overview
+
+Some units in the Wasuro WASM VM source tree include `uses types` to pull in shared type definitions from the Asuro kernel. In the kernel proper, those types may be declared elsewhere or may no longer be needed in the WASM context. This stub unit provides an empty `types` compilation unit so that `uses types` resolves without error during the Wasuro build.
+
+## Dependencies
+
+None.
+
+## Notes
+
+- The unit declares no constants, types, variables, or routines. Its only purpose is to exist as a valid compilation unit.
+- If Wasuro code is ever updated to remove the `uses types` dependency, this shim can be deleted.

doc/lvglh/hack_14.md

@@ -1 +1,53 @@
-# Placeholder
+# hack_14.c
+
+LVGL bitmap font source for the Hack Regular typeface at 14 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Hack Regular TrueType font (`Hack-Regular.ttf`) for use with LVGL. It provides a complete monospaced programmer font covering the full Basic Multilingual Plane (Unicode range 0x0000--0xFFFF). The font is intended for use in terminal emulators, code editors, or any UI element within Asuro that benefits from a fixed-width typeface.
+
+The file was generated by the LVGL font converter tool and is approximately 12,900 lines (~548 KB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### HACK_14
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Hack Regular |
+| Size | 14 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 19 px |
+| Baseline | 5 px from bottom |
+| Underline position | -2 |
+| Underline thickness | 1 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t hack_14;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&hack_14` when assigning fonts to labels, text areas, or other text-bearing widgets.
+
+## Generation Command
+
+```
+--bpp 4 --size 14 --no-compress --stride 1 --align 1 \
+--font Hack-Regular.ttf --range 0-65535 --format lvgl -o hack_14.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range makes this a large file. If binary size is a concern, the range could be narrowed to only the code points actually used.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/lvglh/lv_conf.md

@@ -1 +1,133 @@
-# Placeholder
+# lv_conf.h
+
+LVGL v9.2.2 configuration header tailored for the Asuro bare-metal kernel environment.
+
+## Overview
+
+This file configures the LVGL graphics library for use inside the Asuro kernel, where no standard C library, operating system, or GPU hardware is available. It selects a 32-bit XRGB8888 color depth to match the VESA framebuffer, routes all stdlib functionality through LVGL's built-in implementations, enables only the software renderer, and disables every hardware backend, filesystem driver, and image decoder. The result is a minimal but functional GUI stack that runs entirely in kernel space.
+
+## Configuration Options / Defines
+
+### Color Settings
+
+#### LV_COLOR_DEPTH
+Value: `32`. Matches the VESA XRGB8888 framebuffer used by Asuro.
+
+### Standard Library Wrappers
+
+#### LV_USE_STDLIB_MALLOC / LV_USE_STDLIB_STRING / LV_USE_STDLIB_SPRINTF
+Value: `LV_STDLIB_BUILTIN`. All three are set to use LVGL's own built-in implementations since no libc is available in the bare-metal environment.
+
+### Memory Pool
+
+#### LV_MEM_SIZE
+Value: `256 * 1024U` (256 KB). Size of LVGL's internal memory pool for widget allocations and draw buffers.
+
+#### LV_MEM_POOL_EXPAND_SIZE
+Value: `0`. Pool expansion is disabled; the 256 KB allocation is fixed.
+
+#### LV_MEM_ADR
+Value: `0`. LVGL allocates the pool itself rather than using a fixed address.
+
+### HAL Settings
+
+#### LV_DEF_REFR_PERIOD
+Value: `33` (milliseconds). Targets approximately 30 frames per second.
+
+#### LV_DPI_DEF
+Value: `96`. Standard screen DPI assumption.
+
+### Operating System
+
+#### LV_USE_OS
+Value: `LV_OS_NONE`. No OS abstraction layer; LVGL runs in a bare-metal cooperative model.
+
+### Rendering Configuration
+
+#### LV_USE_DRAW_SW
+Value: `1`. The software renderer is the sole rendering backend.
+
+Only the color formats actually used are enabled within the software renderer:
+
+| Define | Value | Description |
+|--------|-------|-------------|
+| `LV_DRAW_SW_SUPPORT_XRGB8888` | 1 | Primary framebuffer format |
+| `LV_DRAW_SW_SUPPORT_ARGB8888` | 1 | Alpha-blended surfaces |
+| `LV_DRAW_SW_SUPPORT_RGB888` | 1 | 24-bit fallback |
+| `LV_DRAW_SW_SUPPORT_RGB565` | 0 | Disabled |
+| All other formats | 0 | Disabled |
+
+#### LV_DRAW_SW_COMPLEX
+Value: `1`. Enables complex draw operations (shadows, rounded corners). Shadow cache is disabled (`LV_DRAW_SW_SHADOW_CACHE_SIZE = 0`); circle cache is set to 4 entries.
+
+#### LV_DRAW_LAYER_SIMPLE_BUF_SIZE
+Value: `24 * 1024` (24 KB). Buffer for simple layer rendering.
+
+#### GPU Backends
+All GPU-accelerated backends are disabled: VGLite, PXP, Dave2D, SDL, VG-Lite.
+
+### Logging
+
+#### LV_USE_LOG
+Value: `1`. Logging is enabled at `LV_LOG_LEVEL_WARN`. Printf-based logging, timestamps, and file/line info are all disabled to reduce overhead. All trace categories (memory, timer, indev, display refresh, events, object creation, layout, animation, cache) are disabled.
+
+### Assertions
+
+#### LV_USE_ASSERT_NULL / LV_USE_ASSERT_MALLOC
+Value: `1`. Null-pointer and malloc-failure assertions are active.
+
+#### LV_ASSERT_HANDLER
+Value: `{}` (no-op). The assert handler intentionally does nothing to avoid hanging the kernel on a failed assertion.
+
+### Fonts
+
+#### LV_FONT_MONTSERRAT_14
+Value: `1`. The only built-in Montserrat size enabled.
+
+#### LV_FONT_DEFAULT
+Value: `&lv_font_montserrat_14`. All other Montserrat sizes (8--48), compressed variants, and alternative font families (DejaVu, SimSun, UNSCII) are disabled.
+
+### Text Settings
+
+#### LV_TXT_ENC
+Value: `LV_TXT_ENC_UTF8`. UTF-8 text encoding. BiDi and Arabic/Persian character support are disabled.
+
+### Widgets
+
+Enabled widgets: AnimImg, Arc, Bar, Button, ButtonMatrix, Checkbox, Dropdown, Image, Keyboard, Label, Line, List, MsgBox, Roller, Slider, Spinner, Switch, TextArea, Table, TabView, Win.
+
+Disabled widgets: Calendar, Canvas, Chart, ImageButton, LED, Lottie, Menu, Scale, Span, SpinBox, TileView.
+
+### Themes
+
+#### LV_USE_THEME_DEFAULT
+Value: `1`. Dark mode enabled (`LV_THEME_DEFAULT_DARK = 1`) with 80 ms transition time.
+
+#### LV_USE_THEME_SIMPLE
+Value: `1`.
+
+#### LV_USE_THEME_MONO
+Value: `0`.
+
+### Layouts
+
+Both Flex and Grid layout engines are enabled.
+
+### Third-Party Libraries
+
+All filesystem drivers are disabled (stdio, POSIX, Win32, FatFS, MemFS, LittleFS). All image decoders are disabled (PNG, BMP, JPEG, GIF, RLE). FreeType, TinyTTF, Rlottie, vector graphics, LZ4, and FFmpeg are all disabled.
+
+### Device Drivers
+
+All platform-specific device drivers are disabled (SDL, X11, Wayland, Linux FBDEV, Linux DRM, NuttX, various SPI display controllers, Windows, OpenGLES, QNX). Display and input are handled by Asuro's own HAL layer.
+
+### Examples and Demos
+
+All built-in examples and demo applications are disabled.
+
+## Notes
+
+- The configuration is designed for minimal footprint. Features are enabled only when required by the Asuro desktop shell.
+- Since no libc is linked, all string, memory, and formatting operations fall through to LVGL's internal implementations.
+- The assert handler is a deliberate no-op to prevent the kernel from halting on non-critical UI assertion failures.
+- The 256 KB memory pool is fixed and cannot expand at runtime. UI complexity must stay within this budget.

doc/lvglh/lv_font_fa_solid_16.md

@@ -1 +1,55 @@
-# Placeholder
+# lv_font_fa_solid_16.c
+
+LVGL bitmap font source for Font Awesome 7 Free Solid at 16 px.
+
+## Overview
+
+This file contains a pre-rendered bitmap font generated from the Font Awesome 7 Free Solid TrueType font (`Font Awesome 7 Free-Solid-900.ttf`) for use with LVGL. It provides a library of solid-style vector icons rendered as bitmaps, suitable for toolbar buttons, status indicators, navigation elements, and general iconography in the Asuro GUI.
+
+The file was generated by the LVGL font converter tool and is approximately 35,800 lines (~1.6 MB) of static bitmap and glyph descriptor data.
+
+## Configuration Options / Defines
+
+### LV_FONT_FA_SOLID_16
+Value: `1` (default). Acts as a compile-time guard. Set to `0` to exclude this font from the build entirely.
+
+## Font Properties
+
+| Property | Value |
+|----------|-------|
+| Font family | Font Awesome 7 Free Solid 900 |
+| Size | 16 px |
+| Bits per pixel | 4 (16-level anti-aliasing) |
+| Compression | None (`--no-compress`) |
+| Stride alignment | 1 byte |
+| Data alignment | 1 byte |
+| Line height | 20 px |
+| Baseline | 4 px from bottom |
+| Underline position | 0 |
+| Underline thickness | 0 |
+| Unicode range | 0x0000--0xFFFF |
+| Subpixel rendering | None |
+
+## Public Symbol
+
+```c
+const lv_font_t lv_font_fa_solid_16;
+```
+
+This is the font descriptor exposed for use in LVGL widget styles. Reference it as `&lv_font_fa_solid_16` when assigning icon fonts to labels or buttons. Font Awesome icons are addressed by their Unicode code points (e.g., `LV_SYMBOL_*` constants or raw `\uXXXX` escape sequences).
+
+## Generation Command
+
+```
+--bpp 4 --size 16 --no-compress --stride 1 --align 1 \
+--font "Font Awesome 7 Free-Solid-900.ttf" --range 0-65535 --format lvgl \
+-o lv_font_fa_solid_16.c
+```
+
+## Notes
+
+- This is a machine-generated file. Do not edit by hand; regenerate using the LVGL font converter if changes are needed.
+- The full 0--65535 Unicode range includes all Font Awesome solid icons. Since most code points in this range are blank (Font Awesome only defines glyphs for its icon set), the actual rendered glyph count is much smaller than the range suggests, but the descriptor tables still consume significant space.
+- The file is the largest in the `lvglh/` directory at approximately 1.6 MB. If binary size becomes a constraint, the Unicode range should be narrowed to only the icon code points actually used by the Asuro shell.
+- The font includes version-conditional compilation guards for compatibility across LVGL 6.x through 9.x, though Asuro targets LVGL 9.2.2.
+- The `LV_ATTRIBUTE_LARGE_CONST` annotation on the glyph bitmap array allows the linker to place it in an appropriate read-only section.

doc/toolchain/compile.md

@@ -1 +1,44 @@
-# Placeholder
+# compile.sh
+
+Top-level build orchestrator for the Asuro kernel.
+
+## Overview
+
+`compile.sh` is the main entry point for building the Asuro operating system. It sequentially invokes each stage of the build pipeline, halting on the first failure. After all stages complete (or a failure occurs), it calls `compile_finish.sh` to generate a build-status badge and set the exit code.
+
+## Prerequisites
+
+- All sub-scripts must be present in the same directory as `compile.sh`.
+- The Docker build container must provide: `bash`, `nasm`, `fpc`, `gcc`, `ld`, `grub-mkrescue`, `git`, `wget`, and standard POSIX utilities.
+
+## Inputs
+
+None directly. Each sub-script reads its own inputs from the source tree.
+
+## Outputs
+
+- All artifacts produced by the sub-scripts (object files, kernel binary, ISO image, version info, badges, documentation).
+- Final exit code: `0` on success, `1` on failure.
+
+## Behavior
+
+1. Clears the `lib/` directory to ensure a clean build.
+2. Defines a helper function `runOrFail` that runs a command and increments `ERRCOUNT` on failure.
+3. Resolves its own directory (`TOOLCHAIN_DIR`) so sub-scripts can be located by absolute path.
+4. Declares an ordered list of build steps (script name and error message pairs):
+   - `compile_stub.sh` -- Assemble boot stubs.
+   - `compile_vergen.sh` -- Generate version information.
+   - `compile_lvgl.sh` -- Compile the LVGL graphics library.
+   - `compile_wasuro.sh` -- Pull the Wasuro WASM runtime sources.
+   - `compile_sources.sh` -- Compile Free Pascal kernel sources.
+   - `compile_link.sh` -- Link all object files into `kernel.bin`.
+   - `compile_isogen.sh` -- Create the bootable ISO image.
+   - `compile_docs.sh` -- Generate project documentation.
+5. Iterates through the steps. If `ERRCOUNT` is non-zero, all remaining steps are skipped.
+6. Calls `compile_finish.sh` with either `"success"` or `"failed"` depending on whether any errors were recorded.
+7. Changes directory back up one level (`cd ..`).
+
+## Notes
+
+- `compile_finish.sh` is sourced (`. script`) rather than executed as a sub-process, so its `exit` call terminates the entire pipeline.
+- The build is fail-fast: the first failing step prevents all subsequent steps from running, but the finish step always runs to produce a status badge.

doc/toolchain/compile_checksum.md

@@ -1 +1,38 @@
-# Placeholder
+# compile_checksum.sh
+
+Generates MD5 checksums for all Pascal source files.
+
+## Overview
+
+`compile_checksum.sh` iterates over every `.pas` file under `src/` and appends its MD5 hash to `checksums.md5`. This file serves as a source-level fingerprint used by `compile_vergen.sh` to produce a build integrity checksum.
+
+## Prerequisites
+
+- `md5sum` and `find` must be available.
+- The `src/` directory must exist and contain `.pas` files.
+
+## Inputs
+
+All `*.pas` files found recursively under `src/`, up to 10 levels deep.
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `checksums.md5` | A file containing one `md5sum`-format line per Pascal source file. |
+
+## Behavior
+
+1. Truncates (or creates) `checksums.md5` with an empty write (`echo >`).
+2. Finds all directories under `src/` (up to 10 levels deep).
+3. For each directory, iterates over `*.pas` files and computes their MD5 checksum.
+4. Skips files matching any of the following conditions:
+   - Path contains `.svn` (Subversion metadata).
+   - The glob matched no files (literal `*.pas` string).
+   - Path contains `include/asuro.pas`.
+5. Appends each valid checksum line to `checksums.md5`.
+
+## Notes
+
+- The resulting `checksums.md5` is consumed by `compile_vergen.sh`, which hashes the checksum file itself to produce a single build fingerprint constant embedded in the kernel.
+- The `.svn` exclusion is a legacy filter from when the project used Subversion for version control.

doc/toolchain/compile_docs.md

@@ -18,20 +18,6 @@ Builds the static documentation website from the Markdown files in the `doc/` di
 3. Runs `mkdocs build --strict` to generate the static site.
 4. Output is written to the `site/` directory at the project root.
 
-## Docker Usage
-
-The documentation site can also be built and served via Docker Compose:
-
-```bash
-# Live development server with hot-reload
-docker compose up docs
-
-# Static build only
-docker compose run docs build --strict
-```
-
-The development server listens on `http://localhost:8000`.
-
 ## Configuration
 
 The site is configured by `mkdocs.yml` in the project root. The navigation structure mirrors the `doc/` directory hierarchy.

doc/toolchain/compile_finish.md

@@ -1 +1,40 @@
-# Placeholder
+# compile_finish.sh
+
+Reports build status and generates the build result badge.
+
+## Overview
+
+`compile_finish.sh` is the final step in the Asuro build pipeline. It is sourced (not executed) by `compile.sh` and receives a single argument indicating whether the build succeeded or failed. It downloads the appropriate shields.io badge and exits with the corresponding exit code.
+
+## Prerequisites
+
+- `wget` must be available (though badge download failure is non-fatal).
+- The `release/` directory must exist.
+
+## Inputs
+
+| Input | Description |
+|-------|-------------|
+| `$1` | A string argument: `"failed"` or `"success"`. Passed by `compile.sh`. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `release/build.svg` | A shields.io badge: red "build-failed" or green "build-succeeded". |
+
+## Behavior
+
+1. If `$1` is `"failed"`:
+   - Prints an error message directing the user to review the log.
+   - Downloads a red "build-failed" badge to `release/build.svg`.
+   - Exits with code 1.
+2. Otherwise:
+   - Prints a success message.
+   - Downloads a green "build-succeeded" badge to `release/build.svg`.
+   - Exits with code 0.
+
+## Notes
+
+- This script is sourced (`. compile_finish.sh`) by `compile.sh`, meaning its `exit` call terminates the parent shell. This is intentional -- it sets the final exit code for the entire build pipeline.
+- Badge download is silent and non-blocking; if `wget` fails (e.g., no network), the build still reports the correct exit code.

doc/toolchain/compile_isogen.md

@@ -1 +1,37 @@
-# Placeholder
+# compile_isogen.sh
+
+Creates a bootable GRUB ISO image containing the Asuro kernel.
+
+## Overview
+
+`compile_isogen.sh` copies the compiled kernel binary into the ISO directory structure and invokes `grub-mkrescue` to produce a bootable CD-ROM image. The resulting `Asuro.iso` can be booted in any x86 emulator (QEMU, VirtualBox, etc.) or written to physical media.
+
+## Prerequisites
+
+- `grub-mkrescue` (from GRUB utilities) and `xorriso` (its backend) must be available.
+- `bin/kernel.bin` must exist (produced by `compile_link.sh`).
+- The `iso/boot/` directory must exist and contain a GRUB configuration file (`iso/boot/grub/grub.cfg`).
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `bin/kernel.bin` | The linked kernel binary. |
+| `iso/` | Pre-existing ISO directory tree with GRUB configuration. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `Asuro.iso` | Bootable GRUB rescue ISO image. |
+| `iso/boot/asuro.bin` | Copy of the kernel binary placed into the ISO tree. |
+
+## Behavior
+
+1. Copies `bin/kernel.bin` to `iso/boot/asuro.bin`.
+2. Runs `grub-mkrescue -o Asuro.iso iso` to generate the bootable ISO from the `iso/` directory tree.
+
+## Notes
+
+- The GRUB configuration in `iso/boot/grub/grub.cfg` must reference `asuro.bin` as the kernel to load.
+- The ISO is generated in the project root directory.

doc/toolchain/compile_link.md

@@ -1 +1,47 @@
-# Placeholder
+# compile_link.sh
+
+Links all object files and libraries into the final kernel binary.
+
+## Overview
+
+`compile_link.sh` collects every `.o` object file in `lib/`, locates `libgcc` for i386, and invokes the GNU linker (`ld`) to produce `bin/kernel.bin`. The linker script `toolchain/linker.script` controls the memory layout of the resulting binary.
+
+## Prerequisites
+
+- `ld` (GNU linker) and `gcc` must be available.
+- All object files must have been produced by prior build steps (`compile_stub.sh`, `compile_sources.sh`).
+- `lib/liblvgl.a` must exist (produced by `compile_lvgl.sh`).
+- `toolchain/linker.script` must exist.
+- The `bin/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `lib/*.o` | All ELF object files (boot stub, Pascal units, splash screen, etc.). |
+| `lib/liblvgl.a` | Static LVGL library archive. |
+| `libgcc` (system) | GCC runtime support library for i386, located via `gcc -m32 -print-libgcc-file-name`. |
+| `toolchain/linker.script` | Linker script defining section layout and entry point. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `bin/kernel.bin` | The final linked, stripped kernel binary. |
+
+## Behavior
+
+1. Collects all `.o` files from `lib/`, excluding `lib/stub.o` from the general list.
+2. Prepends `lib/stub.o` to the front of the object list so the boot entry point is linked first.
+3. Locates `libgcc` for the 32-bit target using `gcc -m32 -print-libgcc-file-name`.
+4. Invokes `ld` with the following flags:
+   - `-m elf_i386` -- Target i386 ELF format.
+   - `-s` -- Strip all symbol information.
+   - `--gc-sections` -- Remove unused sections (works with FPC's `-CX -XXs` smart-linking).
+   - `-T toolchain/linker.script` -- Use the project linker script.
+   - `--start-group` / `--end-group` -- Wraps `liblvgl.a` and `libgcc` to resolve circular references between them.
+
+## Notes
+
+- `stub.o` must be first in the link order because it contains the multiboot header and the initial entry point that GRUB transfers control to.
+- The `--start-group` / `--end-group` construct allows the linker to iterate over `liblvgl.a` and `libgcc` multiple times to resolve all symbols, which is necessary when C library objects have mutual dependencies.

doc/toolchain/compile_lvgl.md

@@ -1 +1,51 @@
-# Placeholder
+# compile_lvgl.sh
+
+Downloads and compiles LVGL v9.2 into a static library for the kernel.
+
+## Overview
+
+`compile_lvgl.sh` clones the LVGL graphics library source, cross-compiles every C source file to 32-bit freestanding ELF objects, and archives them into `lib/liblvgl.a`. It also compiles any custom Asuro-specific LVGL extension files found in `lvglh/`. A caching mechanism on the host-mounted `/code/lvgl/` directory allows subsequent builds to skip the entire compilation.
+
+## Prerequisites
+
+- `git`, `gcc`, `ar`, and standard POSIX utilities must be available.
+- The `lvglh/` directory must contain an `lv_conf.h` configuration header (and optionally custom `.c` files).
+- The `lib/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| LVGL Git repository | Cloned from `https://github.com/lvgl/lvgl.git` at tag `v9.2.2`. |
+| `lvglh/` | Project-local directory containing `lv_conf.h` and optional custom C source files. |
+| `/code/lvgl/liblvgl.a` | Optional cached artifact from a previous build (host mount). |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/liblvgl.a` | Static archive containing all compiled LVGL and custom extension objects. |
+| `/code/lvgl/` | Cached copy of the static library, LVGL source, and object files for future builds. |
+
+## Behavior
+
+1. **Cache check**: If `/code/lvgl/liblvgl.a` exists, copies it to `lib/` and exits immediately.
+2. **Clone**: Shallow-clones the LVGL repository at the specified version tag into `/tmp/lvgl`.
+3. **Discover sources**: Finds all `.c` files under the LVGL `src/` directory, excluding test files.
+4. **Compile**: Compiles each source file with GCC using the following key flags:
+   - `-m32 -march=i686` -- 32-bit i686 target.
+   - `-ffreestanding -fno-builtin -fno-stack-protector -fno-pic -fno-pie` -- Bare-metal environment.
+   - `-O2` -- Optimization level 2.
+   - `-DLV_CONF_INCLUDE_SIMPLE` -- Tells LVGL to include `lv_conf.h` via a simple path.
+   - Include paths for `lvglh/` and the LVGL source tree.
+5. **Archive**: Collects all `.o` files into `lib/liblvgl.a` using `ar rcs`.
+6. **Custom extensions**: If `lvglh/` contains `.c` files, compiles them with the same flags and appends the resulting objects to `liblvgl.a`.
+7. **Cache write**: Copies the static library, source, and objects to `/code/lvgl/` on the host mount for future builds.
+
+Progress is reported every 50 files. The script aborts with exit code 1 if any compilation errors occur.
+
+## Notes
+
+- All intermediate work (clone, object files) happens in `/tmp` for speed on container-local filesystems.
+- The cache lives on the host mount at `/code/lvgl/`. Deleting `lvgl/liblvgl.a` from the project root forces a full rebuild.
+- The static library is linked into the kernel by `compile_link.sh` using `--start-group` / `--end-group` alongside `libgcc`.

doc/toolchain/compile_sourcelist.md

@@ -1 +1,32 @@
-# Placeholder
+# compile_sourcelist.sh
+
+Generates a list of all Pascal source files in the project.
+
+## Overview
+
+`compile_sourcelist.sh` scans the parent directory for all `.pas` files and writes their paths to `sources.list`. This file can be used by other tools or scripts that need a manifest of Pascal source files.
+
+## Prerequisites
+
+- `find` must be available.
+- Must be run from a subdirectory of the project root (it searches `..`).
+
+## Inputs
+
+The entire project directory tree (searched recursively for `*.pas` files).
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `sources.list` | A newline-delimited list of absolute paths to all `.pas` files found. |
+
+## Behavior
+
+1. Uses `find` to locate all files matching `*.pas` in the parent directory.
+2. Writes the results to `sources.list` in the current working directory.
+3. Exits with code 0.
+
+## Notes
+
+- This script is not currently listed in the `compile.sh` build pipeline steps. It may be used as a standalone utility or by external tooling.

doc/toolchain/compile_sources.md

@@ -1 +1,55 @@
-# Placeholder
+# compile_sources.sh
+
+Compiles the Asuro kernel Pascal sources with Free Pascal.
+
+## Overview
+
+`compile_sources.sh` invokes the Free Pascal Compiler (FPC) to compile the main kernel unit (`src/asuro.pas`) along with all dependent units. It dynamically discovers every subdirectory under `src/`, `wasuro/`, and `compat/` and passes them as unit search paths (`-Fu`) so that FPC can resolve all unit references.
+
+## Prerequisites
+
+- `fpc` (Free Pascal Compiler 3.2.2 or compatible) must be available.
+- `find` must be available.
+- The `src/`, `wasuro/`, and `compat/` directories must be populated with their respective Pascal sources.
+- The `lib/` output directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `src/asuro.pas` | The top-level kernel program unit. |
+| `src/**/*.pas` | All kernel Pascal source units. |
+| `wasuro/**/*.pas` | Wasuro WASM runtime units (pulled by `compile_wasuro.sh`). |
+| `compat/**/*.pas` | Compatibility layer units. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/*.o` | ELF object files for each compiled unit. |
+| `lib/*.ppu` | FPC precompiled unit files. |
+
+## Behavior
+
+1. Discovers all subdirectories under `src/`, `wasuro/`, and `compat/` using `find`.
+2. Builds a `-Fu` flag string containing every discovered directory.
+3. Invokes `fpc` with the following key flags:
+   - `-Aelf` -- Output ELF-format assembly.
+   - `-gw -g -gl` -- Generate DWARF debug info and line info.
+   - `-n` -- Ignore `fpc.cfg`; do not load default configuration.
+   - `-v0e` -- Verbosity: errors only.
+   - `-O3` -- Aggressive optimization.
+   - `-OpPENTIUM3` -- Optimize for Pentium III instruction scheduling.
+   - `-Si -Sc -Sg` -- Enable inline, C-style operators, and goto support.
+   - `-Xd` -- Do not search default library path.
+   - `-CX -XXs` -- Create smartlinkable units and strip unused code.
+   - `-CfSSE -CfSSE2` -- Use SSE/SSE2 floating-point.
+   - `-Rintel` -- Use Intel assembler syntax.
+   - `-Pi386 -Tlinux` -- Target i386 Linux (ELF).
+   - `-FElib/` -- Output compiled files to `lib/`.
+
+## Notes
+
+- The `-n` flag is critical: it prevents FPC from loading any system-wide configuration that might introduce incompatible settings for the bare-metal target.
+- The `-Xd` flag ensures FPC does not try to link against system libraries, since the kernel is freestanding.
+- Object files produced here are later consumed by `compile_link.sh`.

doc/toolchain/compile_stub.md

@@ -1 +1,37 @@
-# Placeholder
+# compile_stub.sh
+
+Assembles the low-level boot stub and splash screen objects.
+
+## Overview
+
+`compile_stub.sh` uses NASM to assemble two assembly source files into ELF object files. These objects contain the initial boot entry point and an embedded splash-screen TGA image, both of which are linked into the final kernel binary.
+
+## Prerequisites
+
+- `nasm` must be available on the PATH.
+- The source files `src/arch/x86/boot/stub.asm` and `src/boot/splash_tga.asm` must exist.
+- The `lib/` output directory must exist (created by `compile.sh` which clears it beforehand).
+
+## Inputs
+
+| File | Description |
+|------|-------------|
+| `src/arch/x86/boot/stub.asm` | x86 boot stub -- the kernel entry point before Pascal code takes over. |
+| `src/boot/splash_tga.asm` | Embeds a TGA splash screen image as a binary blob. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `lib/stub.o` | ELF object for the boot stub. |
+| `lib/splash_tga.o` | ELF object for the splash screen data. |
+
+## Behavior
+
+1. Assembles `stub.asm` into `lib/stub.o` using NASM with the ELF output format (`-f elf`).
+2. Assembles `splash_tga.asm` into `lib/splash_tga.o` using the same format.
+
+## Notes
+
+- Both files are assembled as 32-bit ELF objects, consistent with the i386 target architecture.
+- `stub.o` is treated specially during linking: `compile_link.sh` places it first in the link order so that the boot entry point appears at the expected address.

doc/toolchain/compile_sumgen.md

@@ -1 +1,35 @@
-# Placeholder
+# compile_sumgen.sh
+
+Generates an MD5 checksum badge for the final ISO image.
+
+## Overview
+
+`compile_sumgen.sh` computes the MD5 hash of `Asuro.iso` and downloads a shields.io SVG badge displaying the checksum. This badge is stored in the `release/` directory for use in project documentation and release pages.
+
+## Prerequisites
+
+- `md5sum`, `awk`, and `wget` must be available.
+- `Asuro.iso` must exist in the current directory (produced by `compile_isogen.sh`).
+- The `release/` directory must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| `Asuro.iso` | The final bootable ISO image. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `release/checksum.svg` | Shields.io badge displaying the ISO's MD5 checksum. |
+
+## Behavior
+
+1. Computes the MD5 checksum of `Asuro.iso` using `md5sum`.
+2. Downloads a shields.io badge SVG with the checksum value and saves it to `release/checksum.svg`.
+
+## Notes
+
+- This script is not currently listed in the `compile.sh` pipeline. It may be invoked separately or have been superseded by badge generation in `compile_vergen.sh`.
+- The `wget` call is silenced (`-q`) and its stderr is redirected to `/dev/null`, so download failures are silent.

doc/toolchain/compile_vergen.md

@@ -1 +1,53 @@
-# Placeholder
+# compile_vergen.sh
+
+Generates compile-time version constants and release badges.
+
+## Overview
+
+`compile_vergen.sh` extracts version metadata from Git tags (using semantic versioning), gathers build statistics (line counts, file counts, tool versions), and writes them into a Pascal unit (`core.version.pas`). It also downloads shields.io SVG badges summarizing the release information.
+
+## Prerequisites
+
+- `git`, `wget`, `fpc`, `make`, `nasm`, `awk`, `find`, `md5sum`, and `date` must be available.
+- The repository must have at least one semver-compatible Git tag reachable from HEAD.
+- `compile_checksum.sh` must be present in the toolchain directory (called to generate `checksums.md5` first).
+- `loc.sh` must be present in the toolchain directory.
+- The `bin/`, `release/`, and `src/core/` directories must exist.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| Git tags | Parsed via `git describe --tags` to extract semver components. |
+| `checksums.md5` | Generated by `compile_checksum.sh`; its own MD5 is used as a build fingerprint. |
+| Source tree (`src/`) | Scanned to count total files and driver files. |
+| Tool versions | Queried from `fpc -h`, `make -v`, and `nasm -v`. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `src/core/core.version.pas` | Pascal unit exposing version constants to the kernel at compile time. |
+| `release/*.svg` | Shields.io badges for version, revision, release, line count, file count, driver count, tool versions, date, and fingerprint. |
+
+## Behavior
+
+1. Runs `compile_checksum.sh` to produce `checksums.md5`.
+2. Downloads the `semver` shell tool from GitHub into `bin/` and adds it to `PATH`.
+3. Extracts the following from `git describe --tags`:
+   - Major, minor, and patch version numbers.
+   - Pre-release label (if any).
+   - Build metadata.
+   - Short commit revision (8 characters).
+4. Counts total lines of Pascal source (via `loc.sh`), total source files, and driver-specific files.
+5. Queries the installed versions of FPC, Make, and NASM.
+6. Records the current date and time.
+7. Computes an MD5 fingerprint of `checksums.md5`.
+8. Writes all values into `src/core/core.version.pas` as Pascal `const` declarations.
+9. Downloads SVG badges from shields.io into `release/` for each metric. Badge download failures are non-fatal (`set +e`).
+
+## Notes
+
+- The `set -e` at the top causes the script to abort on any error during the critical version-extraction phase. It is relaxed (`set +e`) before badge downloads, since those are cosmetic and may fail in offline or branch builds.
+- If a pre-release label is present in the tag, it is appended to the version string (e.g., `1.0.0-alpha`).
+- The generated `core.version.pas` is compiled into the kernel by `compile_sources.sh`, making all version metadata available at runtime.

doc/toolchain/compile_wasuro.md

@@ -1 +1,38 @@
-# Placeholder
+# compile_wasuro.sh
+
+Pulls the Wasuro WASM runtime Pascal sources into the build tree.
+
+## Overview
+
+`compile_wasuro.sh` fetches the Wasuro WebAssembly runtime from its Git repository using a sparse checkout (only the `src/wasm` subtree) and copies the Pascal source files into the local `wasuro/` directory. This makes the Wasuro units available to the FPC compiler via `-Fu` include paths during `compile_sources.sh`.
+
+## Prerequisites
+
+- `git` must be available and able to reach `https://gitea.spexeah.com/Spexeah/Wasuro.git`.
+- The `find` and `cp` utilities must be available.
+
+## Inputs
+
+| Source | Description |
+|--------|-------------|
+| Wasuro Git repository | Cloned (sparse, depth 1) from the `develop` branch. |
+
+## Outputs
+
+| File | Description |
+|------|-------------|
+| `wasuro/*.pas` | Pascal source files for the WASM runtime, ready for inclusion in the FPC build. |
+
+## Behavior
+
+1. **Cache check**: If `.pas` files already exist in `wasuro/`, the script prints a message and exits immediately, skipping the network fetch.
+2. **Sparse clone**: Clones the Wasuro repository into `/tmp/wasuro` with `--depth 1`, `--filter=blob:none`, and `--sparse`, then sets the sparse-checkout to `src/wasm`.
+3. **Copy**: Copies the contents of the cloned `src/wasm/` directory into `wasuro/`.
+4. **Cleanup**: Removes the temporary clone from `/tmp`.
+5. Reports the number of Pascal files copied.
+
+## Notes
+
+- The sparse checkout minimizes download size by fetching only the `src/wasm` subtree.
+- Once `wasuro/` is populated, subsequent builds reuse the cached files without re-cloning. To force a fresh pull, delete the `wasuro/` directory.
+- The script uses `set -e`, so any failure (network error, git error) aborts the build.

doc/toolchain/loc.md

@@ -1 +1,30 @@
-# Placeholder
+# loc.sh
+
+Counts the total lines of Pascal source code in the project.
+
+## Overview
+
+`loc.sh` is a utility script that counts the total number of lines across all `.pas` files in the project. It is called by `compile_vergen.sh` to embed a line count into the kernel's version metadata.
+
+## Prerequisites
+
+- `find`, `xargs`, `wc`, and `awk` must be available.
+
+## Inputs
+
+All `*.pas` files found recursively from the current working directory.
+
+## Outputs
+
+Prints a single line to stdout containing the total line count (e.g., `42567`).
+
+## Behavior
+
+1. Uses `find` to locate all `.pas` files starting from the current directory.
+2. Pipes the file list to `xargs wc -l` to count lines in each file.
+3. Uses `awk` to extract the grand total from the last line of `wc` output.
+
+## Notes
+
+- The output is consumed by `compile_vergen.sh` via command substitution and piped through `awk` to extract just the numeric value.
+- This script produces no files; it only writes to stdout.