Part 1-3: Project Setup

Introduction

Before we can write any actual OS code, we need to set up the project structure, build system, and configuration files. This might seem tedious, but having a good structure from the start will save a lot of headaches later.

In this part, we’ll set up:

• Project directory structure
• Build system for multiple bootloaders and platforms
• Linker scripts for different boot targets
• Basic bootloader scaffolding
• A minimal “hello world” that displays text on screen

Our goal is to get something working on all our target platforms: x86-64 (both BIOS/CSM and UEFI) and RISC-V (UEFI).

Project Structure

We need to organize our code to support multiple bootloaders (BIOS and UEFI) and multiple architectures (x86-64 and RISC-V).

Directory Layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

project-root/
├── bootloader/
│   ├── bios-x86_64/          # BIOS/CSM bootloader for x86-64 (C)
│   │   ├── stage1/           # 512-byte boot sector (assembly)
│   │   ├── stage2/           # Main bootloader (C + assembly)
│   │   └── Makefile
│   ├── uefi-x86_64/          # UEFI bootloader for x86-64 (Rust)
│   │   ├── src/
│   │   └── Cargo.toml
│   ├── uefi-riscv64/         # UEFI bootloader for RISC-V (Rust)
│   │   ├── src/
│   │   └── Cargo.toml
│   └── common/               # Shared code (boot protocol definitions)
│       └── boot_protocol.h / boot_protocol.rs
├── kernel/
│   ├── src/
│   │   ├── main.rs
│   │   └── arch/
│   │       ├── x86_64/
│   │       └── riscv64/
│   └── Cargo.toml
└── Makefile                   # Top-level build orchestration

Why This Structure?

Setting Up the BIOS Bootloader (x86-64)

The BIOS bootloader is the most complex because it starts in 16-bit real mode and needs to work within severe constraints.

Stage 1: The Boot Sector

Stage 2: The Main Bootloader

Build System for BIOS Bootloader

Linker Script

Setting Up the UEFI Bootloaders

UEFI bootloaders are much simpler because UEFI provides services for file I/O, memory management, and graphics.

UEFI for x86-64

UEFI for RISC-V

Rust Configuration for UEFI

The Boot Protocol

Building the Project

Hello World: Displaying Text

Now that we have the structure, let’s get something on screen for each platform.

BIOS: Text Mode

UEFI: Graphics Output Protocol

Testing in QEMU

What’s Next?

In the next part, we’ll dive deeper into the boot protocol and bootloader architecture, understanding what information needs to be passed from bootloader to kernel.