Fern Kernel Overview

Fern is the kernel of Forest OS (codename ALDER), a Unix-like, POSIX-oriented operating system. Fern handles everything from physical memory management and process scheduling to device drivers, graphics, networking, and audio — all in a single monolithic binary (fern.elf for ELF, fern.bin for BIOS).

Forest OS is deliberately kernel-oriented: it does not bundle a graphical desktop or a userspace application suite. The kernel ships alongside ForeB (the bootloader) and a consolidated POSIX-oriented C library, which together produce a bootable ISO.

Design Philosophy

Fern follows a monolithic kernel design, meaning all kernel subsystems -- drivers, filesystems, memory management, networking -- run in a single privileged address space. This is a deliberate choice: it keeps inter-subsystem communication fast (direct function calls instead of IPC), simplifies DMA and memory sharing, and matches the POSIX/Linux heritage the project targets.

Key design principles:

• POSIX-oriented: The kernel targets POSIX interfaces (signals, termios, process groups, sysv IPC, shared memory, epoll, inotify) so that familiar Unix userspace software can eventually run on Forest OS.
• Configurable via feature flags: Nearly every subsystem can be independently enabled or disabled at build time. This keeps the kernel adaptable -- from a tiny embedded profile (8 MB RAM minimum) to a full-featured desktop build.
• Multi-architecture: Supports x86 (32-bit and 64-bit), ARM32, AArch64, and RISC-V 64-bit. Architecture-specific code lives in dedicated subdirectories under src/.
• Defensive boot: The boot sequence is carefully ordered to detect failures early, display rich status output (or a splash screen), and gracefully fall back when hardware is unavailable (e.g., framebuffer failure drops to VGA text mode).
• Self-contained: The kernel includes its own ELF loader, initrd parser, and userspace boot path, making it bootable without external dependencies beyond the bootloader.

Kernel Subsystems

Fern is organized into a large number of subsystems, each independently gated by build-time feature flags. Here's a quick reference:

Source Directory Layout

The kernel source tree at fern/src/ is organized as follows:

fern/
├── build/
│   ├── features/          # Feature-flag .mk fragments (memory, graphics, networking, ...)
│   ├── config.mk          # Core build configuration (ARCH, BOOT_MODE, etc.)
│   ├── dirs.mk            # Output directory definitions
│   ├── flags.mk           # Compiler/linker flags
│   ├── kernel-sources.mk  # Source file selection and exclusion logic
│   ├── toolchain.mk       # Cross-toolchain detection
│   ├── iso.mk             # ISO image creation
│   ├── foreb.mk           # ForeB bootloader build
│   ├── qemu-run.mk        # QEMU launch targets
│   └── clean.mk           # Cleanup targets
├── src/
│   ├── kernel.c           # kmain() and boot sequence -- the entry point
│   ├── boot.asm           # 32-bit boot stub (Multiboot)
│   ├── boot64.asm         # 64-bit boot stub
│   ├── gdt.c / gdt64.c    # Global Descriptor Table
│   ├── idt.c / idt64.c    # Interrupt Descriptor Table
│   ├── context_switch.asm # Process context switch
│   ├── interrupt_stubs.asm # Interrupt entry stubs
│   ├── include/           # All kernel headers (231 headers)
│   │   ├── memory.h       # Memory subsystem API
│   │   ├── task.h         # Process/task API
│   │   ├── vfs.h          # Virtual filesystem API
│   │   ├── interrupt.h    # Interrupt system API
│   │   ├── graphics/      # Graphics subsystem headers
│   │   ├── usb/           # USB subsystem headers
│   │   └── sys/           # POSIX-style system headers
│   ├── graphics/          # Graphics drivers (vesa, bochs, intel, nvidia, amd, font)
│   │   └── drivers/       # Individual GPU drivers
│   ├── gl/                # Software OpenGL renderer
│   ├── input/             # Input subsystem (keyboard, mouse, input mux)
│   ├── networking/        # Network protocol implementations
│   ├── usb/               # USB subsystem internals
│   ├── uefi/              # UEFI boot support
│   ├── bios/              # BIOS boot support
│   ├── arch/              # Architecture-specific wrappers
│   ├── arm32/             # ARM 32-bit architecture code
│   ├── aarch64/           # ARM 64-bit architecture code
│   ├── riscv64/           # RISC-V 64-bit architecture code
│   ├── x86_64/            # x86-64 architecture code
│   └── crossarcinterpret/ # Cross-architecture interpreter
├── libs/
│   ├── forestcore/        # Low-level kernel runtime helpers
│   ├── libc/              # POSIX C standard library
│   ├── leafgfx/           # LeafGFX graphics library (BMP, TTF, animation)
│   ├── leafui/            # LeafUI widget framework
│   ├── uacpi/             # Third-party ACPI implementation (subtree)
│   └── qrcodegen/         # QR code generation library
├── forestlibs/            # Exported libc snapshot
├── initrd/                # Initial ramdisk filesystem template
│   ├── bin/               # /bin (init, shell, utilities)
│   ├── dev/               # /dev (device nodes)
│   ├── etc/               # /etc (configuration)
│   ├── proc/              # /proc (process information)
│   ├── tmp/               # /tmp (temporary files)
│   ├── usr/               # /usr (shared resources, icons, fonts)
│   └── var/               # /var (variable data)
├── Makefile               # Top-level build orchestrator
├── conf.sh                # Configuration generator (Kconfig-style)
└── build-config.mk        # Generated build configuration

Feature Flags

Fern uses a Kconfig-style configuration system. conf.sh generates build-config.mk from .forestos_config, and each ENABLE_ boolean controls whether a subsystem's source files are compiled. The build/features/.mk fragments implement the source gating.

Memory Features

Graphics Features

Networking Features

Audio Features

USB Features

Storage Features

Filesystem Features

Interrupt Features

Scheduler / Process Features

Security Features

Hardware / Compatibility

Kernel Initialization Sequence

The boot sequence starts at startk() (src/kernel.c:1367) after the bootloader (ForeB or GRUB) transfers control. The sequence is carefully ordered to ensure each subsystem can depend on its prerequisites:

Phase 1: Early Boot (pre-VMM)

1. Disable interrupts -- Prevent any interrupt-driven code from running before the IDT is ready.
2. Save multiboot info -- Multiboot magic and MBI address are saved immediately to globals to survive stack corruption.
3. GDT initialization -- Sets up the Global Descriptor Table for flat-memory model.
4. Early interrupt init -- Minimal IDT setup with safe interrupt stubs.
5. Debug logging init -- Early serial/file-based debug log.
6. Parse kernel command line -- Extracts quiet, silent, embedded, nofb, livecd, video=WIDTHxHEIGHTxBPP tokens from multiboot.
7. Parse multiboot framebuffer -- Extracts framebuffer physical address, dimensions, and BPP from Multiboot1/2 tags before VMM init.
8. Display early info -- Prints kernel version, CPU info, and framebuffer details.

Phase 2: Memory Subsystem

1. Init system -- Sets up display configuration defaults.
2. Full interrupt init -- Completes IDT, PIC/APIC setup.
3. FPU initialization -- Enables floating-point hardware if present.
4. Syscall init -- Installs the syscall entry point (int 0x80 / syscall).
5. Hardware detection -- CPUID-based feature detection.
6. Driver core -- Initializes the driver registry and bus abstraction.
7. Memory validation -- Validates memory map integrity.
8. Memory init -- memory_init() parses the multiboot memory map, sets up physical-to-virtual mapping, and enables paging.
9. Framebuffer finalization -- Maps the framebuffer to virtual address 0xF0000000 after VMM is live.
10. Reserve initrd -- Marks initrd memory region as reserved in the PMM.
11. Framebuffer console -- Initializes the framebuffer TTY with ANSI support (or falls back to VGA text mode).
12. GL software renderer -- Optionally initializes the software OpenGL renderer.
13. Memory region manager -- Intelligent region tracking.
14. Page fault recovery -- Graceful page fault handling.
15. Bitmap PMM -- Bitmap-based physical memory manager initialization with test.
16. Enhanced Memory v2.0:

• Memory layout analysis
• Memory statistics
• Paging mode manager
• TLB management
• Memory protection (NX, SMEP, SMAP, PAT)
• Stack protection (canaries)
• Stack smashing protection (SSP)
• Secure VMM
• Memory corruption detection

1. Enhanced heap allocator -- Configurable heap with corruption detection and fragmentation mitigation.
2. Advanced memory features -- Copy-on-Write, Swap, memory statistics snapshot.

Phase 3: Core Kernel

1. Task management -- tasks_init() creates the process table and scheduler.
2. ACPI discovery -- Parses ACPI tables via uACPI (with timeout protection).
3. SMP CPU discovery -- Reads ACPI MADT; Application Processors are started via INIT-SIPI-SIPI sequence.
4. PCI enumeration -- Discovers PCI/PCIe devices.
5. ATA detection -- Probes legacy ATA/IDE controllers.
6. VirtualBox Guest -- Detects and initializes VirtualBox Guest Additions.

Phase 4: Devices and Filesystems

1. Input event multiplexer -- Sets up the input event pipeline.
2. Hotkey manager -- Global hotkey registration.
3. DevFS -- /dev filesystem with device nodes:

• Input devices (/dev/kbd, /dev/mouse)
• Timer devices (/dev/timer, /dev/rtc)
• Framebuffer info (/dev/fb_width, etc.)
• PCI devices (/dev/pci/*)
• Block devices (/dev/sd, /dev/loop)

1. USB subsystem -- USB host controller and device enumeration.
2. PS/2 controller -- Reset, self-test, and initialization.
3. PS/2 keyboard -- Driver init, IRQ handler registration (IRQ1).
4. PS/2 mouse -- Driver init, IRQ handler registration (IRQ12).
5. PS/2 watchdog -- Hotplug recovery for PS/2 disconnects.

Phase 5: Filesystem and Userspace

1. Initrd -- Parses the USTAR initrd image from memory.
2. VFS mount -- Mounts the root filesystem from the initrd.
3. Timer init -- 100 Hz PIT/APIC timer for task scheduling.
4. Epoch init -- Wall-clock time from RTC hardware.
5. Sound subsystem -- Audio driver initialization (if enabled).
6. Lock debugging -- Lock contention tracking.
7. ELF loader validation -- Self-test of the ELF loader.

Phase 6: Finalization

1. Enable interrupts -- sti allows timer IRQ to fire, enabling the scheduler.
2. Splash cleanup -- Stops the boot splash and fades out.
3. TTY mode switch -- Exits boot mode, switches framebuffer TTY to normal operation.
4. Idle loop -- Enters hlt-based idle loop (kernel-only build).

Interrupt and Exception Handling

Fern implements a comprehensive interrupt architecture that scales from the legacy 8259A PIC to the modern APIC/IOAPIC system:

Interrupt Controllers

• 8259A PIC: Legacy dual-chip interrupt controller for basic IRQ routing (IRQ 0-15).
• Local APIC: Per-CPU interrupt controller for IPIs and timer interrupts.
• IOAPIC: System-level interrupt routing for device IRQs.

IDT Setup

The Interrupt Descriptor Table supports up to 256 entries:

• Vectors 0-31: CPU exceptions (divide error, page fault, general protection, etc.)
• Vectors 32+: Hardware IRQs (offset by IRQ_BASE_OFFSET = 32)
• Vector 0x80: System call entry (int 0x80 for 32-bit, syscall for 64-bit)
• Vector 0xFF: Spurious interrupt handler

Interrupt Features

• Vector allocation: Dynamic allocation of interrupt vectors for device drivers.
• Priority management: Per-interrupt priority levels for nested handling.
• EOI management: Proper End-of-Interrupt signaling to PIC/APIC.
• Statistics: Runtime interrupt count tracking and profiling.
• Stack switching: Automatic stack switch on interrupt entry.
• NMI handling: Non-maskable interrupt support for hardware errors.

Exception Handling

CPU exceptions are dispatched through the IDT to handlers in exceptions.c. Page faults go through a recovery system (page_fault_recovery.c) that can handle:

• Copy-on-write faults (for fork())
• Demand paging (lazy allocation)
• User-space memory violations

Kernel Internal Libraries

libs/forestcore/ -- ForestCore Runtime

Low-level kernel runtime helpers that don't belong in the exported C library:

• types.h, system.h, net.h -- Forest-specific type definitions and system helpers
• MMIO and I/O port access wrappers
• Audio, string, and utility functions

libs/libc/ -- C Standard Library

The POSIX-oriented C library targeting the Forest OS ABI. Aligned with ISO C headers; provides the userspace API surface.

libs/leafgfx/ -- LeafGFX Graphics Library

A self-contained 2D graphics library used by the graphics subsystem:

• BMP image loading (leafgfx_bmp.c)
• TrueType font rendering (leafgfx_ttf.c, leafgfx_ttf_raster.c)
• Bitmap font rendering (leafgfx_font.c)
• Animation support (leafgfx_anim.c)
• Input handling (leafgfx_input.c)
• Modern rendering pipeline (leafgfx_modern.c)

libs/leafui/ -- LeafUI Widget Framework

Header-only UI widget framework for building graphical interfaces within the kernel (panic UI, login screen, etc.).

libs/uacpi/ -- uACPI

Third-party ACPI implementation pulled in as a subtree. Provides table parsing, AML evaluation, and ACPI device enumeration.

libs/qrcodegen/ -- QR Code Generator

Minimal QR code generation library, likely used for boot-time display or debugging.

forestlibs/ -- Exported Libraries

Snapshot of the exported libc for distribution to userspace.

The Initrd Filesystem

The initial ramdisk (initrd) is the root filesystem loaded into memory by the bootloader. It provides the minimal environment needed to boot to a working system:

initrd/
├── bin/          # Essential binaries (init, shell, utilities)
├── dev/          # Device nodes (populated by DevFS at runtime)
├── etc/          # Configuration files (/etc/livecd marker, auth config)
├── proc/         # Mount point for procfs (/proc)
├── tmp/          # Temporary files
├── usr/          # Shared resources
│   └── share/
│       └── images/icons/   # Icon theme (hicolor scalable SVGs)
└── var/          # Variable data

The initrd is packed as a USTAR archive and embedded in the kernel image or loaded by the bootloader as a Multiboot module. The kernel's ramdisk_init() function locates it in memory (via multiboot info), and vfs_init() mounts it as the root filesystem.

The initrd includes a comprehensive icon theme with scalable SVG icons for:

• Application types (executables, scripts, documents, archives)
• File types (text, images, audio, video, fonts)
• Device categories (drives, printers, cameras, audio)
• Filesystem locations (home, desktop, trash, folders)

Supported Architectures

Fern supports multiple CPU architectures through a combination of architecture-specific source directories, conditional compilation, and linker scripts:

How Multi-Arch is Handled

1. Architecture detection: build/config.mk reads the ARCH variable and sets TARGET_ARCH and TARGET_TUPLE accordingly.

1. Source selection: Architecture-specific source files are organized in dedicated directories:

• src/aarch64/ -- AArch64-specific code (boot, interrupts, timer, sound stubs)
• src/arm32/ -- ARM 32-bit code
• src/riscv64/ -- RISC-V 64-bit code
• src/x86_64/ -- x86-64 specific code (IST handling)
• src/arch/ -- Cross-architecture wrapper layer

1. Conditional compilation: #ifdef __x86_64__, #if ARCH_64BIT, and similar guards in C code select architecture-appropriate implementations. For example, kernel.c uses 64-bit page table manipulation on x86-64 and 32-bit paging on i686.

1. Linker scripts: Different linker scripts handle memory layout differences:

• link.ld -- 32-bit BIOS
• link64.ld -- 64-bit BIOS
• link_uefi_32.ld, link_uefi_64.ld -- UEFI variants
• link_uefi_aarch64.ld -- AArch64 UEFI

1. Assembly: Architecture-specific assembly files (boot.asm, boot64.asm, context_switch.asm, interrupt_stubs.asm) provide the lowest-level entry points and context switch code. The Makefile selects the correct variant based on ARCH.

1. Build targets: Top-level Make targets (build32, build64, buildarm, buildaarch64, buildriscv64) recursively invoke make with the appropriate ARCH= override.

1. Cross-architecture interpreter: An optional subsystem (ENABLE_CROSSARC_INTERPRETER) can interpret instructions from other architectures, enabling binary compatibility scenarios.

Key Design Decisions and Trade-offs

Monolithic vs. Microkernel

Fern chose a monolithic design. While microkernels (like Minix or seL4) offer better isolation, a monolithic design:

• Makes DMA and buffer sharing between drivers trivial
• Avoids the performance overhead of IPC for frequent operations
• Aligns with the Linux/Unix heritage the project targets
• Is significantly simpler to implement for a small team

The trade-off is that a buggy driver can crash the whole kernel, which is why Fern invests heavily in memory protection (SMEP/SMAP, stack canaries, page fault recovery, guard pages).

In-Kernel Display Server

Fern includes an in-kernel Wayland compositor and X11 server. This is unusual -- most Unix-like OSes run display servers in userspace. The rationale:

• Simplifies the boot-to-desktop path (no userspace needed for graphics)
• Provides a graphical panic UI and login screen without userspace dependencies
• The kernel is the only thing that needs to run for a working system

The trade-off is increased kernel complexity and attack surface. This is mitigated by making the display server optional via feature flags.

Configurable Feature Flags

With 180+ feature flags, Fern can be built as a minimal embedded kernel (~8 MB RAM) or a full-featured desktop kernel. Each flag gates specific source files via build/features/*.mk, keeping compile times reasonable for minimal builds.

Embedded Mode

The embedded kernel command-line token activates reduced memory profiles:

• Minimum RAM drops from 64 MB to 8 MB
• Max heap reduced from 128 MB to 8 MB
• Heap expansion increment reduced from 64 KB to 16 KB
• Corruption detection and fragmentation mitigation disabled
• Graphics memory pool skipped

No Root Filesystem in Kernel

Fern ships without a userspace. The kernel boots, initializes all subsystems, and enters an idle loop. This keeps the kernel self-contained and testable independently. Userspace (ForeB, libc, applications) is layered on top separately.

Defensive Boot Sequence

The boot sequence includes:

• Timeout protection for ACPI initialization
• Automatic fallback from framebuffer to VGA text mode
• PS/2 controller flush to clear stale firmware bytes
• Multiple memory validation stages
• Graceful handling of missing hardware (e.g., no mouse, no sound)

Debug-Friendly

The kernel includes extensive debugging support: CONFIG_DEBUG_BOOT for verbose boot logging, lock debugging to detect deadlocks, memory corruption detection, stack trace support, a graphical panic UI, serial debug output, and multiple log levels.

Building the Kernel

make defconfig        # Configure with sane defaults
make build            # Build the kernel binary
make iso              # Create bootable ISO
make run              # Launch in QEMU
make menuconfig       # Interactive config TUI
make configcheck      # Validate current config