Foundations: The Floor

This section is the floor. Seven concepts and six labs, and at the end of it you can write kernel code, load it, break it, debug it, and test it — which is the prerequisite for every other section and for every patch you will ever send.

It is also the longest section, and the one where people fall behind. That is not an accident: the concepts here are the ones with non-local failure modes. A mistake in context or concurrency does not produce a compiler error or a crash at the offending line. It produces a corrupted list on someone else's 96-core machine, three weeks later, once.

Learning Objectives

Before You Start

This section assumes a working lab rig. Specifically:

  [ ] A kernel tree that builds, with ccache, in an O= directory
  [ ] lab-fast.config and lab-paranoid.config applied and VERIFIED in .config
  [ ] A guest that boots to a shell in under 30 seconds, with -smp 4 or more
  [ ] GDB attaching, lx-dmesg working, breakpoints firing
  [ ] A way to get a .ko into the guest without rebuilding the initramfs

If any of those is not true, stop and finish Lab 1 first — it is the lab that builds them. Everything after it assumes you experiment freely, and you will not experiment freely if each experiment costs five minutes.

Warning: Run every lab in this section with -smp 4 at minimum, and re-run the concurrency work with -smp 8. A single-CPU guest makes broken locking look correct. That is the single most effective way to waste a month.

The Seven Concepts, and Why in This Order

flowchart TD
    UKB["1. The user/kernel boundary<br/>what crosses, and how"]
    KC["2. Kernel C<br/>the dialect and its rules"]
    CTX["3. Context and atomicity<br/>may this code sleep?"]
    CON["4. Concurrency<br/>who else is touching this?"]
    MEM["5. Memory<br/>which allocator, which flags"]
    DEF["6. Deferred work<br/>splitting the interrupt"]
    DM["7. The device model<br/>how code meets hardware"]
    UKB --> KC
    KC --> CTX
    CTX --> CON
    CTX --> MEM
    CON --> DEF
    MEM --> DEF
    DEF --> DM

Chapters 3 and 4 are the ones to slow down on. If you have limited time, read those two twice and skim the rest — the others you can look up, and those two you cannot, because you have to notice you need them.

The Six Labs

Labs 2, 3, 5, and 6 build on each other: the char device from Lab 3 is what Lab 4 debugs and what Lab 6 tests. Lab 5 is independent and can be done any time after Lab 2.

The Structures and APIs You Will Meet

A quick-reference index. Every name here should be grepped, not memorized — this table exists so you recognize a name when you hit it, not so you can recite it.

Tip: Two in-tree documents carry more of this section than any chapter here does, and both are in your checkout. Read them once now and again after Lab 3:

$EDITOR Documentation/core-api/memory-allocation.rst   # which allocator, which flags
$EDITOR Documentation/process/coding-style.rst         # short, opinionated, enforced

The Bugs This Section Exists to Prevent

Every one of these is common, and every one of them is caught by something you will turn on.

Deliverables

You have finished Foundations when all of these exist and are committed:

• A lab rig with a measured, written-down edit-to-breakpoint time under two minutes.
• modules/01-hello read line by line, with your annotations.
• Your own module with parameters, a failure path, and clean teardown — ten cycles, no leak.
• A character device with ioctl, a userspace exerciser, and a locking fix you can justify.
• Four diagnostic artifacts, each annotated line by line: an oops, a lockdep splat, a KASAN report, and a sleeping-in-atomic BUG.
• A syscall, its written ABI specification, and a paragraph arguing it should not exist.
• A KUnit suite and a kselftest, both verified to fail when the bug returns.
• predictions.md with a written prediction for every experiment in this section, and a one-sentence post-mortem for each one you got wrong.
• Every lab's code passing checkpatch.pl --strict, make C=1, and make W=1.

How to Verify You Are Actually Done

Not "did I do the labs" — can you do these cold?

# 1. Given an arbitrary kernel function, determine which contexts may call it.
#    Try it on three you have never read:
rg -n "^\w+ \w+\(" mm/vmalloc.c | shuf -n 3

# 2. Read a splat you did not produce. Search lore for a recent one:
#    https://lore.kernel.org — search "BUG: sleeping function called"
#    Can you say what the author did wrong, from the message alone?

# 3. Given an allocation site, name the allocator and flags and defend it.
rg -n "kmalloc\(|kzalloc\(|kvmalloc\(|vmalloc\(" drivers/ | shuf -n 5
#    For each: why that one? What would break with the alternatives?

# 4. Given a driver, find its bind path end to end.
ls drivers/misc/*.c | shuf -n 1
#    Which bus? What matches it? What does probe() do, in order? What does devres free?

If those four feel like work but not like guessing, you are done.

Contributor Profile: Foundations Graduate

This is what a maintainer can assume about you once this section is behind you.

The gap between here and a merged patch is workflow, not knowledge — which is exactly why Contribution comes next, and why it is short.

Next: The User/Kernel Boundary — what crosses the line, and why nothing that comes across it may ever be trusted.