Cogs and Levers A blog full of technical stuff

Build your own x86 Kernel Part 5

Introduction

In the last post we landed in 32-bit protected mode. Before moving on though, let’s tidy up this project a little bit so we can start managing larger pieces of code cleanly.

So far, everything has been hard-wired: ORG directives, absolute addresses, and flat binaries. That works for a boot sector, but we’re about to deal with paging, higher memory, and higher-level languages - so we need a proper linker script to take over memory layout.

Linker

A new file has been added to manage how the result of stage2.asm is laid out, and we call it stage2.ld.

The linker script gives us precise control over where each section of code and data ends up in memory — something ORG statements alone can’t handle once we start mixing multiple object files, sections, and languages.

Up until now, our binaries were assembled as raw flat images: every byte went exactly where NASM told it. But in larger systems (especially when we introduce C or Rust later), each file gets compiled separately into relocatable object files (.o). The linker then combines them — and the .ld script tells it exactly how to do that.

What does a linker script do?

At a high level, the linker script acts as a map for your binary. It tells the linker:

  • where the program starts (ENTRY(start2))
  • where each section should live in memory (. = 0x8000)
  • how to group sections from different files (.text, .data, .bss, etc.)
  • which global symbols to export for use in assembly or C (e.g. _stack_top, _kernel_end)

This becomes essential when we start paging or using virtual addresses — because physical load addresses and virtual execution addresses will differ.

Example

Here’s a minimal example of what we might use in stage2.ld.

ENTRY(start2)

SECTIONS
{
  . = 0x8000;            /* Stage 2 load address */

  .text : {
    *(.text16*)
    *(.text32*)
    *(.text*)
  }

  .rodata : { *(.rodata*) }
  .data   : { *(.data*)   }
  .bss (NOLOAD) : { *(.bss*) *(COMMON) }

  _stack_top = . + 0x1000;   /* simple 4 KiB stack symbol */
}

A file like this replaces the hard-coded layout logic from our assembly. NASM now just emits relocatable code, and the linker (ld) uses this script to position everything properly inside the final binary.

Updating the Makefile

We now assemble stage2.asm into an object file and link it with the new script to produce an ELF image:

boot/stage2.o: boot/stage2.asm
    $(NASM) -f elf32 -g -F dwarf -Wall -O0 $< -o $@

build/stage2.elf: boot/stage2.o boot/stage2.ld
    ld -T boot/stage2.ld -m elf_i386 -nostdlib -o $@ $<

boot/stage2.bin: build/stage2.elf
    objcopy -O binary $< $@
    truncate -s 8192 $@

This new process might look like extra work, but it pays off the moment we start mixing in C code and paging structures. The linker will take care of symbol addresses and memory offsets — no more hardcoded numbers scattered through our assembly.

Paging and Long Mode

Now that our build is structured and linkable, we can continue where we left off in Stage 2 — by preparing to enter 64-bit long mode.

To do that, we first need to enable paging and set up basic 64-bit page tables.

Modern x86 CPUs can only enter 64-bit mode after paging and PAE (Physical Address Extension) are enabled. That means we’ll build just enough of a paging hierarchy to identity-map the first few megabytes of physical memory — enough to run the kernel.

Understanding Paging and PAE

To execute 64-bit code, the CPU insists on PAE paging being enabled and on using the long-mode paging format (the 4-level tree). Concretely:

  • CR4.PAE = 1 (turn on PAE)
  • EFER.LME = 1 (allow long mode)
  • CR0.PG = 1 (turn on paging)
  • Then a far jump into a 64-bit code segment (CS.L=1) to start executing in 64-bit.

The 4-level tree (long-mode paging)

Long mode uses this hierarchy (all entries are 64-bit):

Level Entries Coverage Entry Size
PML4 512 512 GiB each 8 bytes
PDPT 512 1 GiB each 8 bytes
PD 512 2 MiB each 8 bytes
PT 512 4 KiB each 8 bytes

These tables are used in a hierarchy:

Virtual addr bits:  [47:39]   [38:30]   [29:21]   [20:12]   [11:0]
                    PML4 idx  PDPT idx  PD idx    PT idx    page offset

Tables:               PML4  ->  PDPT  ->  PD  ->  PT  ->  4 KiB page
                                           \-> 2 MiB page (PS=1, no PT)

For a minimal set up, we’ll skip PT by using one 2 MiB page: create PML4[0] -> PDPT[0] -> PD[0] with PS=1 which identity-maps 0x00000000–0x001FFFFF.

That’s enough for Stage 2 and the jump.

Why not pt?

You only need a PT (page table) if you want 4 KiB granularity (e.g., guard pages, mapping tiny regions, marking some pages NX later, etc.). Early on, 2 MiB pages are simpler and faster to set up:

  • Use 2 MiB page (no PT):
    • Fewer entries to touch
    • Great for identity-mapping “just get me to 64-bit”
  • Use 4 KiB pages (needs PT):
    • Fine-grained control (per-page permissions)
    • Slightly more code and memory for the PT

Paging entries

Each paging entry (in PML4, PDPT, PD, and PT) follows the same 64-bit structure and flag semantics you listed. The only difference is which address bits and specific flag bits are valid at that level.

Each paging entry = 64 bits (low 32 bits + high 32 bits)

Each paging entry = 64 bits (low 32 bits + high 32 bits)

Bits Name Meaning
0 P (Present) Must be 1 for valid entries
1 RW (Writable) 1 = writable, 0 = read-only
2 US (User/Supervisor) 0 = kernel-only, 1 = user-accessible
3 PWT (Page Write-Through) Cache control bit (leave 0)
4 PCD (Page Cache Disable) Cache disable bit (leave 0)
5 A (Accessed) CPU sets when accessed
6 D (Dirty) For pages only (set by CPU)
7 PS (Page Size) 0 = points to next table, 1 = large page (2 MiB or 1 GiB)
8 G (Global) Optional: prevents TLB flush on CR3 reload
9–11 Available (ignored by hardware) You can use for OS bookkeeping
12–51 Physical Address Base address of next-level table or physical page
52–58 Available (ignored)
59 PAT (Page Attribute Table) Rarely used; controls memory type
60–62 Ignored / Reserved
63 NX (No Execute) 1 = non-executable (if EFER.NXE = 1)

How that applies per level:

Level Structure What address field points to Special bits
PML4E PML4 entry Physical base of PDPT P, RW, US same
PDPTE PDPT entry Physical base of PD (or 1 GiB page if PS = 1) PS = 1 → 1 GiB page
PDE Page directory entry Physical base of PT (or 2 MiB page if PS = 1) PS = 1 → 2 MiB page
PTE Page table entry Physical base of 4 KiB page PS ignored

Setup

To setup these page entries, we configure the flags that we need at each level.

; zero 4 KiB table at EDI
%macro ZERO_PAGE 1
  mov edi, %1
  xor eax, eax
  mov ecx, 4096/4
  rep stosd
%endmacro

%define PTE_P     (1 << 0)   ; present
%define PTE_RW    (1 << 1)   ; writable
%define PTE_PS    (1 << 7)   ; page size (1 = 2 MiB)
%define PTE_FLAGS (PTE_P | PTE_RW)

setup_paging:
  ZERO_PAGE pml4
  ZERO_PAGE pdpt
  ZERO_PAGE pd

  ; PML4[0] -> PDPT
  mov   eax, pdpt
  or    eax, PTE_FLAGS
  mov   [pml4], eax
  mov   dword [pml4 + 4], 0      ; high dword = 0

  ; PDPT[0] -> PD
  mov   eax, pd
  or    eax, PTE_FLAGS
  mov   [pdpt], eax
  mov   dword [pdpt + 4], 0

  ; PD[0] -> 2 MiB page starting at 0x00000000
  mov   eax, 0x00000000 | PTE_FLAGS | PTE_PS
  mov   [pd], eax
  mov   dword [pd + 4], 0

  ; PD[1] -> 2 MiB page starting at 0x00200000
  mov   eax, 0x00200000 | PTE_FLAGS | PTE_PS
  mov   [pd + 8], eax
  mov   dword [pd + 8 + 4], 0

  ret

We can then wrap up the setting of this structure behind a function call, and enable paging:

    call  setup_paging
    
    mov   eax, pml4
    mov   cr3, eax           ; set root paging structure
    
    mov   eax, cr4
    or    eax, (1 << 5)      ; PAE = Physical Address Extension
    mov   cr4, eax
    
    mov   ecx, 0xC0000080    ; EFER MSR
    rdmsr
    or    eax, (1 << 8)      ; enable long mode (LME)
    wrmsr
    
    mov   eax, cr0
    or    eax, (1 << 31)     ; enable paging
    mov   cr0, eax

At this point, all of our paging setup is complete. We now have the first 2 MiB identity mapped, ready for our kernel to use.

Long Mode

We’re almost ready to head over to long mode now.

We do need to add two more descriptors to our gdt. These are for our 64-bit code, and 64-bit data.

; GDT
gdt:
    dq 0x0000000000000000         ; 0x00: null
    dq 0x00CF9A000000FFFF         ; 0x08: 32-bit code (base=0, limit=4GiB)
    dq 0x00CF92000000FFFF         ; 0x10: 32-bit data (base=0, limit=4GiB)
    dq 0x00209A0000000000         ; 0x18: 64-bit code  (L=1, D=0, G=0 ok)
    dq 0x0000920000000000         ; 0x20: 64-bit data  (L ignored)

gdt_desc:
    dw gdt_end - gdt - 1
    dd gdt
gdt_end:

For the 64-bit code descriptor: Access = 0x9A, Flags = 0x20 (L=1). Granularity (G) and Limit are ignored in long mode, so this minimalist form is fine.

Now can can push to long mode.

lgdt  [gdt_desc]            ; GDT that includes 0x18 (64-bit CS)
jmp   0x18:long_entry       ; load CS with L=1 → CPU switches to 64-bit

This means that we need a new block of 64-bit code to jump to:

BITS 64
SECTION .text64

extern _stack        ; from your linker script

long_entry:
  mov     ax, 0x20         ; 64-bit data selector
  mov     ds, ax
  mov     es, ax
  mov     ss, ax
  mov     fs, ax
  mov     gs, ax

  mov     rsp, _stack      ; top of your stage2 stack from .ld

  lea     rsi, [rel msg_long]
  call    serial_puts64

.hang:
  hlt
  jmp     .hang

%include "boot/serial64.asm"

SECTION .rodata

msg_long db "64-bit Long mode: Enabled", 13, 10, 0

Of course, we’ve had to re-implement the serial library as well to be supported in 64-bit mode.

BITS 64

%define COM1 0x3F8

serial_wait_tx64:
  push rdx
  push rax

  mov  dx, COM1+5
.wait:
  in   al, dx
  test al, 0x20
  jz   .wait
  
  pop  rax
  pop  rdx

  ret

; AL = byte
serial_putc64:
  push rdx
  
  call serial_wait_tx64
  
  mov  dx, COM1
  out  dx, al
  
  pop  rdx
  
  ret

; RSI -> zero-terminated string
serial_puts64:
  push rax

.next:
  lodsb
  test al, al
  jz   .done
  ; translate '\n' -> "\r\n"
  cmp  al, 10
  jne  .send
  push rax
  mov  al, 13
  call serial_putc64
  pop  rax
.send:
  call serial_putc64
  jmp  .next
.done:
  pop  rax

  ret

Building and running

Once we’ve got this built, we can see that we’ve successfully jumped across to long mode.

qemu-system-x86_64 -drive file=os.img,format=raw,if=ide,media=disk -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log
Booting ...
Starting Stage2 ...
Stage2: OK
A20 Line: Enabled
GDT: Loaded
Protected Mode: Enabled
Paging: Enabled
64-bit Long mode: Enabled

Conclusion

We cleaned up the build with a linker script, set up a minimal long-mode paging tree (PML4 → PDPT → PD with 2 MiB pages), extended the GDT with 64-bit descriptors, and executed the CR4/EFER/CR0 sequence to reach 64-bit long mode—while keeping serial output alive the whole way. The result is a small but realistic bootstrap that moves from BIOS real mode to protected mode to long mode using identity-mapped memory and clean section layout.

In the next part we’ll start acting like an OS: map more memory (and likely move to a higher-half layout), add early IDT exception handlers, and bring up a simple 64-bit “kernel entry” that can print, panic cleanly, and prepare for timers/interrupts.

Build your own x86 Kernel Part 4

Introduction

In Part 3 finalised out boot loader, so that it now successfully loads Stage 2 for us. In this post, we’ll focus on setting the system so that we unlock the more advanced features.

Inside of Stage 2 we’ll look at setting up the following:

  • Enable the A20 line
  • Set up a Global Descriptor Table (GDT)
  • Switch to 32-bit Protected Mode

By the end of this article, we’ll at least be in 32-bit protected mode.

A20 Line

Before we can enter 32-bit protected mode, we need to enable the A20 line.

Back in the original Intel 8086, there were only 20 address lines — A0 through A19 — meaning it could address 1 MiB of memory (from 0x00000 to 0xFFFFF). When Intel introduced the 80286, it gained more address lines and could access memory above 1 MiB. However, to remain compatible with older DOS software that relied on address wrap-around (where 0xFFFFF + 1 rolled back to 0x00000), IBM added a hardware gate: A20.

When the A20 line is disabled, physical address bit 20 is forced to 0. So addresses “wrap” every 1 MiB — 0x100000 looks the same as 0x000000.

When A20 is enabled, memory above 1 MiB becomes accessible. Protected-mode code, paging, and modern kernels all assume that A20 is on.

Enabling A20

To enable the A20 Line, we use the Fast A20 Gate (port 0x92).

Most modern systems and emulators expose bit 1 of port 0x92 (the “System Control Port A”) as a direct A20 enable bit.

  • Bit 0 — system reset (don’t touch this)
  • Bit 1 — A20 gate (1 = enabled)

We add the following to do this:

%define A20_GATE  0x92

in    al, A20_GATE      ; read system control port A
or    al, 0x02          ; set bit 1 (A20 enable)
and   al, 0xFE          ; clear bit 0 (reset)
out   A20_GATE, al

Global Descriptor Table (GDT)

When the CPU is in real mode, memory addressing is done through segment:offset pairs. Each segment register (CS, DS, SS, etc.) represents a base address (shifted left by 4), and the offset is added to that. This gives you access to 1 MiB of address space — the legacy 8086 model.

When we switch to protected mode, the segmentation model changes. Instead of using raw segment values, each segment register now holds a selector — an index into a table called the Global Descriptor Table (GDT).

The GDT tells the CPU what each segment means:

  • Its base address
  • size (limit)
  • access rights
  • flags like “code or data”, “read/write”, or “privilege level”

The descriptor layout in 32-bit mode looks like this:

Bits Field Description
0-15 Limit (low) Segment limit (low 16 bits)
16-31 Base (low) Segment base address (low 16 bits)
32-39 Base (mid) Segment base (middle 8 bits)
40-47 Access Byte Type, privilege level, presence
48-51 Limit (high) High 4 bits of segment limit
52-55 Flags Granularity, 32-bit flag, etc.
56-63 Base (high) Segment base (high 8 bits)

In our boot setup, we’ll create a very simple GDT with:

  • A null descriptor (required; selector 0 is invalid by design).
  • A code segment descriptor — flat 4 GiB region, readable, executable.
  • A data segment descriptor — flat 4 GiB region, readable, writable.

This gives us a flat memory model, where all segments start at base 0 and cover the entire address space. That makes protected mode addressing behave almost like real mode linear memory, simplifying everything until paging and virtual memory come later.

Once that GDT is loaded with lgdt, we can safely set the PE (Protection Enable) bit in CR0 and perform a far jump into 32-bit protected mode code.

Defining the GDT

We define our GDT as three quad words. One for null, one for code, and one for data.

align 8
; --- GDT for entering 32-bit PM (null, code, data) ---
gdt32:
    dq 0x0000000000000000         ; null
    dq 0x00CF9A000000FFFF         ; 0x08: 32-bit code, base=0, limit=4GiB
    dq 0x00CF92000000FFFF         ; 0x10: 32-bit data, base=0, limit=4GiB

gdt32_desc:
    dw gdt32_end - gdt32 - 1      ; limit = (size of GDT - 1)
    dd gdt32                      ; base  = address of GDT
gdt32_end:

Breaking down the 32-bit code GDT:

0x00CF9A000000FFFF

If we split this into bytes (little-endian in memory):

[FFFF] [0000] [00][9A] [CF][00]

We can now start to map these to the fields:

Field Value Meaning
Limit (low 16) 0xFFFF segment limit = 0xFFFF
Base (low 16) 0x0000 base = 0x00000000
Base (mid 8) 0x00 base = 0x00000000
Access Byte 0x9A flags that define “code, ring 0, present”
Limit (high 4) + flags 0xCF limit high nibble=0xF, flags=0xC
Base (high 8) 0x00 base = 0x00000000

The “limit” of 0xFFFF and granularity bit (G=1) combine to make the segment effectively 4 GiB in size (0xFFFFF × 4 KiB pages = 4 GiB).

Loading the GDT

Now that we have our GDT defined, we can use lgdt to load it.

cli
lgdt  [gdt32_desc]
mov   eax, cr0
or    eax, 1                   ; CR0.PE=1
mov   cr0, eax

The operand to lgdt wants to see a 16bit limit first, and then a 32-bit linear address (in 32-bit mode) to where the GDT starts.

Protected Mode

With the GDT now loaded, we’re free to push over to protected mode. This is 32-bit protected mode, so we’re jumping into code that needs the [BITS 32] directive.

  ; selectors: 0x08 = code32, 0x10 = data32
  jmp   0x08:pm_entry            ; far jump to load 32-bit CS

[BITS 32]
pm_entry:
  mov   ax, 0x10                 ; 0x10 = data32
  mov   ds, ax
  mov   es, ax
  mov   ss, ax
  mov   fs, ax
  mov   gs, ax
  mov   esp, 0x90000             ; temporary 32-bit stack  

.hang:
  hlt
  jmp   .hang

We make our far jump into 32-bit land. This jump both updates CS and flushes the prefetch queue — it’s the required way to officially enter protected mode.

Immediately we set all of our segment selectors to 0x10 which is data GDT entry.

We’re now in 32-bit protected mode.

Stage 2 (full listing)

Our current code for Stage 2 now looks like this:

; ---------------------------------------------------------
; boot/stage2.asm — loaded by MBR at 0000:8000 (LBA 1..16)
; ---------------------------------------------------------
BITS 16
ORG  0x8000

%define A20_GATE          0x92

start2:
  cli
  xor   ax, ax
  mov   ds, ax        ; ds = 0 so labels assembled with ORG work as absolute
  mov   es, ax
  cld                 ; count upwards
  sti

  call  serial_init

  mov   si, stage2_msg
  call  serial_puts

  in    al, A20_GATE          ; A20 fast
  or    al, 0x02
  and   al, 0xFE
  out   A20_GATE, al

  mov   si, a20_msg
  call  serial_puts

  cli
  lgdt  [gdt32_desc]
  mov   eax, cr0
  or    eax, 1                   ; CR0.PE=1
  mov   cr0, eax

  mov   si, gdt_msg
  call  serial_puts

  ; selectors: 0x08 = code32, 0x10 = data32
  jmp   0x08:pm_entry            ; far jump to load 32-bit CS

stage2_msg db "Stage2: OK", 13, 10, 0
a20_msg    db "A20 Line: Enabled", 13, 10, 0
gdt_msg    db "GDT: Loaded", 13, 10, 0

%include "boot/serial16.asm"

[BITS 32]
pm_entry:
  mov   ax, 0x10                 ; 0x10 = data32
  mov   ds, ax
  mov   es, ax
  mov   ss, ax
  mov   fs, ax
  mov   gs, ax
  mov   esp, 0x90000             ; temporary 32-bit stack  

  mov   esi, pm_msg
  call  serial_puts32

.hang:
  hlt
  jmp   .hang


align 8
; --- GDT for entering 32-bit PM (null, code, data) ---
gdt32:
    dq 0x0000000000000000         ; null
    dq 0x00CF9A000000FFFF         ; 0x08: 32-bit code, base=0, limit=4GiB
    dq 0x00CF92000000FFFF         ; 0x10: 32-bit data, base=0, limit=4GiB

gdt32_desc:
    dw gdt32_end - gdt32 - 1
    dd gdt32
gdt32_end:

pm_msg db "Entered protected mode ...", 13, 10, 0

%include "boot/serial32.asm"

Notes

I’ve had to duplicate the serial assembly file. Originally it was 16 bits only, but now we need 32-bit support.

These routines look alot like their 16-bit counterparts:

; ---------------------------------------------------------
; serial32.asm — COM1 (0x3F8) UART helpers for 32-bit PM
; ---------------------------------------------------------
[BITS 32]

%define COM1 0x3F8
; LSR bits: 0x20 = THR empty, 0x40 = TSR empty

; init: 115200 8N1, FIFO on
serial_init32:
    push eax
    push edx
    ; IER=0 (disable UART interrupts)
    mov  dx, COM1 + 1
    xor  eax, eax
    out  dx, al
    ; DLAB=1
    mov  dx, COM1 + 3
    mov  al, 0x80
    out  dx, al
    ; divisor = 1 (DLL=1, DLM=0)
    mov  dx, COM1 + 0
    mov  al, 0x01
    out  dx, al
    mov  dx, COM1 + 1
    xor  al, al
    out  dx, al
    ; 8N1, DLAB=0
    mov  dx, COM1 + 3
    mov  al, 0x03
    out  dx, al
    ; FIFO enable/clear, 14-byte trigger
    mov  dx, COM1 + 2
    mov  al, 0xC7
    out  dx, al
    ; MCR: DTR|RTS|OUT2
    mov  dx, COM1 + 4
    mov  al, 0x0B
    out  dx, al
    pop  edx
    pop  eax
    ret

; wait until THR empty
serial_wait_tx32:
    push eax
    push edx
    mov  dx, COM1 + 5
.wait:
    in   al, dx
    test al, 0x20
    jz   .wait
    pop  edx
    pop  eax
    ret

; putc: AL = character
serial_putc32:
    push edx
    call serial_wait_tx32
    mov  dx, COM1
    out  dx, al
    pop  edx
    ret

; putc with '\n' -> "\r\n"
serial_putc_nl32:
    cmp  al, 10              ; '\n'
    jne  .send
    push eax
    mov  al, 13              ; '\r'
    call serial_putc32
    pop  eax
.send:
    jmp  serial_putc32

; puts: ESI -> zero-terminated string
serial_puts32:
    push eax
    push esi
.next:
    lodsb                    ; AL = [ESI], ESI++
    test al, al
    jz   .done
    call serial_putc_nl32
    jmp  .next
.done:
    pop  esi
    pop  eax
    ret

Running

Getting this built and running now, we can see that we’re successfully in 32-bit protected mode.

➜ make run  
qemu-system-x86_64 -drive file=os.img,format=raw,if=ide,media=disk -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log
Booting ...
Starting Stage2 ...
Stage2: OK
A20 Line: Enabled
GDT: Loaded
Entered protected mode ...

Conclusion

We’ve now built the minimal foundation of a protected-mode operating system: flat memory model, GDT, and a working serial console. From this point on, we can start using true 32-bit instructions and data structures. In the next post, we’ll extend this with an Interrupt Descriptor Table (IDT), Programmable Interrupt Timer (PIT), and paging, preparing the system for 64-bit long mode.

Build your own x86 Kernel Part 3

Introduction

In Part 2 we wired up a serial port so we could see life signs from our bootloader. Now we’re going to take the next big step — load a second stage from disk. We’ll keep stage2 simple for now - we’ll just prove that control has been transferred.

Our 512-byte boot sector is tiny, so it’ll stay simple: it loads the next few sectors (Stage 2) into memory and jumps there. Stage 2 will then have a lot more room to move to enable our processor.

Finishing Stage 1

Before we can get moving with Stage 2, the first stage of our boot process still has a few things left to do.

The BIOS hands our boot sector the boot drive number in DL (e.g., 0x80 for the first HDD, 0x00 for the floppy).

We need to stash that away for later.

mov   [boot_drive], dl

Disk Address Packet (DAP)

The BIOS via int 0x13 (AH=0x42) provides a read function that will allow us to read Stage 2 off of disk and into memory. The extended read function uses a 16-byte structure pointed to by DS:SI:

Offset Size Field
0x00 1 Size of packet (16 for basic)
0x01 1 Reserved (0)
0x02 2 Number of sectors to read
0x04 2 Buffer offset (destination)
0x06 2 Buffer segment (destination)
0x08 8 Starting LBA (64-bit, little-endian)

We fill this structure like so:

%define STAGE2_SEG      0x0000
%define STAGE2_OFF      0x8000
%define STAGE2_LBA      1
%define STAGE2_SECTORS  16

mov   si, dap           ; DAP for stage2 -> 0000:8000
mov   byte [si], 16
mov   byte [si + 1], 0
mov   word [si + 2], STAGE2_SECTORS
mov   word [si + 4], STAGE2_OFF
mov   word [si + 6], STAGE2_SEG
mov   dword [si + 8], STAGE2_LBA
mov   dword [si + 12], 0

And now we can actually load it off of disk:

mov   dl, [boot_drive]
mov   ah, 0x42
mov   si, dap
int   0x13
jc    disk_error

This call reads count sectors from starting LBA into segment:offset specified in the DAP.

If you recall, we setup our stack at 0x7000. By loading Stage 2 at 0x8000 and having 16 sectors (8 KiB), Stage 2 will occupy 0x8000..0x9FFF, so there won’t be a collision.

After this call we either have Stage 2 successfully loaded at STAGE2_SEG:STAGE2_OFF or the carry flag will be set; in which case, we have an error.

If everything has gone ok, we can use a far jmp to transfer control there in real mode.

jmp   STAGE2_SEG:STAGE2_OFF

Now that we’ve got a bit more space to work with, we can set some more things up (video, disk i/o, a20 lines, gdt, etc.).

Boot loader

Here’s a full rundown of the boot loader so far:

; ---------------------------------------------------------
; boot/boot.asm: Main boot loader
; ---------------------------------------------------------
;
BITS 16
ORG  0x7C00

%define STAGE2_SEG      0x0000
%define STAGE2_OFF      0x8000
%define STAGE2_LBA      1
%define STAGE2_SECTORS  16

main:
  cli
  
  xor   ax, ax
  mov   ss, ax
  mov   bp, 0x7000
  mov   sp, bp            ; temp stack setup (so it's below code)

  mov   ds, ax            ; DS = 0 -> labels are absolute 0x7Cxx
  mov   es, ax            ; ES = 0

  cld                     ; lods/stos auto-increment

  sti

  mov   [boot_drive], dl  ; remember the BIOS drive

  call  serial_init

  mov   si, boot_msg
  call  serial_puts

  mov   si, dap           ; DAP for stage2 -> 0000:8000
  mov   byte [si], 16
  mov   byte [si + 1], 0
  mov   word [si + 2], STAGE2_SECTORS
  mov   word [si + 4], STAGE2_OFF
  mov   word [si + 6], STAGE2_SEG
  mov   dword [si + 8], STAGE2_LBA
  mov   dword [si + 12], 0

  mov   ax, STAGE2_SEG
  mov   es, ax
  mov   dl, [boot_drive]
  mov   ah, 0x42
  mov   si, dap
  int   0x13
  jc    disk_error

  mov   si, stage2_msg
  call  serial_puts
  jmp   STAGE2_SEG:STAGE2_OFF

disk_error:
  mov   si, derr_msg
  call  serial_puts

.hang:
  hlt
  jmp   .hang

%include "boot/serial.asm"

boot_msg    db "Booting ...", 13, 10, 0
stage2_msg  db "Starting Stage2 ...", 13, 10, 0
derr_msg    db "Disk error!", 13, 10, 0

boot_drive  db 0
dap:        db 16, 0
            dw 0, 0, 0
            dd 0, 0

times 510-($-$$) db 0
dw 0AA55h

If we were to run this now without a Stage 2 in place, we should pretty reliably get a Disk error!:

qemu-system-x86_64 -drive file=os.img,format=raw,if=ide,media=disk -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log
Booting ...
Disk error!

Stage 2

Our Stage 2 runs in real mode, but it’s free of the 512-byte limit that our boot loader had. We’ll keep the implementation very simple right now, just to prove that we’ve jumped over to Stage 2 - and fill it out later.

; ---------------------------------------------------------
; boot/stage2.asm — loaded by MBR at 0000:8000 (LBA 1..16)
; ---------------------------------------------------------
BITS 16
ORG  0x8000           ; the offset where we were loaded to by MBR

start2:
  cli
  xor   ax, ax
  mov   ds, ax        ; ds = 0 so labels assembled with ORG work as absolute
  mov   es, ax
  cld                 ; count upwards
  sti

  call  serial_init

  mov   si, stage2_msg
  call  serial_puts

.hang:
  hlt
  jmp   .hang


stage2_msg db "Stage2: OK", 13, 10, 0

%include "boot/serial.asm"

Building

We need to include Stage 2 as a part of the build now in the Makefile. Not only do we need to assemble this, but it needs to make it into our final os image:

boot/boot.bin: boot/boot.asm
    $(NASM) -f bin $< -o $@

boot/stage2.bin: boot/stage2.asm
    $(NASM) -f bin $< -o $@
    truncate -s 8192  $@

os.img: boot/boot.bin boot/stage2.bin
    rm -f $@
    dd if=boot/boot.bin   of=$@ bs=512 count=1 conv=notrunc
    dd if=boot/stage2.bin of=$@ bs=512 seek=1  conv=notrunc
    truncate -s $$((32*512)) $@

After stage2.bin is assembled, you can see we pad it out to the full 8k which is our 16 sectors. This gets appended after the boot loader in the image.

With this very simple Stage 2 in place, we give this a quick build and run we should be able to confirm that we are up and running in Stage 2.

➜  make run    
qemu-system-x86_64 -drive file=os.img,format=raw,if=ide,media=disk -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log
Booting ...
Starting Stage2 ...
Stage2: OK

Conclusion

We’ve made it to Stage 2. We’ve got a great base to work from here. In the next upcoming posts in this series we’ll start to use Stage 2 to setup more of the boot process.

Build your own x86 Kernel Part 2

Introduction

In our previous post we successfully setup our development and build environment, booting a very basic boot loader in QEMU.

In today’s post, we’re going to add some serial integration so that we can see some “signs of life” when our boot loader runs.

Stack Setup

Before moving on any further, it’ll be a good move for us to setup a temporary stack. It’ll live for as long as our boot loader lives. We know our boot code is loaded at 0x7C00. The stack grows downward, so we place it below the boot sector at 0x7000. This keeps it out of the way of our code/data and gives us space to work with. We disable interrupts while changing SS:SP (an interrupt during this window would push onto an uninitialized stack), then re-enable them once the stack and data segments are valid.

main:
cli                   ; disable interrupts

xor   ax, ax
mov   ss, ax
mov   sp, 0x7000      ; stack at 0000:7000 (grows downward)

mov   ds, ax          ; DS = 0 so [label] addresses resolve correctly
mov   es, ax          ; ES = 0

cld                   ; string ops auto-increment

sti                   ; re-enable interrupts

We make sure we can’t be interrupted while doing this, so we clear the interrupt flag with cli. Next, set up the stack so that SS:SP points to 0000:7000. Making ds and es point to the same segment as our code 0000 simplifies things for us. cld makes sure that our lods and stos operations always count ascending. Finally, we re-enable interrupts.

It’ll look something like this:

graph TB A0["0x0000 — 0x03FF
IVT (Interrupt Vector Table)"] A1["0x0400 — ~0x04FF
BDA (BIOS Data Area)"] A2["..."] S["0x7000 (SS:SP start)
Stack top → grows downward"] GAP["0x7000 — 0x7BFF
Gap (free space)"] BOOT["0x7C00 — 0x7DFF
Boot sector (512 bytes)"] A3["... up to conventional memory"] A0 --> A1 --> A2 --> S --> GAP --> BOOT --> A3

Serial

UART (the serial port) is the early debugging channel that we’ll use. It’s the standard for debugging x86 and embedded work, so it’s perfect for what we’re doing.

Registers

We write-to and read-from the UART registers to setup communications over serial. Here’s each of the registers.

COM1 is defined at a base-address of 0x3F8. The following map is an offset from that base.
Offset Description
+0 THR/RBR or DLL (when DLAB=1) — Transmit Holding / Receive Buffer / Divisor Latch Low
+1 IER or DLM (when DLAB=1) — Interrupt Enable / Divisor Latch High
+2 IIR/FCR — Interrupt ID / FIFO Control
+3 LCR — Line Control (word length, parity, stop, DLAB)
+4 MCR — Modem Control (DTR, RTS, OUT1, OUT2, LOOP)
+5 LSR — Line Status (TX empty, RX ready, etc.)
+6 MSR — Modem Status
+7 SCR — Scratch

Init

We can now walk through the init code for the serial line.

%define COM1 0x3F8

serial_init:
  ; 1) Disable UART-generated interrupts (clear IER)
  mov   dx, COM1 + 1
  xor   ax, ax            ; AL=0
  out   dx, al            ; IER = 0 (no UART IRQs)

  ; 2) Enable DLAB so we can set the baud rate divisor
  mov   dx, COM1 + 3
  mov   al, 0x80          ; LCR: DLAB=1
  out   dx, al

  ; 3) Set divisor to 1 -> 115200 baud (on standard PC clock)
  mov   dx, COM1 + 0
  mov   al, 0x01          ; DLL = 1
  out   dx, al
  mov   dx, COM1 + 1
  xor   al, al            ; DLM = 0
  out   dx, al

  ; 4) 8 data bits, no parity, 1 stop bit; clear DLAB to use data regs
  mov   dx, COM1 + 3
  mov   al, 0x03          ; LCR: 8N1 (DLAB=0)
  out   dx, al

  ; 5) Enable FIFO, clear RX/TX FIFOs, set 14-byte RX threshold
  mov   dx, COM1 + 2
  mov   al, 0xC7          ; FCR: 1100_0111b
  out   dx, al

  ; 6) Modem Control: assert DTR, RTS, and OUT2
  mov   dx, COM1 + 4
  mov   al, 0x0B          ; MCR: DTR|RTS|OUT2
  out   dx, al

  ret

Each of these steps is needed in the init phase:

  • IER=0 (no UART IRQs): We’re going to use polling (check LSR bits) in early boot, so we explicitly disable UART interrupts.
  • DLAB=1, set divisor: Standard PC UART clock (1.8432 MHz / 16 = 115200). A divisor of 1 yields 115200 baud. Later you can choose 2 (57600), 12 (9600), etc.
  • LCR=0x03 (8N1): The classic “8 data bits, No parity, 1 stop.” Clearing DLAB returns access to THR/RBR/IER instead of the divisor latches.
  • FCR=0xC7: Enables the FIFO, clears both FIFOs, and sets the RX trigger level to 14 bytes. (On 8250/16450 parts without FIFOs this is ignored—harmless.)
  • MCR=0x0B: Asserts DTR and RTS so the other side knows we’re ready; sets OUT2, which on PCs typically gates the UART interrupt line (even if we aren’t using IRQs yet, OUT2 is commonly left on).

Waiting

Because working with UART is asynchronous, we need to wait for the transmitter holding register is ready. So this waits for the THR empty (bit 5).

serial_wait_tx:
  push  ax
  push  dx

  mov   dx, COM1 + 5
.wait:
  in    al, dx
  test  al, 0x20
  jz    .wait
  
  pop   dx
  pop   ax
  ret

This is important when trying to write data out.

We must wait until we’re ready.

putc and puts

We can now use serial_wait_tx before going to send a character.

The character that we put into al gets sent directly to our COM1 which is at 0x3F8.

serial_putc:
  push  dx

  call  serial_wait_tx

  mov   dx, COM1
  out   dx, al

  pop   dx
  ret

Finally, we can use putc in a loop to implement a puts which iterates though the string at si, sending each of the chars to serial_putc.

serial_puts:
  push  ax
  push  si

.next:
  lodsb
  test  al, al
  jz    .done

  call  serial_putc
  jmp   .next

.done:
  pop   si
  pop   ax

  ret

Signs of life

Now that we have a way to integrate with the serial line, we can use it to prove signs of life in our bootloader.

After our stack is setup, we can start using these functions.

  call  serial_init         ; initialize serial

  mov   si, msg_alive       ; si = our string to print
  call  serial_puts         ; print the string

  hlt                       ; halt

.halt:
  jmp   .halt

%include "boot/serial.asm"  ; serial functions

msg_alive db "Serial communications are alive!", 0

times 510-($-$$) db 0
dw 0AA55h

To clean up the boot code, I tucked all of the serial communication code away into an asm file of its own. It’s still assembled as part of the boot.asm as it’s just text included.

Setting this up for a run, you should see a message in your console.

➜  make run
qemu-system-x86_64 -drive file=os.img,format=raw -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log
Serial communications are alive!

We are alive!

Conclusion

We have put ourselves in a very strong position with these recent additions. This is an invaluable debugging and diagnostic tool being able to write breadcrumbs into the console to check where execution has made it to.

We’ll continue to build on this when we return for Stage2.

Build your own x86 Kernel Part 1

Introduction

One of the best ways to learn how computers work is to get as close to the hardware as possible. Writing assembly language with no other tools or libraries really helps you to understand exactly what makes them tick. I’m building this article series to walk through the full setup of an x86 system to go from power on to a minimal running operating system.

I’ll gradually build this from the ground up, introducing concepts as we go through these articles.

Today, we’ll get all the tooling and build environment setup so we can develop comfortably.

Tools

Before we begin, we need some tools installed.

  • QEMU for virtualising the system that will run our operating system
  • NASM to be our assembler
  • Make to manage our build chain

Get these installed on your respective system, and we can get started getting the project directory setup.

Project Setup

First up, let’s create our project directory and get our Makefile and bootloader started.

mkdir byo_os
mkdir byo_os/boot

cd byo_os

Boot loader

A boot loader is the very first piece of software that runs when a computer starts. Its job is to prepare the CPU and memory so that a full operating system can take over. When the machine powers on, the BIOS (or UEFI) firmware looks for a bootable program and transfers control to it.

In this tutorial we’re building a BIOS-style boot loader. When a machine boots in legacy BIOS mode, the firmware reads the first 512 bytes of the boot device — called the boot sector — into memory at address 0x7C00 and jumps there. Those 512 bytes must end with the magic signature 0xAA55, which tells the BIOS that this sector is bootable. From that point, our code is executing directly on the CPU in 16-bit real mode, with no operating system or filesystem support at all.

Modern systems use UEFI, which is the successor to BIOS. UEFI firmware looks for a structured executable (a PE/COFF file) stored on a FAT partition and provides a much richer environment — including APIs for disk I/O, graphics, and memory services. It’s powerful, but it’s also more complex and hides many of the low-level details we want to understand.

Starting with BIOS keeps things simple: one sector, one jump, and full control. Once we’ve built a working real-mode boot loader and kernel, it’ll be easy to explore a UEFI variant later because the CPU initialization concepts remain the same — only the firmware interface changes.

Here is our first boot loader.

; ./boot/boot.asm

ORG 0x7C00                  ; our code starts at 0x7C00
BITS 16                     ; we're in 16-bit real mode

main:
  cli                       ; no interrupts
  hlt                       ; stop the processor

.halt:
  jmp   .halt

times 510-($-$$) db 0       ; pad out to 510 bytes
dw 0AA55h                   ; 2 byte signature

Our boot loader must be 512 bytes. We ensure that it is with times 510-($-$$) db 0. This directive pads our boot loader out to 510 bytes, leaving space for the final 2 signature bytes dw 0AA55h which all boot loaders must finish with.

Building

With this code written, we need to be able to build and run it. Using a Makefile is an easy way to wrap up all of these actions so we don’t need to remember all of the build steps.

CC64 = x86_64-elf-gcc
LD64 = x86_64-elf-ld
OBJCOPY = x86_64-elf-objcopy
NASM = nasm

OBJDIR = build

all: os.img

$(OBJDIR):
	mkdir -p $(OBJDIR)

boot/boot.bin: boot/boot.asm
	$(NASM) -f bin $< -o $@

os.img: boot/boot.bin 
	rm -f $@
	dd if=boot/boot.bin of=$@ bs=512 count=1 conv=notrunc
	truncate -s $$((32*512)) $@

run: os.img
	qemu-system-x86_64 -drive file=os.img,format=raw -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log

clean:
	rm -rf build os.img boot/*.bin *.log

This will build a boot/boot.bin for us, and it will also pack it into an os.img which we will use to run our os.

The key lines in making the os image are the dd and truncate. They get our 512 byte boot sector first in the image, and then the truncate extends the image to 32 sectors (16 KB total) by padding it with zeros. The extra space simulates a small disk, leaving room for later stages like a kernel or filesystem. The first 512 bytes remain our boot sector; the rest is just blank space the BIOS ignores for now.

When we issue make run, this turns into this:

qemu-system-x86_64 -drive file=os.img,format=raw \
                   -serial stdio \
                   -debugcon file:debug.log \
                   -global isa-debugcon.iobase=0xe9 \
                   -display none \
                   -no-reboot \
                   -no-shutdown \
                   -d guest_errors,cpu_reset \
                   -D qemu.log
  • -drive file=os.img,format=raw Attach a raw disk image as the primary drive. When QEMU boots in BIOS mode, it loads the first sector (the MBR) if it ends with the signature 0xAA55.
  • -serial stdio redirect the guest’s COM1 serial port (I/O 0x3F8) to this terminal’s stdin/stdout, so any serial output from the guest appears in your console.
  • -debugcon file:debug.log will dump the debug console into a file called debug.log
  • -global isa-debugcon.iobase=0xe9 Map QEMU’s simple debug console to I/O port 0xE9. Any out 0xE9, al from your code is appended to debug.log
  • -display none Disables the graphical display window. No VGA text output will be visible unless you use -nographic, serial, or the 0xE9 debug console
  • -no-reboot on a guest reboot request, do not reboot; QEMU exits instead (handy for catching triple-fault loops).
  • -no-shutdown on a guest power-off, don’t quit QEMU; keep it running so logs/console remain available.
  • -d guest_errors,cpu_reset Enables QEMU’s internal debug logging for guest faults and CPU resets (for example, triple faults). The messages are written to the file specified by -D
  • -D qemu.log Write QEMU’s debug logs (from -d) to qemu.log instead of stderr.

We will plan to print with BIOS INT 0x10 later on, so this instruction will evolve as we go.

Running

Let’s give it a go.

By running make you should see output like this:

➜  make
nasm -f bin boot/boot.asm -o boot/boot.bin
rm -f os.img
dd if=boot/boot.bin of=os.img bs=512 count=1 conv=notrunc
1+0 records in
1+0 records out
512 bytes copied, 9.4217e-05 s, 5.4 MB/s
truncate -s $((32*512)) os.img

You can then run this make run:

➜  make run
qemu-system-x86_64 -drive file=os.img,format=raw -serial stdio -debugcon file:debug.log -global isa-debugcon.iobase=0xe9 -display none -no-reboot -no-shutdown -d guest_errors,cpu_reset -D qemu.log

And there you have it. Our bootloader ran very briefly, and now our machine is halted.

Conclusion

We’ve managed to setup our build environment and get a very simple boot loader being executed by QEMU. In further tutorials we’ll look at integrating the serial COM1 ports so that we can get some signs of life reported out to the console.