Architecture & Boot Flow

Detailed walkthrough of system initialisation, hardware setup, and subsystem design.

Boot Flow

GRUB discovers the Multiboot header and jumps to _start in boot.s. From there, a precise initialisation sequence brings the system to a usable state.

GDT Layout

Five descriptor entries configured in gdt.c. 4 KiB granularity, 32-bit flag. Code and data segments overlap (flat model). Loaded by i686_GDT_Initialize using lgdt.

GDTEntry Fields

typedef struct {
    uint16_t LimitLow;       // limit bits 0–15
    uint16_t BaseLow;        // base  bits 0–15
    uint8_t  BaseMiddle;     // base  bits 16–23
    uint8_t  Access;         // access byte (ring, type, present)
    uint8_t  FlagsLimitHi;   // limit bits 16–19 | flags (32-bit, 4K gran)
    uint8_t  BaseHigh;       // base  bits 24–31
} __attribute__((packed)) GDTEntry;

IDT & PIC

idt.c allocates a 256-entry IDT and initialises both PIC chips via the ICW sequence.

typedef struct {
    uint16_t offset_low;        // ISR addr[0:15]
    uint16_t segment_selector;  // code selector (0x08)
    uint8_t  alwaysZero;
    uint8_t  access_gran;       // flags: 0x8E = present, 32-bit trap
    uint16_t offset_high;       // ISR addr[16:31]
} __attribute__((packed)) idt_entry_t;

typedef struct {
    uint16_t limit;   // sizeof(idt_entry_t)*256 - 1
    uint32_t base;    // address of idt_entries[]
} __attribute__((packed)) idt_ptr_t;

PIC Remapping (init_pic)

The 8259A PIC's default vectors (0–15) conflict with CPU exceptions. They are remapped:

Interrupt Vectors Summary

Paging (vm_watchdog.c)

mem$setup_paging() establishes a simple identity-mapped page table covering the first 4 MiB of physical memory.

// 1. Fill page_table[1024]: entry i = (i * 0x1000) | 3  (present + RW)
// 2. Set page_directory[0] = &page_table | 3
// 3. mov &page_directory → CR3
// 4. Read CR0, set bit 31 (PG), write back → paging enabled

Memory Map (Runtime)

Interrupt Handling Flow

When a hardware interrupt fires, control passes through several layers:

CPU raises interrupt vector N
  → IDT gate[N].offset → ASM stub in idt_hndlr_setup.s
      → saves registers, pushes N
          → calls interrupt_handler(N)   [isr.c]
              → if N >= 40: outb(0xA0, PIC_ACK)  // EOI to slave
              → if N >= 32: outb(0x20, PIC_ACK)  // EOI to master
              → if isr_map[N] != NULL: call isr_map[N]()
                  → e.g. keyboard_read()   [ttyin.c]
                  → e.g. pagefault_hander() [vm_watchdog.c]

ISR Map Registration (isr.c)

void register_routines() {
    isr_map[KBD_INTERRUPT]   = &keyboard_read;     // 0x21
    isr_map[PGFLT_INTERRUPT] = &pagefault_hander;  // 0x2E
}

VGA Text-Mode Terminal (libk/tty)

The terminal writes directly to the VGA buffer at physical address 0xB8000. Each cell is 2 bytes: character + attribute (fg|bg colour).

// bits [15:8] = attribute (color)
// bits [7:0]  = ASCII character
uint16_t vga_entry(char c, uint8_t color);
uint8_t  vga_entry_color(vga_color fg, vga_color bg);

Key Terminal Functions

libk — Memory Utilities (util.h / memory.c)

Provides a safe block-copy abstraction using lazy$block descriptors.

struct lazy$block {
    char*    lb$base_addr;   // pointer to memory region
    uint64_t lb$limit;       // length in bytes
};

Status Codes