Project 8: Bare-metal “Hello World” on QEMU

A freestanding Zig program that runs on bare metal (emulated by QEMU). It will not link libc or any OS libraries. Its only job is to print “Hello, world!” to the serial port.

Quick Reference

Attribute Value
Primary Language Zig
Alternative Languages C, Assembly
Difficulty Level 4: Expert
Time Estimate 1-2 weeks
Knowledge Area Operating Systems / Embedded
Tooling A minimal OS kernel
Prerequisites Project 4. Familiarity with assembly concepts.

What You Will Build

A freestanding Zig program that runs on bare metal (emulated by QEMU). It will not link libc or any OS libraries. Its only job is to print “Hello, world!” to the serial port.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Creating a freestanding build → maps to setting the target OS to .freestanding and disabling libc linking
  • Writing an entry point → maps to exporting a _start function instead of main
  • Interacting with hardware → maps to writing to magical memory addresses (e.g., 0x3F8 for the serial port) using volatile
  • Setting up the QEMU environment → maps to learning QEMU command-line flags to emulate a specific machine

Key Concepts

  • Freestanding vs. Hosted: OSDev Wiki - Bare Bones
  • Memory-Mapped I/O: “Making Embedded Systems” by Elecia White, Ch. 4
  • Volatile Keyword: Zig Docs - volatile

Real-World Outcome

# Build the freestanding binary
$ zig build

# Run it in QEMU
$ qemu-system-x86_64 -serial stdio -kernel zig-out/bin/my-kernel
Hello, bare-metal world!
# QEMU exits

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_ZIG_DEEP_DIVE.md
  • “Operating Systems: Three Easy Pieces” by Arpaci-Dusseau