Freestanding mode

Freestanding mode compiles Quadrate with no libc and no hosted operating system, for kernels, bootloaders, microcontrollers, and anything else that runs on bare metal.

quadc --freestanding kernel.qd -o kernel.o

The output is a relocatable object file, not an executable. You link it yourself, against your own entry stub and linker script.

What changes

Hosted build --freestanding
quadc emits int main(int, char**) and links an executable quadc emits a void _start(void) shim and stops at .o
Runtime context is heap-allocated per run A single statically allocated qd_freestanding_ctx
Whole stdlib available bits, limits, mem, sys, plus your own .qd files
print/panic work Rejected at compile time
A fatal error prints a stack trace and aborts It calls qd_freestanding_halt()

The entry point

Declare _start (or main) as a pub fn taking and returning nothing:

pub fn _start( -- ) {
    // kernel body
}

quadc emits a C-callable void _start(void) that hands your function the static context and calls qd_freestanding_halt() when it returns. Your assembly entry stub sets up a stack and jumps here.

Dead-code elimination is disabled in freestanding mode, because pub functions are routinely called from assembly and nothing in the Quadrate side references them.

What you can use

Allowed modules — bits, limits, mem, sys. Everything else either allocates or calls into libc, so use io (and friends) is a compile error. Your own file imports (use "vga.qd") are always allowed: you control what is in them.

mem is split at build time. libmem-freestanding.a contains only the raw memory operations — set_byte/get_byte, set_i64/get_i64, set_f64/get_f64, set_ptr/get_ptr, the sized set_i8…get_u32 accessors, copy, zero, fill, ptr_add, is_null, is_not_null. The allocating half (alloc, realloc, free, to_string, from_string) lives in libmem.a and is simply not linked, so reaching for it is a link error rather than a silent heap dependency.

Rejected builtins — print, dump, nl, panic, err. Each gives builtin 'X' is not available in --freestanding mode. Arithmetic, comparison, bitwise ops, stack manipulation, locals, if/loop/for/switch, structs, arrays, function values and FFI all work normally.

The sys module

sys is the bare-metal escape hatch. Every function is inline, so the compiler lowers it to instructions with no call overhead and no runtime dependency.

Raw memory — these lower directly to LLVM store/load. No runtime call, no libc. This is how a kernel touches MMIO and hardware registers without an FFI shim.

use sys

const VGA_BASE = 0xB8000

fn cell(row:i64 col:i64 -- addr:i64) {
    swap 80 * + 2 * VGA_BASE +
}

fn vga_put(row:i64 col:i64 ch:i64 -- ) {
    rrot cell
    dup 1 0x0F sys::st8
    0 rot sys::st8
}
Function Effect
sys::st8 / st16 / st32 / st64 (addr:i64 offset:i64 value:i64 -- ) — store the low 8/16/32/64 bits
sys::ld8 / ld16 / ld32 / ld64 (addr:i64 offset:i64 -- value:i64) — load, zero-extended

x86 I/O ports — sys::outb / outw / outl (port:i64 value:i64 -- ) and sys::inb / inw / inl (port:i64 -- value:i64).

CPU control — sys::cli, sys::sti, sys::hlt. The idle loop is loop { sys::hlt }.

Port I/O and the CPU-control functions require an x86 target.

What does not work

Division and modulo halt. 64-bit / and % on a 32-bit target need the compiler runtime (__divdi3, __moddi3), which freestanding mode does not link. The symbols resolve so unrelated code still compiles, but qd_div and qd_mod call qd_freestanding_halt() at runtime. If you need integer division, either link libgcc or implement it yourself. Shifts and multiplication are fine.

Strings are not meaningfully supported. qd_push_s_ref is a stub — a string literal will compile and do nothing useful. Work in bytes.

There is no error reporting. panic is rejected outright, and every internal fatal path (stack underflow, stack overflow, division, a failed cast<ptr>) halts silently instead of printing. Getting a wrong answer and getting a halt look the same from outside, so lean on the compile-time stack checker.

Call-stack tracking is compiled but inert. qd_push_call/qd_pop_call are no-ops so that codegen emitting them still links.

Overriding the halt hook

qd_freestanding_halt is weak. The default is cli; hlt in a loop on x86 and wfi on ARM/AArch64. Define your own to report the failure before stopping:

// C
void qd_freestanding_halt(void) {
    vga_print("HALT");
    for (;;) {
        __asm__ volatile("cli; hlt");
    }
}

The value stack is statically allocated at QD_FREESTANDING_STACK_CAP elements (default 1024). Rebuild freestanding.c with -DQD_FREESTANDING_STACK_CAP=... if you need a deeper one — there is no growth path and overflow halts.

Linking it together

The recommended shape is three files beside your .qd: an assembly entry stub, a linker script, and a Makefile that compiles the freestanding runtime alongside your object.

boot.S — multiboot header, a stack in .bss, and a jump to _start:

/* Assembly */
.section .multiboot
    .align 8
    /* multiboot header goes here */

.section .bss.stack, "aw", @nobits
    .align 16
stack_bottom:
    .skip 16384
stack_top:

.section .text
.global _kernel_entry
_kernel_entry:
    mov $stack_top, %esp
    call _start
1:  cli
    hlt
    jmp 1b

linker.ld — load at 1 MiB and keep the multiboot header inside the first 8 KiB, or the bootloader will not find it:

/* Linker script */
ENTRY(_kernel_entry)

SECTIONS {
    . = 1M;
    .boot   ALIGN(4K) : { KEEP(*(.multiboot)) }
    .text   ALIGN(4K) : { *(.text) *(.text.*) }
    .rodata ALIGN(4K) : { *(.rodata) *(.rodata.*) }
    .data   ALIGN(4K) : { *(.data) *(.data.*) }
    .bss    ALIGN(4K) : { *(COMMON) *(.bss) *(.bss.*) *(.bss.stack) }
    /DISCARD/ : { *(.comment) *(.note*) *(.eh_frame*) }
}

Put .bss.stack last so the downward-growing CPU stack cannot run into runtime data.

Building — compile the Quadrate object, the freestanding runtime, and the raw half of mem, then link with -nostdlib:

# Makefile
kernel.o: kernel.qd
    quadc --freestanding --target x86_64-unknown-none-elf -O2 kernel.qd -o kernel.o

freestanding.o: lib/rt/src/freestanding.c
    clang --target=x86_64-unknown-none-elf -ffreestanding -fno-builtin -nostdlib \
          -fno-stack-protector -mno-red-zone -O2 -Ilib/rt/include -c $< -o $@

mem.o: stdlib/mem/src/mem.c
    clang --target=x86_64-unknown-none-elf -ffreestanding -fno-builtin -nostdlib \
          -Ilib/rt/include -Istdlib/mem/include -c $< -o $@

kernel.elf: boot.o kernel.o freestanding.o mem.o linker.ld
    ld -nostdlib -T linker.ld -o $@ boot.o kernel.o freestanding.o mem.o

-mno-red-zone matters on x86_64: interrupt handlers will clobber the red zone.

A worked example

examples/kernel/ is a complete bare-metal x86_64 multiboot kernel written in Quadrate. It boots through a 32→64-bit transition, sets up a GDT and IDT, remaps the PIC, and runs a VGA text console with a PIT timer and PS/2 keyboard input — with only boot.S (multiboot header and long-mode transition) and interrupts.S (ISR stubs) outside Quadrate.

cd examples/kernel
make          # kernel.elf
make iso      # GRUB-bootable image (needs xorriso + grub-mkrescue)
make run      # boot it under QEMU

Two details worth copying: the IDT and GDT are built with sys::st64 writes from Quadrate rather than from C, and the assembly side exports address-of helpers (gdt_addr, idt_addr, tick_addr, …) through a normal import "interrupts.o" block, so shared state lives in .bss where both languages can reach it.