API Reference

All public functions, structures, enums and macros, organized by source module.

kernel/kernel.c

kernel_main kernel kernel/kernel.c

void kernel_main(void)

Entry point called by _start in boot.s. Initialises terminal, IDT, then calls powerup_kernel_i386(). Does not return (falls through to kern_exit label which triggers int $55).

Variable	Type	Description
boot_successful	static bool	Currently unused; intended boot-success flag
mem$paging_state	static int	Tracks paging state (MEM$PAGING_DISABLED)
input_allowed	extern bool	Set true by powerup; enables keyboard input

kernel/gdt.c — kernel/gdt.h

i686_GDT_Initialize kernel gdt.c / gdt.h

void i686_GDT_Initialize(void)

Loads g_GDTDescriptor via the lgdt instruction. Called from _start in boot.s before protected-mode switch.

Structures

struct GDTEntry — gdt.c

typedef struct {
    uint16_t LimitLow;      // limit[0:15]
    uint16_t BaseLow;       // base[0:15]
    uint8_t  BaseMiddle;    // base[16:23]
    uint8_t  Access;        // access byte (present | ring | type)
    uint8_t  FlagsLimitHi;  // limit[16:19] | flags[4:7]
    uint8_t  BaseHigh;      // base[24:31]
} __attribute__((packed)) GDTEntry;

struct GDTDescriptor — gdt.c

typedef struct {
    uint16_t  Limit;   // sizeof(g_GDT) - 1
    GDTEntry* Ptr;     // pointer to GDT array
} __attribute__((packed)) GDTDescriptor;

Enums

enum GDT_ACCESS — gdt.c

GDT_ACCESS_CODE_READABLE       = 0x02
GDT_ACCESS_DATA_WRITEABLE      = 0x02
GDT_ACCESS_CODE_CONFORMING     = 0x04
GDT_ACCESS_DATA_DIRECTION_NORMAL = 0x00
GDT_ACCESS_DATA_DIRECTION_DOWN = 0x04
GDT_ACCESS_DATA_SEGMENT        = 0x10
GDT_ACCESS_CODE_SEGMENT        = 0x18
GDT_ACCESS_DESCRIPTOR_TSS      = 0x00
GDT_ACCESS_RING0               = 0x00
GDT_ACCESS_RING1               = 0x20
GDT_ACCESS_RING2               = 0x40
GDT_ACCESS_RING3               = 0x60
GDT_ACCESS_PRESENT             = 0x80

enum GDT_FLAGS — gdt.c

GDT_FLAG_64BIT             = 0x20
GDT_FLAG_32BIT             = 0x40
GDT_FLAG_16BIT             = 0x00
GDT_FLAG_GRANULARITY_1B    = 0x00
GDT_FLAG_GRANULARITY_4K    = 0x80

kernel/idt.c — kernel/idt.h

init_idt kernel idt.c

void init_idt(void)

Initialises all 256 IDT gates with corresponding ASM ISR stubs using idt_set_gate. Calls init_pic(0x20, 0x28) to remap PIC. Calls register_routines(). Loads the IDT via lidt.

init_pic kernel idt.c

void init_pic(uint16_t master_offset, uint16_t slave_offset)

Sends the 4-word ICW sequence to both 8259A PICs via I/O ports. Remaps IRQ vectors and clears data registers. Called with master_offset=0x20, slave_offset=0x28.

iowait kernel idt.c

void iowait(void)

Issues a dummy outb to port 0x80 to create a small I/O delay between PIC configuration writes.

Structures

struct idt_entry_t — idt.h

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

struct idt_ptr_t — idt.h

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

PIC ICW Enums (idt.c)

enum PIC_ICW1 / PIC_ICW4

// ICW1
PIC_ICW1_ICW4        = 0x01   // ICW4 will be present
PIC_ICW1_SINGLE      = 0x02   // single (not cascade) mode
PIC_ICW1_INTERVAL4   = 0x04   // call address interval 4
PIC_ICW1_LEVEL       = 0x08   // level triggered mode
PIC_ICW1_INITIALIZE  = 0x10   // initialisation command

// ICW4
PIC_ICW4_8086        = 0x1    // 8086/88 mode
PIC_ICW4_AUTO_EOI    = 0x2    // automatic EOI
PIC_ICW4_BUFFER_MASTER = 0x4  // buffered master
PIC_ICW4_BUFFER_SLAVE  = 0x0  // buffered slave
PIC_ICW4_BUFFERRED   = 0x8    // buffered mode
PIC_ICW4_SFNM        = 0x10   // special fully nested mode

kernel/isr.c — kernel/isr.h

register_routines kernel isr.c

void register_routines(void)

Populates isr_map[] with function pointers for handled interrupts. Currently installs keyboard_read at KBD_INTERRUPT (0x21) and pagefault_hander at PGFLT_INTERRUPT (0x2E).

interrupt_handler kernel isr.c

void interrupt_handler(int intno)

Called from every ASM ISR stub. Sends EOI to slave PIC (if intno ≥ 40) then master PIC (if intno ≥ 32). Dispatches to isr_map[intno]() if handler is registered. Non-handled interrupts silently return.

Parameter	Description
intno	Interrupt vector number (0–255)

kernel/hwio.s — kernel/hwio.h

outb asm hwio.s / hwio.h

void outb(uint16_t port, uint8_t value)

Writes an 8-bit value to the specified I/O port using the x86 outb instruction.

inb asm hwio.s / hwio.h

uint8_t inb(uint16_t port)

Reads and returns an 8-bit value from the specified I/O port using the x86 inb instruction.

Macros (hwio.h)

Macro	Description
IDT_FLAG_PRESENT = 0x80	Present bit for IDT gate access byte
FLAG_SET(x, flag)	Sets bit(s) — x \|= flag
FLAG_UNSET(x, flag)	Clears bit(s) — x &= ~flag

libk/kio — libk/include/kio.h

k_print libk libk/kio/kio.c

size_t k_print(char* format, ...)

Printf-like variadic print function for the kernel. Outputs to the VGA terminal via terminal_writestring. Supports format specifiers for integers, strings, and hex values.

Usage pattern in the codebase:

k_print("[K_INFO] Initializing IDT\n");
k_print("[K_INFO] kernel now in protected mode cr0: %d \n", cr0);

libk/tty — libk/include/tty.h

Function	Signature	Description
terminal_initialize	`void (void)`	Clears VGA buffer, sets default colour, resets cursor
terminal_putchar	`void (char c)`	Writes one character; handles \n and scroll
terminal_writestring	`void (const char*)`	Writes NUL-terminated string
terminal_write	`void (const char*, size_t)`	Writes exactly size bytes
terminal_scroll_down	`void (void)`	Scrolls screen up by one row
terminal_setcolor	`void (uint8_t)`	Sets current fg/bg colour attribute
terminal_putentryat	`void (char, uint8_t, size_t x, size_t y)`	Writes char+colour at exact grid position
terminal_put_uint	`void (uint32_t d, INT_BASE base, void(*putc)(char))`	Prints unsigned integer in given base via callback
terminal_put_int	`void (int32_t d)`	Prints signed 32-bit integer (decimal)
strlen	`size_t (const char*)`	Freestanding strlen implementation
__terminal_move_line_save	`void (size_t row, int dir)`	Internal: shifts a row up/down for scrolling

Enums & Constants (tty.h / vgadef.h)

enum INT_BASE — tty.h

BINARY      = 2
OCTAL       = 8
DECIMAL     = 10
HEXADECIMAL = 16

enum vga_color — vgadef.h

VGA_COLOR_BLACK=0  VGA_COLOR_BLUE=1   VGA_COLOR_GREEN=2    VGA_COLOR_CYAN=3
VGA_COLOR_RED=4    VGA_COLOR_MAGENTA=5 VGA_COLOR_BROWN=6   VGA_COLOR_LIGHT_GREY=7
VGA_COLOR_DARK_GREY=8  VGA_COLOR_LIGHT_BLUE=9  VGA_COLOR_LIGHT_GREEN=10
VGA_COLOR_LIGHT_CYAN=11  VGA_COLOR_LIGHT_RED=12  VGA_COLOR_LIGHT_MAGENTA=13
VGA_COLOR_LIGHT_BROWN=14  VGA_COLOR_WHITE=15

Constant	Value	Description
VGA_WIDTH	80	Terminal columns
VGA_HEIGHT	24	Terminal rows
K_PRINT_MAX_BUF	sizeof(long int)*8	Max buffer for integer-to-string conversion
BLANK_CHAR	0x20	Space character used for clearing

libk/tty (ttyin) — libk/include/ttyin.h

keyboard_read libk libk/tty/ttyin.c

void keyboard_read(void)

PS/2 keyboard ISR handler. Called by interrupt_handler on IRQ 1 (vector 0x21). Reads scan code from port 0x60, calls keyboard_to_ascii, and echoes to terminal.

keyboard_to_ascii libk libk/tty/ttyin.c

uint8_t keyboard_to_ascii(uint8_t key)

Converts a PS/2 scan code byte to its ASCII equivalent using the static QWERTY lookup tables.

KEYCODE Enum (ttyin.h) — Key Scan Codes

Key	Pressed	Released
Q–P row	0x10–0x19	0x90–0x99
A–L row	0x1E–0x26	0x9E–0xA6
Z–M row	0x2C–0x32	0xAC–0xB2
BACKSPACE	0x0E	0x8E
SPACE	0x39	0xB9
ENTER	0x1C	0x9C
POINT	0x34	0xB4

libk/util — libk/include/util.h

lazy$check_integrity libk libk/util/memory.c

size_t lazy$check_integrity(const struct lazy$block* lb)

Validates a lazy$block: checks lb$base_addr != NULL and lb$limit != 0. Returns UTIL$SUCCESS, LAZY$LIMINV, LAZY$BASEINV, or LAZY$BLOCKINV.

util$blkcpy_weak libk libk/util/memory.c

size_t util$blkcpy_weak(struct lazy$block* dest, const struct lazy$block* src)

Copies min(dest.limit, src.limit) bytes from src to dest. Returns UTIL$SUCCESS if limits match, UTIL$MEMTRUNC if truncated.

util$blkcpy_strong libk libk/util/memory.c

size_t util$blkcpy_strong(struct lazy$block* dest, const struct lazy$block* src)

Copies src to dest only if dest.limit >= src.limit. Returns UTIL$FAIL if dest is too small.

util$self_test libk libk/util/memory.c

size_t util$self_test(void)

Runs internal tests for blkcpy_weak, blkcpy_strong, and paging. Called during powerup_kernel_i386. Returns UTIL$SUCCESS or UTIL$FAIL. Uses TEST$ARRAY_LIMIT = 1024 byte buffers.

lazy$block Structure

struct lazy$block — util.h

struct lazy$block {
    char*    lb$base_addr;   // base pointer to memory region
    uint64_t lb$limit;       // byte length of region
};

kernel/compat/i386

powerup_kernel_i386 compat compat/i386/kern_powerup.c

uint16_t powerup_kernel_i386(void)

Architecture-specific kernel powerup sequence. Checks CR0 protected-mode bit, calls mem$setup_paging(), runs util$self_test(). Sets input_allowed = true on success.

Return Value	Meaning
KERN$PWRUP (1)	All subsystems initialised successfully
KERN$PWRDOWN (0)	At least one subsystem failed

mem$setup_paging compat compat/i386/vm_watchdog.c

uint16_t mem$setup_paging(void)

Identity-maps the first 4 MiB (1024 pages × 4 KiB). Loads page_directory into CR3, sets CR0 bit 31 (PG) to enable paging. Returns UTIL$SUCCESS.

Precondition: Protected mode must be active before calling this function.

pagefault_hander compat compat/i386/vm_watchdog.c

void pagefault_hander(void)

Registered in isr_map[PGFLT_INTERRUPT]. Currently prints "Pagefault occured backing up\n" and returns without taking recovery action. Note: function name has a typo ("hander" → "handler").

Global Macros & Constants

Macro / Constant	Defined In	Value	Purpose
MAP_IRQ(irq)	idt.h	irq + 0x20	Maps hardware IRQ to IDT vector
KBD_INTERRUPT	idt.h	MAP_IRQ(1) = 0x21	Keyboard IRQ vector
PGFLT_INTERRUPT	idt.h	MAP_IRQ(14) = 0x2E	Page fault IRQ vector
KERN$PWRUP	kern_powerup.h	1	Kernel powerup success
KERN$PWRDOWN	kern_powerup.h	0	Kernel powerup failure
UTIL$SUCCESS	util.h	0x1	Generic success code
UTIL$FAIL	util.h	0x0	Generic failure code
UTIL$MEMTRUNC	util.h	0x2	Successful but data truncated
LAZY$LIMINV	util.h	0x2	lazy$block limit invalid
LAZY$BASEINV	util.h	0x4	lazy$block base invalid
LAZY$BLOCKINV	util.h	0x6	Both base and limit invalid
TEST$ARRAY_LIMIT	util.h	1024	Self-test buffer size
IDT_FLAG_PRESENT	hwio.h	0x80	IDT gate present bit
i686_GDT_CODE_SEGMENT	gdt.h	0x08	Kernel code segment selector
i686_GDT_DATA_SEGMENT	gdt.h	0x10	Kernel data segment selector
PIC1 / PIC1_COMMAND	idt.h	0x20	Master PIC command port
PIC2 / PIC2_COMMAND	idt.h	0xA0	Slave PIC command port
VGA_WIDTH	vgadef.h	80	Terminal width in columns
VGA_HEIGHT	vgadef.h	24	Terminal height in rows