The subsystem atlas and a path to independent expertise

Before you start#

Review source navigation, device model, architecture portability, maintainer workflow, and cross-subsystem capstones. This atlas inventories the upstream Linux v6.12 tree, a historical teaching snapshot rather than a current deployment recommendation. It is an entry map and study plan, not a claim that 96 chapters cover every driver, filesystem, architecture or device.

Learning goals#

Use a source inventory without confusing path coverage with semantic expertise, select an entry and prerequisite for an unfamiliar subsystem, extend the map from actual maintainership and tests, and build an independently reviewed evidence portfolio.

Source walkthrough#

A repository directory is an index into code, not a complete subsystem boundary. The same operation can cross architecture entry code, core APIs, drivers, filesystems, security hooks and userspace tooling. Conversely, a directory can contain many independently maintained drivers with different hardware contracts. The atlas below accounts for every top-level directory and every immediate directory under drivers/, fs/, net/ and arch/ in the upstream v6.12 tree. It groups entries to keep the map useful, and lists each covered path explicitly. Directory enumeration establishes coverage of names, not correctness of every interpretation or mastery of every device.

The three depth labels are deliberately conservative. WORKED means a named course chapter includes a concrete source walkthrough in the family, not that every member of the group was traced. SURVEYED means the course introduces the family or interface but does not establish each implementation. INDEPENDENT FOLLOW-ON means the reader must perform the investigation beyond this course. A row can list a source entry point and a next test without implying that the test ran. A grouped row's label does not turn every path in that row into a worked example; follow the named chapter and source to see its actual scope.

The v6.12 MAINTAINERS file contains this exact historical excerpt from the ext4 section; the inspected file has no file-level SPDX identifier or specific license notice, so consult the repository licensing information rather than inferring a narrower license:

S:	Maintained
W:	http://ext4.wiki.kernel.org
Q:	http://patchwork.ozlabs.org/project/linux-ext4/list/
T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tytso/ext4.git
F:	Documentation/filesystems/ext4/
F:	fs/ext4/

The status describes that historical section, and the path pattern identifies a family of files. It does not guarantee that all files under a group share a maintainer or that the same people remain responsible today. Find applicable positive and exclusion patterns, relevant subsystem documentation and recent history before drawing a routing conclusion. The maintainer tool can assist, but its output depends on input and options. Consult the kernel contribution guide and current subsystem documentation before acting on routing information.

The root Kconfig includes this exact v6.12 source excerpt; SPDX GPL-2.0; surrounding menu content is omitted:

source "drivers/Kconfig"

The statement includes the driver configuration menu. It does not select every driver or prove every architecture has the same options, compiler, page-table layout or devices. A source path can exist while its option is disabled, unavailable for the selected architecture, or dependent on other symbols. Read the relevant Kconfig and Makefile, then inspect definitions, callers and tests in that configuration. Root and family Kconfig links in the atlas are entry points, not evidence that every child is built together.

How to enter an unfamiliar family#

Start with a question narrow enough to test. “How does one driver release DMA mappings when probe fails?” is more actionable than “master all devices.” Identify the relevant device or interface and check the exact source revision and configuration. Read its Kconfig dependencies and Makefile to see when it is built; find the driver registration, probe, ordinary operation, remove and error labels. List the objects and references acquired at each step, the context in which callbacks run, and which locks or RCU rules protect them. Do not assume a module's filename identifies its entire call path.

The failure ladder in really_probe is a useful place to practice the error-label question. In drivers/base/dd.c, v6.12, SPDX GPL-2.0, the labels fall through, so a goto to a later label runs only the cleanup that follows it (surrounding code omitted):

dev_sysfs_state_synced_failed:
dev_groups_failed:
	device_remove(dev);
probe_failed:
	driver_sysfs_remove(dev);
sysfs_failed:
	bus_notify(dev, BUS_NOTIFY_DRIVER_NOT_BOUND);
	if (dev->bus && dev->bus->dma_cleanup)
		dev->bus->dma_cleanup(dev);
pinctrl_bind_failed:
	device_links_no_driver(dev);
	device_unbind_cleanup(dev);
done:
	return ret;
}

The ladder is arranged so that each label undoes the steps completed before the failure. The excerpt does not show what acquired each step, the success path that reaches driver_bound, the caller's locking, or each callback's behavior. Confirm the full function before relying on that order for any particular driver.

For a filesystem, trace a specific VFS operation through the filesystem callback, page cache or direct I/O, storage stack and completion. Note the file, inode, folio, transaction and request lifetimes; distinguish successful submission from durability. For networking, identify the network namespace, socket or packet, direction, queue and protocol state. A packet observed at one hook does not prove it reached another. For an architecture port, begin with boot and entry contracts, privilege levels, page size, memory ordering, interrupt controllers and DMA assumptions. A driver that works on x86-64 QEMU is not automatically portable to arm64 or RISC-V hardware.

Next locate a meaningful test or design one. KUnit can exercise internal logic, kselftest commonly exercises userspace-visible behavior and interfaces, and a full guest can test interactions; each has different dependencies and safety boundaries (KUnit documentation, kselftest documentation). A skip means the assertion was not exercised; kselftest explicitly reports skipped tests separately from passed tests (kselftest documentation). A configuration or hardware failure must not be converted into a passing result. For destructive storage, network, hotplug, fault or crash tests, use a dedicated disposable guest or recoverable dedicated hardware with a reviewed plan, bounded resources and a way to recreate the environment. The chapter 08 guest remains unbooted in this workspace because of the GCC 16/C23 incompatibility, so the course's source-only route does not imply a working VM.

The read–change–measure–review loop#

First read the implementation and record a specific invariant, such as “an object remains referenced until the completion callback cannot run.” Identify normal and error paths, including partial initialization and cancellation. Next formulate a minimal hypothetical change and a counterexample that distinguishes it from existing behavior. Do not change the shared course repository or send an upstream patch merely to complete this exercise. If a change is actually authorized, work in an appropriate isolated source checkout and preserve its base and build artifacts.

Then measure or test the claim under documented conditions. A source-only walkthrough can establish a branch and its return value, but cannot establish runtime scheduling, hardware behavior, durability or performance. A successful guest test can establish that a specific build and workload behaved as observed; it cannot prove a different architecture, configuration or device. Capture errors, skipped tests, missing instrumentation and confounders. Compare a known-bad baseline, the proposed fix, negative controls and neighboring configurations where applicable.

Finally seek review from someone able to challenge the mechanism and test. An independent reviewer should ask whether a pointer can outlive its owner, whether a callback can run in atomic context, whether cleanup reverses all acquired state, and whether the evidence matches the claimed configuration. A passing style tool or a count of chapters is not independent review. A correction can narrow or invalidate the original claim; record that change rather than hiding it. The maintainers and review channels in a historical file are not permission to send messages or publish work.

Planning a long specialization#

A practical multi-year path is iterative rather than a promise of a fixed calendar. First build a reliable lab and source-navigation habit: keep exact kernel and toolchain identities, know how to restore a disposable guest, and reproduce a small existing test without claiming unrun hardware coverage. Next choose a core family such as scheduler, virtual memory, VFS or networking and learn its invariants, locking and error handling through a sequence of small, reviewed investigations. Then follow one boundary into an architecture, driver or userspace interface, where assumptions about ordering, DMA, firmware and ABI become concrete.

An evidence portfolio should contain reproducible reports, source maps with versioned links, raw test outcomes including skips and failures, a before/after comparison where appropriate, and review feedback or documented unresolved objections. Include a case where a hypothesis was falsified and a case where the environment could not support a conclusion. Contributions and measurements matter more than the number of files read. A maintained test, a reviewed bug fix, a carefully explained regression or a validated performance investigation provides stronger evidence of a particular skill than a self-issued “expert” label.

Specialization does not mean ignoring adjacent systems. A storage engineer needs enough scheduler, memory and block knowledge to interpret latency; a networking engineer needs concurrency, DMA and security context; a virtualization engineer needs both guest and host memory lifetimes. Depth comes from repeatedly tracing real ownership and failure paths and asking experts to review them. The atlas intentionally leaves rare hardware, firmware, architecture-specific recovery and rapidly changing interfaces as follow-on work. No finite list here replaces maintainers' current documentation, source and independent test.

From inventory to an evidence portfolio#

Choose one atlas family and define a small source question before looking for an exercise. For example, an EDAC investigation could ask how one particular controller reports a corrected event and which user-visible counter changes. The entry point and hardware driver, not the word “EDAC” alone, determine the answer. Identify the exact kernel revision, architecture, configuration, event structure, callback context and lifetime. If the machine has no relevant controller, a source-only state table is an honest first artifact; it is not a substitute for testing that controller.

A first portfolio entry might include a diagram of one source path, a table of acquired references and failure labels, a test plan, and a record of which assumptions remain unverified. A later entry could reproduce a bug in a disposable guest, show a known-bad baseline and a proposed fix, and include negative controls. Another could compare performance with raw samples and uncertainty. A reviewer should be able to find the exact artifact and independently challenge its conclusion, including cases that did not work. Include a map of environment dependencies: toolchain, target architecture, selected configuration, test prerequisites and recovery method. A skipped hardware scenario belongs in that map with its reason, not in a list of passes. These details let another engineer reproduce the scope of a result or identify why it cannot be reproduced.

Independent expertise is cumulative but not automatic. A maintainer's review may identify a missing configuration, an architecture-specific ordering rule or a mistaken interpretation of an old API. The learner should revise the model, rerun affected tests and preserve the history of the correction. Eventually, substantial work in one area may support independent ownership under peer review, while neighboring areas still require specialists. The atlas's exhaustive path list is a navigation guarantee for this snapshot only, not a certificate of that expertise.

A concrete extension from the inventory#

Suppose you choose drivers/vdpa from the virtual-device family. First distinguish a vDPA device and its hardware or software backend from a virtio guest driver, a vhost backend and a VFIO-assigned device; their names overlap but their object ownership and trust boundaries differ. Find the selected vDPA driver's Kconfig and registration code, then trace feature negotiation, queue setup, DMA mapping and removal. Record which process or kernel object owns each mapping and how failure after partial setup unwinds it. A source file that compiles under one architecture does not establish that its backend is available on another machine.

The next artifact is a test plan with a positive setup, one deliberately invalid or unsupported configuration, and teardown while no DMA remains outstanding. If it requires hardware not available in a disposable guest, mark it unrun and keep the source trace as a bounded result. A useful review question is whether the proposed cleanup can race with a queue callback or device reset. Only after matching a real environment, collecting raw evidence and obtaining review should the row's depth be revised for that particular driver. The other paths in the group remain independently classified.

Practice#

Inventory and extend one row

In a clean Linux checkout whose v6.12 tag is available, inspect paths and configuration without modifying the checkout:

git describe --tags --exact-match v6.12
git ls-tree -d --name-only v6.12
git ls-tree -d --name-only v6.12:drivers | head -n 20
git show v6.12:MAINTAINERS | grep -n -A12 '^EXT4 FILE SYSTEM$'

The commands enumerate names and one historical maintainer section; they do not prove semantic coverage. A missing tag or shallow/incomplete checkout is a valid limitation. Pick one atlas row and follow its linked Kconfig or source entry to a specific function, failure branch and relevant test. Record a versioned path, prerequisite, uncertainty and safe next experiment. Do not submit a patch or contact maintainers as part of this exercise.

Source-only alternative: use the ext4 MAINTAINERS and root Kconfig excerpts above. Explain what each establishes, then select a grouped atlas family and write a follow-on question whose answer requires source and test evidence. Deliver a one-page research card with a claimed fact, a plausible alternative, missing evidence and review question. The map itself is supplied below in this reader chapter.

Knowledge check#

1. Why does enumerating every first-level directory not establish expertise in every driver?
2. What does the root Kconfig driver source line establish and what does it not establish?
3. Why can a source-only result and a guest runtime result support different claims?
4. What makes a portfolio stronger than a chapter completion count?
5. Why can a historical MAINTAINERS pattern not be treated as a current instruction to contact someone?

Answers#

1. Directories contain many implementations and interfaces cross directory boundaries. Names establish inventory coverage, not detailed behavior, hardware testing or review.
2. It includes the drivers configuration menu; it does not enable every driver or prove that a particular configuration builds or runs.
3. Source can establish code and conditional paths in a revision. A runtime observation establishes behavior only for its actual build, configuration and workload and can reveal context not visible from a snippet alone.
4. Reproducible artifacts, failed or skipped cases, measurements, source reasoning and independent review demonstrate specific skills and their limits. A reading count does not.
5. Maintainers and processes change, and the user has not authorized communication. Current routing and consent are separate steps.

Checkpoint#

Submit a research card and a multi-step specialization plan naming a source boundary, safe test, expected artifacts and review gate. Ready means the atlas depth label is not mistaken for complete coverage, a source claim is separated from runtime evidence, and uncertainties are explicit. Retry with a narrower operation if the next step cannot identify an object, invariant or test. This is not certification.

Sources#

• Linux v6.12 root tree
• MAINTAINERS v6.12
• Root Kconfig v6.12
• get_maintainer.pl v6.12
• Kernel testing overview

Complete v6.12 source-tree inventory#

The lists below were enumerated from GitHub’s nonrecursive contents API with ref=v6.12. A link names an existing directory in that response. Group descriptions are navigation aids; they are not an exhaustive semantic review. A WORKED label applies to the named chapter’s particular walkthrough, not every path in its group. The top-level and four first-level inventories are exhaustive for directory names at the tag; source files and deeper directories still need independent study.

Top-level directories

drivers first-level directories

fs first-level directories

net first-level directories

arch first-level directories

Cross-directory specialties and next steps

Some names are subsystems rather than directory names. DAX, persistent memory, CXL and HMM cross drivers/dax, drivers/nvdimm, drivers/cxl and mm; begin with memory placement and DMA/IOMMU, then independently trace mapping invalidation and pinning. Memory hotplug, EDAC/RAS and pstore cross mm, drivers/edac, drivers/ras and fs/pstore; livepatch and RAS surveys their failure boundaries. SCHED_EXT is a v6.12 scheduler family within kernel/sched, not a top-level directory; use scheduler core, then inspect kernel/sched/ext.c, its Kconfig and tests independently.

Securityfs is implemented in the security tree rather than a fs/securityfs first-level directory; start at security/inode.c and LSM hooks. NFS, SMB/CIFS, Ceph, 9p, FUSE, configfs, procfs, sysfs and debugfs have different consistency and trust models; choose one and inspect its exact paths above. IPsec spans net/xfrm, protocol code and crypto; mesh can involve net/batman-adv or wireless implementations. PPP lives in driver-side paths such as drivers/net/ppp, below this first-level inventory. Xen, Hyper-V and confidential VMs span architecture and virtual-device code; KVM provides a prerequisite, not a universal confidentiality guarantee.

PTP/PPS, reset, hwspinlock, interconnect, LEDs, backlight, W1, serio, parport, NTB, vDPA, TEE, firmware, DPLL, counter, extcon, misc, HID, FPGA and staging have explicit parent paths above; some detailed names such as backlight and serio are deeper than the enumerated level. Follow their Kconfig, maintainer patterns and tests independently. The drivers/staging tree is not a claim that all staged code is production-ready. Use git ls-tree recursively for the chosen family and keep new findings and missing tests in the research card.