fwoskrnl.exe - FreeWorld Kernel Executive

Overview

fwoskrnl.exe (FreeWorld Kernel Executive) is the core operating system component. It consists of multiple parts:

• kernel_entry.asm: Assembly boot code that handles real mode initialization, memory detection, and protected mode transition
• fwoskrnl.c: C kernel executive that provides system calls, manages memory, processes, and device drivers
• arch/x64/: 64-bit architecture support modules for long mode transition and 64-bit kernel operation

Kernel Entry Point (kernel_entry.asm)

The kernel entry point is loaded at 0x1000:0x0000 (linear address 0x10000) by the boot sector.

Kernel Magic Number

The first 8 bytes must be the kernel signature:

kernel_signature:
    db 'FREEWORL'  ; 8 bytes - must match boot sector

Initialization Sequence

1. Segment Setup: Initialize DS, ES, SS, SP
2. Hardware Init: Initialize serial port (COM1 at 0x3F8) for debugging
3. Memory Detection: Use INT 15h E820 to detect available memory
4. Protected Mode Transition: Set up GDT, enable A20, set CR0.PE, far jump to 32-bit code
5. IDT Setup: Initialize Interrupt Descriptor Table
6. 32-bit Subsystem Initialization: Initialize all 32-bit subsystems (memory, drivers, process, filesystem, graphics)
7. 64-bit Long Mode Transition: Check CPUID, set up 4-level paging, enable PAE and EFER, jump to 64-bit code
8. 64-bit Kernel Entry: Initialize 64-bit subsystems and enter main kernel loop

Protected Mode Transition

The transition from 16-bit real mode to 32-bit protected mode is critical. The sequence is:

1. cli                    ; Disable interrupts
2. Load GDT              ; lgdt [gdt_descriptor]
3. Enable A20            ; Fast method via port 0x92
4. Set CR0.PE            ; mov cr0, eax; or eax, 1; mov cr0, eax
5. Far jump              ; 32-bit jump to protected_mode_start (0x10191)

Critical: The far jump must be IMMEDIATELY after setting CR0.PE with no instructions in between.

Serial Port Configuration

The serial port (COM1 at 0x3F8) is configured for reliable interrupt output:

• Baud Rate: 38400 (divisor 0x0003)
• Line Control: 8 bits, no parity, 1 stop bit
• FIFO: Disabled (0x00) for reliable interrupt handler output
• Note: FIFO was disabled to prevent timing issues in interrupt handlers

Global Descriptor Table (GDT)

The GDT provides segment descriptors for protected mode:

• Null Descriptor (0x00): Required first entry
• Code Segment (0x08): Base=0x00000000, Limit=0xFFFFF (4GB), Type=0x9A (present, ring 0, code, executable/readable)
• Data Segment (0x10): Base=0x00000000, Limit=0xFFFFF (4GB), Type=0x92 (present, ring 0, data, writable)

Interrupt Descriptor Table (IDT)

A complete IDT is set up after entering protected mode. The IDT is located at 0x8000 and contains 256 entries (8 bytes each = 2048 bytes total).

IDT Entry Format (8 bytes)

Bytes 0-1:   Offset Low (bits 0-15 of handler address)
Bytes 2-3:   Segment Selector (0x08 = code segment)
Byte 4:      Reserved (must be 0)
Byte 5:      Flags (0x8E = Present, Ring 0, 32-bit interrupt gate)
Bytes 6-7:   Offset High (bits 16-31 of handler address)

IDT Entries

• 0-31: Exception Handlers - All 32 CPU exception vectors:
  • 0: Division by Zero
  • 1: Debug
  • 2: Non-Maskable Interrupt (NMI)
  • 3: Breakpoint
  • 4: Overflow
  • 5: Bound Range Exceeded
  • 6: Invalid Opcode
  • 7: Device Not Available
  • 8: Double Fault
  • 9: Coprocessor Segment Overrun
  • 10: Invalid TSS
  • 11: Segment Not Present
  • 12: Stack Fault
  • 13: General Protection Fault
  • 14: Page Fault
  • 15: Reserved
  • 16: x87 FPU Floating-Point Error
  • 17: Alignment Check
  • 18: Machine Check
  • 19: SIMD Floating-Point Exception
  • 20-31: Reserved exceptions
• 32 (0x20): Timer Interrupt (IRQ0) - timer_handler
• 33 (0x21): Keyboard Interrupt (IRQ1) - keyboard_handler
• 34-47 (0x22-0x2F): Other Hardware Interrupts - interrupt_handler_generic
• 128 (0x80): System Call - syscall_handler (Ring 3 accessible)
• 129-255 (0x81-0xFF): Reserved - interrupt_handler_generic

PIC Remapping

The Programmable Interrupt Controller (PIC) is remapped to avoid conflicts with CPU exceptions:

• Master PIC: IRQ0-7 → INT 0x20-0x27
• Slave PIC: IRQ8-15 → INT 0x28-0x2F
• IRQ0 (Timer): Unmasked (bit 0 cleared in IMR)
• IRQ1 (Keyboard): Unmasked (bit 1 cleared in IMR)

PIT Configuration

The Programmable Interval Timer (PIT) is explicitly configured:

• Channel: 0 (system timer)
• Mode: 2 (Rate Generator)
• Frequency: ~100 Hz (for faster testing, divisor = 11932)
• Ports: 0x43 (command), 0x40 (data)

Memory Detection (INT 15h E820)

The kernel uses the E820 memory map function to detect available memory:

detect_memory_e820:
    mov eax, 0xE820   ; E820 function code
    mov ecx, 24       ; Structure size
    mov edx, 0x534D4150 ; 'SMAP' signature
    int 0x15          ; BIOS interrupt

Memory map entries are stored at 0x1000:0x2000.

Data Structures

kernel_info_t

Kernel information structure:

typedef struct {
    uint64_t magic;         // Kernel magic number
    uint32_t version_major;
    uint32_t version_minor;
    uint64_t memory_base;   // Base memory address
    uint64_t memory_size;   // Total memory size
} kernel_info_t;

Functions

kernel_init

Initializes kernel subsystems:

void kernel_init(void);

Description: Initializes memory management, process scheduler, device drivers, and file system.

kernel_main

Kernel main entry point:

int kernel_main(void);

Returns: 0 on success

Description: Main kernel function called after boot. Initializes kernel and starts system services.

System Calls (from fwoskrnl.h)

int sys_read(int fd, void* buf, size_t count);
int sys_write(int fd, const void* buf, size_t count);
int sys_open(const char* path, int flags);
int sys_close(int fd);

Static Variables

Constants

Initialization Process

16-bit Real Mode Phase

1. Set up segments (DS, ES, SS, SP)
2. Initialize serial port (COM1 at 0x3F8, 38400 baud)
3. Display kernel messages
4. Detect memory using INT 15h E820
5. Enter protected mode

32-bit Protected Mode Phase

1. Set up segment registers (DS, ES, FS, GS, SS = 0x10)
2. Set up stack pointer (ESP = 0x90000)
3. Call kernel_subsystems_init() to initialize all subsystems:
   • I/O system (PIC remapping, serial ports)
   • Memory management (paging, frame allocator, heap)
   • Timer driver (system time tracking)
   • VGA driver (text mode display)
   • System call table (INT 0x80 handler)
   • IDT entries for hardware interrupts
   • Mouse driver (PS/2 mouse support)
   • Process manager (PCB, scheduling)
   • File system (kernel-level file operations)
   • Graphics bridge (VESA framebuffer, Node.js integration)
4. Transition to 64-bit long mode (see below)

64-bit Long Mode Phase

After all 32-bit subsystems are initialized, the kernel transitions to 64-bit long mode:

1. CPUID Check: Verify CPU supports long mode (EDX bit 29 in CPUID 0x80000001)
2. Disable Paging: Temporarily disable paging (clear CR0.PG) to modify page tables
3. 4-Level Paging Setup: Set up PML4, PDPT, PD, and PT tables for 64-bit virtual memory
   • PML4 at 0x200000 (Page Map Level 4)
   • PDPT at 0x201000 (Page Directory Pointer Table)
   • PD at 0x202000 (Page Directory)
   • PT at 0x203000 (Page Table)
   • Identity map first 2MB (512 pages × 4KB)
4. 64-bit GDT Setup: Load 64-bit Global Descriptor Table
   • Null descriptor (0x00)
   • 64-bit code segment (0x08) - base=0, limit=0, L=1 (long mode)
   • 64-bit data segment (0x10) - base=0, limit=0
5. Enable PAE: Set CR4.PAE bit (Physical Address Extension required for long mode)
6. Enable Long Mode: Set EFER.LME bit (Long Mode Enable) via MSR 0xC0000080
7. Enable Paging: Set CR0.PG bit (this activates long mode)
8. Far Jump: Jump to 64-bit code segment (0x08:long_mode_entry)
9. 64-bit Setup: Set up 64-bit segment registers (DS, ES, FS, GS, SS = 0x10)
10. 64-bit Stack: Set up 64-bit stack pointer (RSP = 0x200000)
11. 64-bit Kernel Entry: Call kernel_init_64() to initialize 64-bit subsystems

Kernel Subsystem Integration

The kernel uses kernel/integration.asm to wire all subsystems together. The kernel_subsystems_init() function initializes components in the correct order:

kernel_subsystems_init:
    1. I/O system init (PIC remapping, serial ports)
    2. Memory system init (paging, frame allocator, heap)
    3. IDT entries setup (timer, keyboard, mouse, syscall)
    4. Timer driver init
    5. VGA driver init
    6. Syscall table init
    7. Mouse IDT entry setup (IRQ 12 -> INT 0x2C)
    8. Mouse driver init
    9. Process manager init
    10. File system init
    11. Graphics bridge init
    12. Transition to 64-bit long mode (enter_long_mode)

Location: kernel/integration.asm

Status: ✅ Complete - All subsystems integrated, 64-bit transition implemented

New Components:

• Process Management - See Process Management
• File System - See File System
• Graphics Bridge - See Graphics System
• 64-bit Architecture Support - See 64-bit Long Mode section below

Remap PIC (Programmable Interrupt Controller)

The PIC is remapped to avoid conflicts with CPU exceptions:

• Master PIC: IRQ0-7 → INT 0x20-0x27
• Slave PIC: IRQ8-15 → INT 0x28-0x2F

Debug Output

During boot, the kernel outputs debug characters to the serial port (COM1 at 0x3F8):

Known Issues & Solutions

Protected Mode Transition Fix

Issue: The far jump was targeting the wrong address (0x10189 instead of 0x10191), causing execution to land in the middle of code.

Solution: Fixed by using the correct static address 0x10191 for the protected mode entry point.

Root Cause: NASM was calculating protected_mode_start - kernel_start + 0x10000 incorrectly due to label positioning.

Timer Interrupt Debugging (Current Issue)

Issue: Timer interrupts (IRQ0) are configured correctly (IDT entry verified with 'V'), but hardware timer interrupts are not firing. Manual int 0x20 test hangs.

Status: Debugging in progress. The following have been verified:

• ✅ IDT entry for timer (0x20) is correctly written and verified
• ✅ PIC remapping complete (IRQ0 → INT 0x20)
• ✅ IRQ0 unmasked in PIC (bit 0 cleared in IMR)
• ✅ PIT configured (Mode 2, ~100 Hz)
• ✅ Interrupts enabled (sti executed, IF flag set)
• ✅ Stack pointer set (ESP = 0x90000)
• ⚠️ Manual int 0x20 hangs (handler not executing)
• ⚠️ Hardware timer interrupts not firing

Debugging Steps Taken:

• Disabled FIFO in serial port for reliable interrupt output
• Added timeout to serial wait loops in interrupt handlers
• Explicitly configured PIT (don't rely on BIOS defaults)
• Simplified timer handler to minimal version (just EOI and return)
• Added extensive debug output to trace execution flow
• Verified IDT entry format and handler address calculation

Next Steps: Investigate IDT dispatch mechanism, stack setup during interrupts, and handler address calculation.

64-bit Architecture Support

FreeWorld OS includes full 64-bit (x64) long mode support. The kernel transitions through three execution modes:

1. 16-bit Real Mode: Initial boot from boot sector
2. 32-bit Protected Mode: Initial kernel setup and subsystem initialization
3. 64-bit Long Mode: Full 64-bit operation with extended addressing

64-bit Architecture Files

• kernel/arch/x64/long_mode.asm: Long mode transition code
  • enter_long_mode(): Main transition function
  • check_long_mode_support(): CPUID check for long mode
  • setup_64bit_paging(): 4-level page table initialization
  • setup_64bit_gdt(): 64-bit GDT setup
  • long_mode_entry: 64-bit code entry point
• kernel/arch/x64/kernel_64.asm: 64-bit kernel entry point
  • kernel_init_64(): 64-bit kernel initialization
  • init_64bit_subsystems(): 64-bit subsystem initialization
  • kernel_main_64(): 64-bit main kernel loop
  • print_string_64(): 64-bit string printing
• kernel/arch/x64/paging_64.asm: 64-bit paging support
  • init_paging_64(): Initialize 4-level paging
  • map_page_64(): Map virtual to physical address
  • unmap_page_64(): Unmap a page
• kernel/arch/x64/memory_64.asm: 64-bit memory management
  • memory_init_64(): 64-bit memory system initialization
  • frame_allocator_init_64(): 64-bit frame allocator (stub)
  • heap_init_64(): 64-bit heap allocator (stub)

Long Mode Transition Details

The transition from 32-bit to 64-bit mode requires several steps:

1. Check CPUID for long mode support (EDX bit 29)
2. Disable paging (clear CR0.PG)
3. Set up 4-level page tables (PML4 → PDPT → PD → PT)
4. Load 64-bit GDT (with L=1 bit for long mode)
5. Enable PAE (set CR4.PAE)
6. Enable long mode (set EFER.LME via MSR 0xC0000080)
7. Enable paging (set CR0.PG) - this activates long mode
8. Far jump to 64-bit code segment (0x08:long_mode_entry)
9. Set up 64-bit segment registers and stack
10. Call kernel_init_64()

4-Level Paging Structure

64-bit long mode uses 4-level paging (48-bit virtual addresses):

• PML4 (Page Map Level 4): 512 entries, 9 bits (bits 47-39)
• PDPT (Page Directory Pointer Table): 512 entries, 9 bits (bits 38-30)
• PD (Page Directory): 512 entries, 9 bits (bits 29-21)
• PT (Page Table): 512 entries, 9 bits (bits 20-12)
• Page Offset: 12 bits (bits 11-0)

Each page table entry is 8 bytes (64 bits), allowing for 48-bit physical addresses.

64-bit GDT Structure

The 64-bit GDT is simpler than 32-bit mode:

• Null Descriptor (0x00): Required first entry
• 64-bit Code Segment (0x08): Base=0, Limit=0, L=1 (long mode), D=0 (64-bit)
• 64-bit Data Segment (0x10): Base=0, Limit=0

In 64-bit mode, segment registers are mostly ignored (except FS and GS which can be used for thread-local storage).

Status

Integration Points

• freeload.exe: Loaded and executed by OS loader
• hal.dll: Uses HAL for hardware abstraction
• smss.exe: Starts session manager after initialization
• System Calls: Provides syscalls for user applications
• Process Manager: Manages processes and threads (see Process Management)
• File System: Provides file operations (see File System)
• Graphics Bridge: Connects to Node.js window system (see Graphics System)
• 64-bit Architecture: Long mode transition and 64-bit kernel (see 64-bit Architecture Support above)