ClankerOS Development Guide

Guide Claude Code when working on ClankerOS, an experimental operating system built collaboratively by a human architect and Claude (AI). The human provides architectural direction; Claude implements the code.

Project Context

Build Commands

Execute these commands in the project root:

```bash

First-time setup: Build cross-compiler toolchain

./scripts/build-toolchain.sh

export PATH="$PWD/toolchain/bin:$PATH"

Build kernel

make

Run in QEMU

make run # Basic VGA output

make run-serial # Serial output to stdio

make debug # With GDB server

Clean build artifacts

make clean

Documentation

make website # Generate website

make serve-website # Serve at http://localhost:8000

```

Running and Testing (CRITICAL FOR CLAUDE CODE)

**IMPORTANT**: When testing kernel functionality, you MUST:

1. **Use QEMU directly** with these exact parameters:

```bash

qemu-system-i386 -kernel kernel/clankeros.bin -serial stdio -append "earlycon"

```

2. **Always include `earlycon` kernel parameter** - without this, no serial output will be visible.

3. **Use serial output (`-serial stdio`)** to capture kernel logs and diagnostic information.

4. **Add VGA display for visual inspection** (display window shows VGA output automatically).

5. **Pass additional kernel parameters** via `-append` as needed:

```bash

# Test panic system

qemu-system-i386 -kernel kernel/clankeros.bin -serial stdio -append "earlycon testpanic"

# Test page fault handler

qemu-system-i386 -kernel kernel/clankeros.bin -serial stdio -append "earlycon testpagefault"

```

**Why**: `make run-serial` lacks the `earlycon` parameter required for serial output. You must call QEMU directly to see kernel logs.

Directory Structure

```

kernel/

├── arch/i386/ # x86-specific: boot.s, GDT, IDT, ISR, IRQ, PIC, PIT

├── core/ # Architecture-independent: main.c

└── include/ # Public kernel headers

libraries/

└── libclankercommon/ # Shared library (printf, writer interface)

├── include/clc/ # Headers with Clc prefix

└── src/ # Implementation

programs/ # Userspace programs (future)

scripts/ # Build scripts and utilities

docs/ # Session notes and coding style

```

Naming Conventions (STRICTLY ENFORCE)

Follow these exactly per docs/CODING_STYLE.md:

Public Functions: PascalCase with Module Prefix

Local Variables & Static Globals: camelCase

Private Static Functions: camelCase

Constants & Macros: UPPER_SNAKE_CASE

Module Prefixes

Brace Style: K&R (Kernighan & Ritchie)

```c

void FunctionName(void)

{

if (condition) {

DoSomething();

} else {

DoSomethingElse();

}

}

```

Opening brace on same line for control structures, new line for functions.

Key Design Patterns

Writer Interface (Rust-inspired Trait Objects)

Generic output abstraction using fat pointers:

```c

// Generic writer interface

typedef struct {

void (*putchar)(void* data, char c);

} ClcWriterVTable;

typedef struct {

void* data; // Fat pointer data

const ClcWriterVTable* vtable; // Fat pointer vtable

} ClcWriter;

// Usage

ClcWriter* vgaWriter = VidGetWriter();

ClcWriter* serialWriter = EConGetWriter();

ClcPrintfWriter(vgaWriter, "Booting %s\n", "ClankerOS");

```

x86 I/O Port Access

Use direct instruction names in kernel/include/x86.h:

```c

outb(PIC1_COMMAND, 0x20); // NOT IoWriteByte()

uint8_t value = inb(port); // NOT IoReadByte()

io_wait(); // Short delay via port 0x80

```

Interrupt Architecture

Hardware interrupts flow:

1. **Assembly stub** (irq_stubs.s): Saves CPU state, pushes interrupt number

2. **Common handler** (irq.c): Dispatches to registered C callback

3. **Send EOI**: Acknowledges interrupt to PIC

IRQs 0-15 remapped to interrupts 32-47 to avoid conflicts with CPU exceptions (0-31).

Implementation Instructions

1. **Read TODO.md** for current milestone and task list

2. **Follow coding style** in docs/CODING_STYLE.md strictly

3. **Consult session notes** in docs/sessions/ for context on past decisions

4. **Test changes** using QEMU with earlycon parameter (see above)

5. **Update TODO.md and README.md** when completing milestones

6. **Run before commits**: `scripts/copy-claude-data.sh`

Technical Details

Interrupt Numbering

- IRQ0 (32) = PIT timer

- IRQ1 (33) = Keyboard

- IRQ2 (34) = PIC cascade

Memory Layout

Currently identity mapping (virtual = physical). Paging not yet enabled.

Multiboot Information

Bootloader passes `multiboot_info_t*` to `KMain()`. Key fields:

Project Philosophy

Avoid backwards-compatibility hacks, premature abstractions, or unnecessary complexity. Delete unused code completely.

Current Status

**Completed**: Multiboot boot, VGA text mode, GDT, IDT, ISR, IRQ handlers, PIC, PIT (100Hz), early console (COM1), generic printf with writer interface

**Next Milestone**: Memory Management (physical allocator, multiboot memory map parsing, paging, kernel heap)