Command Reference

Complete documentation for the bootstrap command format

Command Format

bootstrap --level <n> --arch <arch> --mem <type>:<size> --sched <type>:<tasks> [--drivers <spec>] --entry <function>

All parameters except drivers are required. The command specifies a complete operating system configuration in a single line.

Kernel Level

The --level flag specifies kernel capability level.

Level Capability Output Size Use Case
0 Boot entry, halt ~2KB Bootloader foundation, hardware bring-up
1 Scheduler, basic HAL ~15KB Simple embedded systems, real-time control
2 Memory management ~40KB RTOS, embedded firmware with dynamic allocation
3 Full drivers, IPC ~80KB+ Microkernel, full-featured embedded OS

Note: L0 kernels cannot have schedulers. L0/L1 kernels cannot have block or network drivers.

Architecture

The --arch flag specifies target architecture.

Value Description
x86_64 64-bit x86 (Intel/AMD)
arm64 64-bit ARM (AArch64)

Memory Allocator

The --mem flag specifies allocator type and heap size.

Format: --mem <type>:<size>

Type Characteristics Best For
bump Sequential allocation, bulk free only Temporary allocations, parsing
pool Fixed-size blocks, O(1) alloc/free Same-size objects
slab Multiple size classes General-purpose allocation
buddy Power-of-2 coalescing Variable-size with coalescing

Size Format

Heap size can be specified with units:

Minimum: 1KB. Maximum: 4GB.

Scheduler

The --sched flag specifies scheduler type and maximum tasks.

Format: --sched <type>:<max_tasks>

Type Characteristics
round_robin Fair time-slicing, equal priority
priority Deterministic preemption, 32 priority levels

Maximum tasks: 1-256. Default tick rate: 100Hz.

Drivers

The --drivers flag specifies device drivers (optional).

Format: --drivers <name>:<config>[,<name>:<config>,...]

Prefix Type Examples
uart, gpio, spi, i2c Character uart:115200, gpio:32
ramdisk, sd, mmc, nvme Block ramdisk:1MB
eth, wifi, net Network eth:1000

Restrictions:

Entry Point

The --entry flag specifies the kernel entry function name.

Must be a valid C identifier (letters, numbers, underscores; cannot start with number).

Default: kernel_main

Examples

Minimal Bootloader (L0)

bootstrap --level 0 --arch x86_64 --mem bump:4KB --entry boot_main

Embedded RTOS (L1)

bootstrap --level 1 --arch arm64 --mem pool:64KB --sched round_robin:16 --drivers uart:115200 --entry firmware_main

Standard Kernel (L2)

bootstrap --level 2 --arch x86_64 --mem slab:16MB --sched priority:32 --entry kernel_main

Full Microkernel (L3)

bootstrap --level 3 --arch arm64 --mem buddy:128MB --sched priority:64 --drivers uart:115200,eth:1000,ramdisk:4MB --entry microkernel_main

Output

Generation produces a .tar.gz archive containing:

FONK Commitment

Each generated file includes a FONK commitment hash in its header:

/* FONK Commitment: e4709dc766145e869df5efbb5a3e4151c729bbd9aa6ab93b2aab9a3a60e14a3f */

This hash proves the code corresponds exactly to your specification. Same specification always produces identical code with the same commitment.

Building

Generated code compiles with standard freestanding toolchains:

x86_64

x86_64-elf-gcc -ffreestanding -nostdlib -c kernel.c -o kernel.o

arm64

aarch64-none-elf-gcc -ffreestanding -nostdlib -mcpu=cortex-a53 -c kernel.c -o kernel.o

Or simply run make in the extracted directory.