Appendix A Toolchain and flags reference

This appendix gathers in one place every tool option the book uses, so that you do not have to search the chapters for them. Chapter 0 explains the environment; this is the reference card.

A.1 Versions

The listings were produced inside the container built from tools/Dockerfile (Debian trixie):

tool version used for
gcc 14.2.0 compiling C, hosted (Part I) and freestanding (Part III)
binutils 2.44 ld, objdump, readelf, objcopy, nm
nasm 2.16.03 the bootloader and the assembly parts of the kernel
gdb 16.3 debugging hosted programs and the emulated machine
QEMU 10.0 qemu-system-i386, the emulated PC
GNU Make 4.4.1 builds
e2fsprogs 1.47 mke2fs, building the ext2 image of chapter 14

A.2 Reference documents

Section, table and figure numbers quoted in the book are those of the following editions:

document edition cited
Intel® 64 and IA-32 Architectures Software Developer’s Manual, Volume 1 and Volume 3A September 2026, revision 093 (order numbers 253665-093, 253668-093)
ATA/ATAPI-6 (ANSI INCITS 361-2002) T13 working draft d1410, revision 3a
The Second Extended File System: Internal Layout, Dave Poirier the nongnu.org edition (2001-2011)
ACPI specification version 6.5, chapter 15 “System Address Map Interfaces”
AMD64 Architecture Programmer’s Manual, Volume 2 (System Programming) and Volume 3 (General-Purpose and System Instructions) July 2026: publication 24593 revision 3.45, publication 24594 revision 3.38
UNIX Programmer’s Manual, First Edition (Thompson and Ritchie) November 1971, section II for the system calls
SYSCALL and SYSRET Instruction Specification (AMD) application note 21086, 1998

Intel renumbers the chapters of Volume 3A from time to time (between the 2016 and 2026 editions, “Paging” moved from chapter 4 to chapter 5 and “Task Management” from chapter 7 to chapter 10). If a number does not match your copy, search for the section title.

A.3 gcc

Hosted programs (Part I):

$ gcc $BOOKFLAGS [-g] file.c -o file
BOOKFLAGS = -m32 -no-pie -fno-pie -fno-asynchronous-unwind-tables -fcf-protection=none -O0
flag effect chapter
-m32 32-bit code and ELF32 output 0
-no-pie -fno-pie fixed load address, no position-independent code 0, 4
-fno-asynchronous-unwind-tables no .eh_frame section 0, 5
-fcf-protection=none no endbr32 markers 0
-O0 no optimization; assembly follows the source line by line 0, 4
-g DWARF debugging information 6
-gdwarf-4 DWARF version 4 (when the text shows DWARF 4 output) 6
-masm=intel Intel syntax in gcc -S output 6
-c compile only, produce an object file 5, 8
-S produce assembly instead of an object file 4

Freestanding kernel code (Part II and III), on top of the flags above:

flag effect chapter
-ffreestanding no assumptions about a standard library or main 8
-nostdlib do not link crt0, libc or libgcc 8
-fno-stack-protector no canary checks that would call into a library we do not have 8
-Wall -Wextra all warnings; the sample code builds without any 9

A.4 ld

$ ld -m elf_i386 [-nmagic] [--no-warn-rwx-segments] -T script.lds objects... -o output
option effect chapter
-m elf_i386 32-bit x86 output 8
-T script.lds use this linker script instead of the default 8
-nmagic do not page-align sections; file offsets follow the script 8
--no-warn-rwx-segments silence the warning about a segment that is readable, writable and executable (our single kernel segment) 8
--verbose print the default linker script 0, 8

A.5 nasm

command effect chapter
nasm -f bin file.asm -o file flat binary, exactly the bytes of the instructions 4, 7
nasm -f elf -F dwarf -g file.asm -o file.o ELF32 object with DWARF debug information 8
nasm -DNAME=value ... define an assembly-time constant (KERNEL_SECTORS) 9

A.6 objdump, readelf, objcopy

command shows chapter
objdump -d file disassembly of executable sections 4
objdump -D file disassembly of all sections 4
objdump -M intel -d file Intel syntax 4
objdump -S file interleave source (needs -g) 4
objdump -s -j .section file raw contents of one section 5
readelf -h file ELF header 5
readelf -S file section header table 5
readelf -l file program header table and section-to-segment mapping 5, 8
readelf -s file symbol tables 5
readelf -r file relocations 8
readelf --debug-dump=info file DWARF debugging information entries 6
objcopy -O binary in.elf out.bin extract the loadable bytes of an ELF file 8

A.7 QEMU

$ qemu-system-i386 -machine q35 -drive format=raw,file=build/disk.img,if=floppy|if=ide [options]
option effect chapter
-machine q35 emulate an Intel Q35 chipset PC 3, 7
-drive format=raw,file=...,if=floppy the image is a floppy disk 7
-drive format=raw,file=...,if=ide the image is a hard disk 9
-gdb tcp::26000 gdb stub on TCP port 26000 7
-S start stopped, wait for the debugger 7
-display none no window (tests, CI) 0
-serial stdio the first serial port goes to the terminal 10
-serial file:log.txt the first serial port goes to a file 10
-monitor stdio the QEMU monitor on the terminal (info registers, sendkey, screendump) 9, 11
-d int log every interrupt and exception 11
-no-reboot halt instead of rebooting on a triple fault 11
-smp 4 four processors 15

A.8 gdb

command effect chapter
target remote localhost:26000 attach to QEMU’s gdb stub 7
set architecture i8086 disassemble as 16-bit real-mode code 7
set architecture i386 back to 32-bit 9
set disassembly-flavor intel Intel syntax 6
symbol-file build/os/os load symbols and debug information of the kernel 8
b *0x7c00 breakpoint at an address 7
hook-stop user-defined command run at every stop (prints cs:eip) 7
layout asm / layout src / layout split / layout reg the text user interface 6, 8
x/8xb addr, x/4i $eip examine memory as bytes / as instructions 6
info registers general-purpose registers and flags 6
monitor info registers QEMU’s view, including CR0, CR3, GDTR, IDTR 9
p $cr0, p/x $cr3 control registers (supported by recent gdb/QEMU) 9, 12
gdb -q -nx -x .gdbinit run gdb with the chapter’s script, ignoring ~/.gdbinit 9

A.9 Make targets of the sample code

Every code/chapterN/os directory understands make, make qemu, make gdb, make test and make clean; see code/README.md and chapter 7.