Bug log
Format: number · date · title, then symptom → cause → fix → test.
#1 · 2026-10-24 · Passing test reported as failure
- Symptom:
make testprints "All tests passed.", but cargo reportsexit status: 33. - Cause:
run-qemu.shdetected test binaries by the path*/deps/*. Current cargo nightly (1.101) places them undertarget/<triple>/debug/build/<pkg>/<hash>/out/instead, so the runner used run mode and passed the raw exit status 33 through. - Fix: detect test mode by the hash suffix in the file name (
-[0-9a-f]{16}$), which works with both layouts. - Test:
make test→ 3× PASS, exit status 0. Counter-check with a deliberately wrong assert → FAIL, exit status 35.
#2 · 2026-10-24 · Timer interrupt never arrives (test hangs in sleep_ms)
- Symptom:
sleep_msnever returns, test timeout.-d intshows not a single vector 0x20 although RFLAGS.IF = 1. - Diagnosis: QEMU monitor
info pic→pic0: irr=01 imr=fe irq_base=20, so the PIC correctly has the IRQ pending.info lapic→LVT0 0x00018700 … masked ExtINT: Limine masks LINT0 of the local APIC, which is exactly where PIC interrupts enter. - Fix:
lapic::disable()clears bit 11 (global enable) in MSRIA32_APIC_BASE, so PIC interrupts go directly to the CPU's INTR pin. - Test:
irq::tests::local_apic_disabled_for_pic_mode,timer_ticks_advance,sleep_waits_roughly. Verified with BIOS and UEFI. - Update (M12): superseded – the kernel now uses the local APIC + I/O APIC and masks LINT0 on purpose; the 8259 is fully masked.
- Update (C6): the fix depends on the QEMU version – QEMU 8.2 drops PIC interrupts at the masked LINT0 even with the APIC disabled (bug #25).
- Remember: when interrupts do not arrive, look at
info pic/info lapicfirst:python3 -I scripts/qemu-monitor.py <elf> [s] -- "info pic" "info lapic".
#3 · 2026-10-24 · hexdump 0 shows IDENTIFY data instead of the boot sector
- Symptom: in the test run, reading sector 0 through the global disk returned the drive's IDENTIFY data ("QM0000 1" serial number).
- Cause: AHCI unit tests called
ahci::probe()again. Re-initializing port 0 pointed its command-list/FIS registers at the test's new frames; the globalAhciDiskkept filling its old (now ignored) command list, so the HBA executed stale commands and the data landed in another bounce buffer. - Fix:
probe()refuses to run twice (PROBEDflag); tests use the globaldrivers::DISK. - Test:
ahci::tests::probing_twice_is_refused,shell::tests::hexdump_shows_boot_signature. - Remember: hardware state is global – a device must have exactly one driver instance.
#4 · 2026-10-24 · Ctrl+C stops working in /bin/sh after spawntest
- Symptom: E2E step
fault spin+ Ctrl+C hung under/bin/sh– the spinner was never killed. - Cause: children of the foreground process inherited the foreground at spawn.
spawnteststarts an orphan (hello) that nobody waits for; it took the foreground, and when it ended the foreground fell back to its dead parent → 0. From then on nobody owned the console, sosh's children were not foreground either and Ctrl+C arrived as a plain byte. - Fix: the console is lent only while a foreground process waits for a child (
process::wait_child) and returned when the wait ends – like a real shell'stcsetpgrp.spawnnever changes the foreground. - Test: E2E
spawntestfollowed byfault spin<pause>^C,fault sleep<pause>^C,upper<pause>^C(all under/bin/sh). - Remember: "who owns the console" must follow who is waiting, not who was started.
#5 · 2026-10-24 · smp::run_on hangs once more threads exist
- Symptom: after the network thread was added, the unit test
jobs_run_on_their_cputimed out. - Cause:
run_onwaited for the job withyield_now()in a loop. If the waiting thread happened to run on the target CPU itself, it was always ready there, so that CPU's idle thread – the one that executes jobs – was never scheduled. On an otherwise idle system the thread rarely ended up there; more scheduling activity made it likely. - Fix: wait by blocking (
time::sleep_ms(1)), which lets the target CPU's idle thread run. - Test:
smp::tests::jobs_run_on_their_cpu(now stable with the net thread running). - Remember: a busy-yield loop is not waiting – a ready thread starves the idle thread of its CPU.
#6 · 2026-10-25 · run_on(0, …) hangs sometimes (about 1 in 15 test runs)
- Symptom:
jobs_run_on_their_cputimed out now and then; all CPUs were idle inhlt. - Cause: only the APs' idle loop ran jobs. Since M26 the calling thread may run on an AP, and a job for CPU 0 then waited
forever in the mailbox: the boot CPU's idle thread (
task::idle_loop) never looked into it. Found with a temporary scheduler dump after 25 s plusinfo registersof all CPUs through the QEMU monitor. - Fix: one
smp::idle_loop(cpu)for every CPU; running inline on the own CPU happens with interrupts off. - Test:
smp::tests::jobs_for_every_cpu_from_every_cpu(4 threads send jobs to all CPUs; hangs reliably with the old code). - Remember: with SMP every per-CPU duty must exist on every CPU, including the boot CPU.
#7 · 2026-10-25 · With one CPU, every disk command took 10 ms
- Symptom: after switching AHCI to MSI,
KERNEL_SMP=1 make testtimed out;time hellotook 0.38 s instead of 0.1 s. - Cause: the reading thread blocked, the CPU went to its idle thread and
hlt. The completion interrupt made the thread ready, but the CPU returned into the idle thread and only switched at the next timer tick. With more CPUsmake_readysends a wake-up IPI to another idle CPU, which hid the problem; nothing kicks the CPU that handles the interrupt itself. - Fix:
task::preempt_idle()at the end of interrupt handlers that wake threads (AHCI, keyboard, COM1): an idling CPU switches to the woken thread at once. - Test: the integration test with
KERNEL_SMP=1(timing oftime helloand the whole run under 30 s). - Remember: run the suite with one CPU after scheduler or interrupt changes – some paths only exist there.
#8 · 2026-10-25 · MSI test flaky: "only 12 interrupts for 16 commands"
- Symptom:
ahci::tests::commands_complete_by_msi_interruptfailed in about 1 of 10 runs withKERNEL_SMP=2. - Cause: the test's assumption was wrong, not the driver. QEMU often completes a command before the waiter blocks
(
wait_forchecks PxCI first), so the thread goes on without needing the interrupt. The MSI for it is still sent to the boot CPU; when that CPU runs with interrupts off for a moment, the next command's MSI arrives while the first one is still pending in the local APIC's IRR – both set the same bit and become one interrupt. - Fix: the test only requires that completion interrupts arrive at all (waiting up to 100 ms for the first).
- Test: the test itself (repeated runs with 2 CPUs).
- Remember: interrupts with the same vector coalesce while pending – never count interrupts to count events; the handler must look at the device's status registers (ours does).
#9 · 2026-10-25 · run_on test hung once with 2 CPUs
- Symptom:
smp::tests::jobs_for_every_cpu_from_every_cpuhung once inKERNEL_SMP=2 make test(not again in 160 hunted runs). - Cause (by analysis): a priority inversion. The idle thread ran jobs with interrupts enabled, so it could be
preempted while the job held the result lock (
*slot.lock() = ...). An idle thread only runs when nothing else is ready – but the thread waiting for the result spun on that very lock, stayed ready and occupied the CPU forever. The waiter could likewise be preempted holding the lock while the job spun on it. - Fix: jobs run with interrupts disabled; the waiter takes the result lock with interrupts disabled too. A spin lock that an idle thread shares with normal threads must never be held across a preemption point.
- Test:
jobs_for_every_cpu_from_every_cpuwithKERNEL_SMP=2and4(rare – the race needs a timer tick inside a few instructions). - Remember: idle threads have the lowest priority by construction; anything they hold can starve.
#10 · 2026-10-25 · stack_overflow test: #GP with error code 0x102 after -cpu max
- Symptom: after switching QEMU to
-cpu max,tests/stack_overflow.rsdied with a general protection fault (code 0x102) instead of the expected double fault. - Cause: error code 0x102 = "IDT entry 0x20": the timer interrupt. The test loads its own IDT with only exception handlers, but interrupts were still enabled; the recursion used to finish before the next tick, and with the slower emulated CPU model a tick arrived first.
- Fix: test kernels with their own IDT disable interrupts before loading it (
stack_overflow.rs,page_fault.rs). - Test: both tests, with
-cpu max. - Remember: a #GP with bit 1 of the error code set points at an IDT vector (index = code >> 3) – usually an interrupt without a handler.
#11 · 2026-10-26 · A syscall with a huge length freezes the system
- Symptom: found by
syscheck(M41):write(1, 0, 1 << 47)never returned, the whole machine stopped responding. - Cause: before checking a user buffer,
Process::populatewalked every page of[addr, addr + len)to map demand-paged heap/stack pages – 2^35 iterations here, under the process table lock with interrupts off. - Fix: the walk stops at the first page that is neither mapped for user mode nor demand-paged (the access check fails there anyway). A request now costs at most the size of the mapped area it touches.
- Test:
syscheckcalls every pointer-taking syscall with lengths up tou64::MAX(integration testuserspace, E2E). - Remember: every loop over a user-supplied range must be bounded by something the kernel owns, not by the user's length.
#12 · 2026-10-26 · Kernel panic from ring 3: empty buffer with a null pointer
- Symptom:
KERNEL PANIC: unsafe precondition(s) violated: slice::from_raw_parts requires the pointer to be aligned and non-nullincopy_from_user, triggered by the random phase ofsyscheck. - Cause: zero-length ranges are always "accessible" (see pitfalls: empty slices have dangling pointers), but
copy_from_user/copy_to_userstill built a slice / calledcopy_nonoverlappingwith that pointer. With a null pointer that is undefined behaviour, which the debug build checks – any program could panic the kernel. - Fix: both return immediately for empty buffers, without touching the pointer.
- Test:
syscheck:write/readwith length 0 and pointers 0, 1,u64::MAXmust return 0. - Remember: an "accessible" empty range is no licence to dereference its pointer.
#13 · 2026-10-26 · readdir with a bad buffer skipped a directory entry
- Symptom:
syschecksawreaddir(fd, bad pointer)return 0 (end of directory) after a few calls – the failed calls had used up the entries. - Cause:
sys_readdiradvanced the directory position before copying the entry out; the copy then failed with EFAULT. - Fix: the buffer is checked first; the position only moves when the entry can be delivered.
- Test:
syscheck:readdirinto null → EFAULT, then the first realreaddirreturns the same entry as on a fresh handle. - Remember: check, then change state – a syscall that fails should leave nothing behind.
#14 · 2026-10-26 · Kernel panic: user copy raced against brk in another thread
- Symptom:
syscheck racewithKERNEL_SMP=1:KERNEL PANIC ... EXCEPTION: PAGE FAULT at address 0x44b000within a second – a kernel-mode page fault on a user heap address. - Cause:
copy_from_user/copy_to_userchecked the buffer (under the process table lock) and copied it after releasing the lock. A timer interrupt between the two let another thread of the process shrink the heap; the copy then touched an unmapped page in ring 0, which is fatal. - Fix: check and copy happen together under the process table lock (
locked_user_copy), in pieces of at most 64 KiB to keep the time with interrupts off short.brkchanges the page tables under the same lock. - Test:
syscheck race 1000in the integration test (fails within a second on the old code with 1 CPU). - Remember: a check of user memory is only valid while nothing can change the mapping – hold the lock until the copy is done.
#15 · 2026-10-26 · TLB shootdown waited for idle CPUs (seconds, or forever)
- Symptom:
syscheck racewith 4 CPUs: only 4 heap shrinks in 5 s (~1 s perbrk). The new unit test with a spinning thread on every CPU never finished. - Cause:
paging::shoot_downsent the CR3 reload as ansmp::run_onjob to every CPU. Jobs run in a CPU's idle thread, which only gets the CPU when no other thread is ready – a busy CPU answered late or never. - Fix: own IPI vector
smp::TLB_VECTOR(0xF1): the handler reloads CR3 if that CPU runs the address space and counts down a pending counter the sender spins on (with interrupts on, so two shootdowns cannot deadlock). - Test:
smp::tests::tlb_shootdown_is_fast_while_all_cpus_are_busy(20 shootdowns < 50 ms with all CPUs busy; the old code hangs until the 30 s timeout). - Remember: work that must happen now on another CPU belongs in an interrupt handler, not in a job queue.
#16 · 2026-10-26 · One write could make the kernel heap grow by the whole buffer
- Symptom: found while sorting the open items (M42) and confirmed with
syscheck: a 16 MiBwriteinto a pipe without a reader grew the kernel heap by 16 388 KiB before failing with EPIPE. The kernel heap never shrinks, and a failed kernel allocation halts the system – two programs writing their 64 MiB heaps at once could take the machine down. - Cause:
sys_write(andsys_sendto) copied the whole user buffer into a kernelVecbefore doing anything. - Fix:
sys_writecopies and writes in pieces of at most 64 KiB (pieces end on a UTF-8 character boundary, the console prints each piece as text);sendtorefuses datagrams larger thanMAX_UDP_PAYLOADbefore copying (EMSGSIZE). Programs still see one complete write –ulibdoes not expect short writes. - Test:
syscheck: 16 MiB into a pipe without a reader → EPIPE with < 1 MiB heap growth;sendtoof 1 GiB → EMSGSIZE. - Remember: the size of a kernel allocation must never be chosen by a user program.
#17 · 2026-10-26 · Shootdown regression test too strict for CI runners
- Symptom: the first CI run (M47) failed on Ubuntu and Fedora alike:
tlb_shootdown_is_fast_while_all_cpus_are_busy– "20 shootdowns took 72610 us" (Fedora: 74845 us) against a limit of 50 000 us. Locally the test passed. - Cause: the limit was chosen from local runs. GitHub's shared runners emulate 4 CPUs with TCG on fewer real cores, so every IPI round trip takes longer. Not a kernel bug.
- Fix: limit raised to 1 s. The test still tells the two implementations apart: the old
run_onshootdown never finished with all CPUs busy (30 s timeout). - Test: the test itself, green in CI on Ubuntu and Fedora.
- Remember: a timing assertion must separate good from broken behaviour, not fast machine from slow machine –
pick the limit from the broken case, not from the local measurement (see
docs/HACKING.md, "Add a test").
#18 · 2026-10-26 · sleep_ms could end up to one tick early
- Symptom: one local E2E run:
time helloprintedreal 0.095377 sfor a program that sleeps 100 ms (and itself reported "Slept for 100 ms", measured in ticks). - Cause: the deadline was "now + ⌈ms / 10⌉ ticks". The tick that is already running counts fully, although part
of it is over – a sleep starting just before a tick ended almost a whole tick early;
sleep_ms(10)could return after a few microseconds. - Fix: one tick more (
sleep_ms_or_abort): a sleep now lasts at leastmsand at mostms+ 10 ms. - Test:
irq::tests::sleep_never_ends_early– 20 sleeps of 10 ms started at different points inside a tick, measured with the TSC clock; fails on the old code, passes on the new. - Remember: a tick counter tells which tick it is, not how far into it – deadlines must round up.
#19 · 2026-10-26 · A new process could miss its own table entry (SMP race)
- Symptom: CI on Fedora, E2E step
ls /bin | grep test | sort -r:sortkilled by a "page fault at 0x7fffffeefff8 (page not present, write, user mode)" incore::panicking::panic_nounwind_fmt– 8 bytes below the 1 MiB stack area. Not reproducible by running the pipeline 200 times locally. - Cause: two bugs in a chain. (1)
process::spawn_withmade the new thread runnable (task::spawn_user) before inserting the process into the table. Another CPU – woken by an IPI because a thread became ready – could start the program at once; its firstbrkfound no table entry and failed with EBADF, so the program's allocator could never get memory. (2) The allocation failure made Rust panic, andulib's panic handler formatted its message witheprintln!, which allocates – it panicked again, recursively, until the stack was used up. - Fix: (1)
spawn_withholds the process table lock while it creates the thread and inserts the entry – the orderspawn_threadalready used. (2) The panic handler formats into a 256-byte buffer on the stack and stops at a second panic ("panic while panicking"). - Test:
process::tests::first_syscall_of_a_new_process_finds_its_table_entry(240 processes whose first syscall isbrk; failed in 4 of 6 runs on the old code with "first brk returned -9", 0 of 7 on the new, also with 1 and 2 CPUs);fault oomfills the heap to the last byte and must still print "panic: memory allocation of 1048576 bytes failed" (old handler: the same page fault below the stack as in CI). - Remember: "interrupts off" protects against this CPU only – on SMP, anything a new thread may look at must exist before the thread becomes runnable.
#20 · 2026-10-27 · DESIGN.md said there was no block cache
- Symptom: an outside review of the docs found two contradicting statements: "Disk caching and interrupts" says the
root file system runs on a 1024-sector
BlockCache, "File system" said "No block cache: data clusters are read/written directly". - Cause: documentation only. The "File system" text was written at M15; M32 added
BlockCacheand updated its own section but not the older one. The code (fs::RootDisk = BlockCache<SystemDisk>) was right. - Fix: the "File system" section now describes the caches as they are and states the limit of the power-off guarantee (after a command, not during one).
- Test: none possible for prose;
scripts/check-doc-refs.pyonly checks that named symbols exist. - Remember: a milestone that changes a layer must search the docs for every statement about that layer, not only edit its own section.
#21 · 2026-10-27 · The heap could grow into the stack
- Symptom: none observed; found while placing the thread stack slots of M52 below the main stack.
- Cause:
USER_IMAGE_ENDonly kept the ELF segments 64 KiB below the stack area. The heap starts right after the image and may grow byHEAP_MAX(64 MiB) – a program whose image ended nearUSER_IMAGE_ENDcouldbrkits heap into the stack range, and both would demand-page the same addresses. Only the program itself was affected (memory isolation between processes held), but it broke the stack guard. - Fix:
USER_IMAGE_END = THREAD_STACKS_BOTTOM - STACK_GUARD - HEAP_MAX: the largest heap behind the highest allowed image ends below a guard gap. - Test:
process::tests::thread_stack_slots_have_guardsasserts the layout (fails with the old constant). - Remember: a limit on one region (the image) is only safe together with the limits of the regions that grow out of it (the heap).
#22 · 2026-10-27 · The TCP loss test needed almost the whole time limit of its test kernel
- Symptom:
make stress, pass 1 with 4 CPUs:netfaultkilled by the 30 s timeout ofrun-qemu.shwhileevery_fifth_packet_lost_the_data_still_arrivesran. With 1 and 2 CPUs, and in 6 single runs, it passed. - Cause: the test, not the kernel. 3 echoes of 20 KB with every 5th packet lost cost 36–49 retransmission timeouts of at least 200 ms each (go-back-N sends everything after a loss again, and every 5th of that is lost too) – 10–15 s of the 30 s limit. On a busy machine that was not enough. Runs with a 120 s limit never hung (6 of 6 passed in 18–22 s).
- Fix: 8 KB per echo and every 10th packet lost; the loss still hits the SYN, the SYN-ACK and the first ACK once each. The test prints its duration.
- Test: 6 runs with all 4 host cores busy: 2.7–6.1 s for the test, all passed; then the full
make stress. - Remember: a test that waits for timeouts must be sized against the time limit of the machine it runs on, with room to spare – the CI uses 120 s, a developer machine 30 s.
#23 · 2026-10-27 · The DNS timeout E2E step expected an exact duration
- Symptom:
make e2e-uefion the 1.0.0 commit:time host silent.yak.test …printedreal 5.152603 s, the step expectedreal 4.. - Cause: the test (M58). 3 tries of 1.5 s are at least 4.5 s; how much longer depends on the machine.
- Fix: the step now only forbids giving up too early (
real 0.…real 3.); the step's own timeout catches a hang. - Test:
make e2eandmake e2e-uefigreen. - Remember: the same lesson as #22 – assert a lower bound for timeouts, never an exact time.
#24 · 2026-10-29 · The hello sleep check in the userspace test allowed only one tick of delay
- Symptom:
make checkon a busy host:tests/userspace.rsfailed at its first assertion –helloprinted "Slept for 120 ms", the test accepted only 100 or 110 ms. Five runs right after it printed 110 ms and passed. - Cause: the test, not the kernel. A sleep of 100 ms lasts at least 100 ms (bug #18); when the woken thread runs again depends on the timer ticks arriving on time, and under TCG on a loaded host a tick can come late.
- Fix: the test reads the number and checks 100 ≤ ms ≤ 300 – the lower bound stays exact, the upper one only catches a sleep
that is far too long.
irq::tests::sleep_never_ends_earlystill checks bug #18 precisely with the TSC clock. - Test:
tests/userspace.rsgreen in five runs in a row. - Remember: the third time after #22 and #23 – an emulated machine gives lower bounds for time, never upper ones.
#25 · 2026-10-29 · Course chapter 6: no timer interrupt under QEMU 8.2
- Symptom: CI job
courseon PR #9:time::tests::sleep_never_ends_earlyhung until the 120 s limit. Locally (Fedora, QEMU 10.2) all 29 tests passed. Reproduced with the same kernel under Ubuntu 24.04's QEMU 8.2.2 in a container: the normal kernel stops after "Timer: IRQ 0 on vector 32". - Diagnosis: QEMU monitor under 8.2:
pic0: irr=01 imr=fe isr=00 irq_base=20– the PIC holds the tick, moved and unmasked – andLVT0 0x00018700 … masked ExtINT, RFLAGS.IF = 1, the CPU inhlt. The chapter switched the local APIC off throughIA32_APIC_BASEas the reference kernel did in M6 (bug #2), but QEMU 8.2 still sends the PIC's signal through LINT0, and Limine masked LINT0. QEMU 10.2 delivers it; where its code differs I did not find. - Fix: unmasking LINT0 ("virtual wire mode") needs the APIC registers – memory-mapped at
0xFEE0_0000, which Limine does not map (a read through the HHDM page-faults), or x2APIC MSRs, which QEMU 8.2's TCG does not offer. So from chapter 6 on the course starts QEMU with-cpu qemu64,-apic: no local APIC, the PIC goes straight to the CPU. TheIA32_APIC_BASEcode is gone from the chapter; the APIC returns in part IV. - Test:
pic::tests::the_cpu_has_no_local_apic; chapter 6'smake testgreen under QEMU 8.2.2 (container) and 10.2; with-apicremoved the kernel hangs again. The CI jobcourse(Ubuntu 24.04) runs it on every push. - Update (C12): chapter 12 uses the APIC; from there on
run-qemu.shstarts QEMU with-cpu qemu64again. - Remember: behaviour that depends on emulator details needs a run on the oldest supported version – CI runs Ubuntu's QEMU, a developer machine often a much newer one.
#26 · 2026-10-29 · translate was 4 KiB off inside the framebuffer's huge pages
- Symptom: found while writing course chapter 9, no visible effect in the kernel: the chapter's
translate, written after the kernel'stranslate_in, gave0xfd001000instead of0xfd000000for the framebuffer's HHDM address0xffff8000fd000000. The kernel's function computed it the same way. - Cause: Limine maps the framebuffer with 2 MiB pages and sets their PAT bit, which selects a caching type.
In a 2 MiB or 1 GiB page entry that bit is bit 12 (
0xfd0010eb), in a 4 KiB entry it is bit 7.translate_intook bits 12–51 as the address for every level and added the offset, so the PAT bit shifted the result by 4 KiB. Every caller in the kernel translates 4 KiB pages (user memory, the SMP trampoline check), which is why nothing broke. - Fix: for a huge page the address is rounded down to the page size before the offset is added.
- Test:
mem::paging::tests::translate_ignores_the_pat_bit_of_huge_pages(kernel) andpaging::tests::the_framebuffer_translates_exactly(course chapter 9). - Remember: an entry's bits mean different things on different levels – the Intel SDM's table per level, not one mask for all.
#27 · 2026-11-01 · Course chapter 12: the PIT ticked twice as fast through the I/O APIC
- Symptom: found while writing course chapter 12, before it was published. All tests were green and
sleep_ms(1000)reported 1010 ms – butsleep 5000in the shell returned after 2.7 s on the host clock (chapter 11: 5.2 s). Every test measured time in the same ticks that were wrong, so none could notice. - Cause: the chapter routes the PIT's IRQ 0 through the I/O APIC for a tenth of a second, to measure the local
APIC timer against it. The PIT ran in mode 3 (square wave), as since chapter 6, and through the I/O APIC that gave
two interrupts per period, 200 Hz: the calibration measured 312 274 APIC timer counts per tick instead of about
625 000 (QEMU's APIC timer runs at 1 GHz, divided by 16). The PIC of chapters 6–11 gave one per period. The same
under QEMU 8.2.2 and 10.2. In mode 2 (rate generator, one short pulse per period) the count is 624 593 and
sleep 5000takes 5.2 s. The reference kernel is not affected: it measures the APIC timer with PIT channel 2, polled, and never routes IRQ 0. - Fix: the chapter's
pit::inituses mode 2. - Test:
lapic::tests::the_timer_was_measured_against_a_100_hz_clock(course chapter 12): 600 000–650 000 counts per tick; with mode 3 it fails with311689 counts per tick. - Remember: a clock cannot be checked against itself. A test of time needs a second, independent clock – here the APIC timer's known rate under QEMU, or the host's clock.
#28 · 2026-11-01 · Course chapter 13: the boot hung now and then in task::init
- Symptom: found while testing chapter 14: the boot check
fault=overflowfailed 2 times in 20, and chapter 13 (already merged) hung 1 time in 20 at the same place – after theKeyboard:line, beforeThreads:. Its seven test-kernel runs had all been green: the tests start the scheduler too, but the window is small. - Diagnosis: booted in a loop until it hung, then
info registersthrough the QEMU monitor: RIP in the idle thread'shlt(task.rs:208), interrupts on, RSP on the idle thread's stack – andmainin no queue. - Cause:
task::initset up the scheduler in steps with interrupts on: first a scheduler whoseidlefield was 0 – thread 0 ismain– thenspawn("idle"), then the real idle id. A tick between the steps found a ready thread and calledyield_now, which never queues the idle thread – and tookmainfor it.mainwas never queued again, and the CPU halted in the idle thread for good. The reference kernel is not affected: itstask::initruns entirely with interrupts off; the course chapter lost that while being made smaller. - Fix:
initbuilds both threads first (new_thread, the idle thread never queued) and installs the finished scheduler in one step with interrupts off. In chapters 13 and 14. - Test:
task::tests::the_idle_thread_is_thread_1_and_never_queued; 40 boots of chapter 13 without a hang (before: 3 of 40). - Remember: a structure that an interrupt handler reads must never be visible half built – build it aside, then publish it in one step with interrupts off.
#29 · 2026-11-06 · Course chapters 12–15: the timer calibration test failed on a busy host
- Symptom: while chapter 15 ran 6 times with all 4 host cores busy (to imitate a CI runner):
the_timer_was_measured_against_a_100_hz_clockfailed twice with 597 649 and 596 420 counts per tick. - Cause: the test, not the kernel. The local APIC timer is measured against the PIT's interrupts; on a loaded host QEMU delivers them a little late, so the 10 ticks take a little longer and the count per tick comes out about 4 % low. The window 600 000–650 000 around the expected 625 000 left too little room.
- Fix: 550 000–700 000 in chapters 12 to 15. Bug #27 halved the value (about 312 000) and is still caught.
- Test: chapter 15's unit tests 4 times with the host fully loaded, all passed.
- Remember: like #22 and #23: a test that measures time needs room for a slow machine – here on both sides.
#30 · 2026-11-06 · Course chapter 15: join returned while the ended thread was still on its CPU
- Symptom: chapter 15's unit tests, run 8 times, 4 of them with all host cores busy:
ended_threads_give_their_ stack_backfailed twice – once 8 frames (one thread stack) were missing after all threads were joined. - Cause:
exitwoke the joiners as soon as the thread was marked dead – but it was still on its CPU until the switch away from it had finished, soreaphad to leave its stack alone.joinreturned, and the stack was freed only by a laterspawnorjoin. On one CPU that gap was invisible: the joiner could only run after the switch. - Fix: the joiners are woken in
finish_switch, once the dead thread is off its CPU, andjoinwaits for "dead and not on a CPU". The test's threads also wait for a signal, so that none ends before the frames are counted. - Test:
ended_threads_give_their_stack_back, 6 runs, 4 with the host loaded: all passed. - Remember: on SMP, "the thread ended" and "the thread's stack is free" are two moments, not one.
#31 · 2026-11-06 · Course chapters 15–20: a GDT test asked whichever CPU the test thread was on
- Symptom:
make coursefor release 1.1.0: chapter 20'sgdt::tests::gdtr_points_to_our_tablefailed once – the GDTR held a heap address, the test expected the boot CPU's static GDT. CI and all earlier runs had passed. - Cause: the test, not the kernel. Since chapter 15 every CPU runs threads, so the test thread
mainmay have moved to an AP – and each AP loads a GDT of its own (chapter 14).sgdtanswered for the CPU the test ran on. - Fix: the test asks every CPU itself with
smp::run_on: CPU 0 has the static GDT, every CPU the right size, no two CPUs the same table. Changed in chapters 15–20 (chapter 14's threads stay on the BSP). - Test: the fixed test, 3 runs of chapter 20 and one of each of chapters 15–19: all passed.
- Remember: "the CPU I run on" is a moving target once threads migrate – a per-CPU question has to be asked on that CPU (as chapter 15 learned for the double fault stack).
Known pitfalls (not bugs, but worth remembering)
- The Limine host utility (
limine bios-install) needs a C compiler (gcc). It is not required for booting the ISO in QEMU with-cdrom; it is only needed to make the ISO bootable as a hard disk / USB image. sudodoes not work through!in Claude Code because there is no TTY for the password prompt. I run installs in a separate terminal.cargo fmt -- <file>formats the whole crate, not just the file. Format deliberately withmake fmt, and commit pure formatting separately from functional changes.- Limine sets the USER bit on its upper-half page tables (PML4/PDPT/PD entries; the leaf entries are supervisor-only).
Harmless while the leaves are right, but
paging::initclears USER in all upper-half PML4 entries so ring 3 can never reach kernel memory by accident (found by the testkernel_half_is_fully_populated). x86_64-unknown-nonedefaults tocode-model=kernel(addresses in the top 2 GiB). User programs linked at 0x40_0000 need-C code-model=small, otherwise GNU ld fails with "relocation truncated to fit".- LLVM may delete an unused allocation and assume it succeeded.
alloc(huge).is_null()was optimized tofalseinheaptest, so the "allocation must fail" check failed although the kernel refused the memory. Pass the pointer throughcore::hint::black_boxwhen testing allocation failure. - Empty slices from Rust come with dangling pointers (e.g.
0x1for an emptyVec<u8>). The syscall pointer check rejectedspawn(path, [])withEFAULTbecause page 0 is unmapped; zero-length ranges are now always accepted. - The serial console sends
\r\nfor every\n. E2E expectations spanning several lines must contain\r\n. - rustc no longer accepts
+sse/-soft-floatonx86_64-unknown-none("must be disabled to ensure that the ABI of the current target can be implemented correctly", soon a hard error). Hard-float user programs need their own target JSON and-Zbuild-std; build scripts ofcore's dependencies then need a host C toolchain (gcc, glibc headers/crt files). - LLVM's assembler rejects label differences inside memory operands in
global_asm!(Intel syntax):mov eax, [ebx + (a - b)]→ "cannot use more than one symbol in memory operand". Encode such instructions with.byteand put the difference into a.word/.long(see the SMP trampoline). - The page allocator hands out the lowest frames first, so memory below 1 MiB is gone after early boot. Hardware that
needs low memory (the SMP trampoline) must reserve it at
pmm::inittime. spin0.12'sMutexhas noas_mut_ptr. To use the data of a lock you own without a guard (the scheduler lock is released by the next thread after a switch), keep the address of the data from a guard taken at init (task::SCHEDULER_DATA) and callforce_unlockafterwards.- Limine's stack has no guard page – a stack overflow silently corrupts memory instead of faulting (until M9 gives us our own stack).