Documentation coverage matrix

This page is the honest inventory of what exists in the tree versus what the Sphinx manual (platform-docs) actually explains today.

Note

Canonical technical contracts are maintained in newdocs/.
Use this matrix primarily as a migration/debt tracker for Sphinx coverage, not as the sole source of platform truth.

Legend

Status

Meaning

Sphinx

Has a dedicated page under platform-docs/docs/ (even if short).

Legacy HTML

Narrative or reference exists under repo-root documentation/ (open locally; not part of the Sphinx build).

Rustdoc

API HTML under documentation/kernel_api_reference/ (from cargo doc / rustdoc).

Missing

No first-class write-up; only code, comments, or scattered notes.

The goal is to drive every row to Sphinx (or explicitly retire legacy) so one search box and one site cover the project.

Sphinx pages this matrix points at (use the sidebar or search; MyST {doc} links from this file fail cross-ref resolution during build):

  • explanation/system-architecture

  • explanation/foundation-debt

  • explanation/terminal-stack

  • reference/wm-v1-platform-roadmap

  • reference/launch-paths

  • reference/dynamic-linking

  • reference/sdk-contract

  • reference/sdk-p1scode-v0-release-notes

  • reference/legacy-narrative-docs

  • explanation/documentation-map

1. Kernel & runtime (src/)

Subsystem

Primary code

Legacy / other

Sphinx

Status

Entry, init flow

src/main.rs

documentation/welcome.html, documentation/architecture.html

explanation/system-architecture, canonical boot-and-init

Partial (canonical boot path; welcome HTML is broad)

Panic / diagnostics

src/main.rs, src/platform/bsod.rs, src/sys/bsod.rs

documentation/hardware.html (tangential)

explanation/foundation-debt (incidents)

Partial

Syscall surface

src/kernel/syscalls.rs

documentation/kernel_api_reference/ (fragments)

explanation/foundation-debt, reference/wm-v1-platform-roadmap, canonical syscalls-reference

Partial

Tasks / scheduler

src/kernel/task.rs, src/kernel/smp.rs

documentation/smp_threading.html

canonical scheduler-smp (+ process-lifecycle)

Sphinx (boot is single-core; legacy HTML assumes full SMP)

Kernel shell

src/kernel/shell.rs

—

canonical boot-and-init §2

Partial

ELF / PE loaders

src/kernel/elf_loader.rs, src/kernel/pe_loader.rs

documentation/dynamic_linker.html (mixed narrative)

canonical elf-and-loaders; reference/dynamic-linking (userspace ld / p1dl); canonical dynamic-linking-abi (DT_* / reloc index)

Sphinx (split: kernel load vs dynamic link)

IPC broker (queues, routing)

src/sys/ipc.rs

documentation/security_ipc.html

canonical ipc-broker; ipc-wire-reference (message_type index); explanation/foundation-debt §2

Partial

Syscall 50 present maps

src/sys/ipc_present_maps.rs, src/mm/memory.rs

—

explanation/foundation-debt §3

Sphinx

RegCube (kernel hives)

src/sys/regcube.rs

documentation/regcube.html, documentation/regcube_editor.html

explanation/foundation-debt §4, explanation/system-architecture, canonical regcube

Partial

Window manager (in-kernel / legacy paths)

src/sys/window.rs

documentation/kernel_api_reference/.../sys/window/

Missing dedicated page

Rustdoc

XDG portal daemon

src/sys/xdg_portal.rs

documentation/kernel_api_reference/.../xdg_portal/

Missing

Rustdoc

udev / device registry

src/sys/udev.rs, src/sys/device_manager.rs

kernel_api_reference

Missing

Rustdoc

PCI

src/sys/pci.rs

documentation/pci_pnp.html

Missing

Legacy HTML

PnP

src/sys/pnp.rs

documentation/pci_pnp.html

Missing

Legacy HTML

PTY

src/fs/pty.rs, src/kernel/syscalls.rs (sys_read flags)

—

explanation/terminal-stack, reference/pty-v1-design

Partial (design doc tracks v1; A.3 / SIGWINCH open)

VFS

src/fs/vfs.rs

documentation/filesystem.html, documentation/vfs_pseudo.html

canonical vfs-and-filesystem, staging-and-ramdisk

Sphinx (see canonical for current ramdisk/FAT policy)

FAT

src/fs/fat.rs, src/fs/native_fat.rs

documentation/filesystem.html

canonical vfs-and-filesystem §5

Sphinx

Memory manager

src/mm/memory.rs, src/mm/frame_allocator.rs, src/mm/allocator.rs

documentation/memory.html

explanation/foundation-debt §3, §5, §5.3 (brk vs mmap client slabs)

Partial

Paging / arch

src/arch/paging.rs, src/arch/idt.rs, src/arch/gdt.rs, src/arch/apic.rs, src/arch/ioapic.rs, src/arch/cmos.rs

documentation/hardware_io.html

Missing

Legacy HTML

ACPI HAL

src/hal/acpi.rs

documentation/hardware.html

Missing

Legacy HTML

PS/2 keyboard

src/drivers/input/ps2.rs

documentation/input_drivers.html

Missing

Legacy HTML

PS/2 mouse

src/ps2_mouse.rs, src/drivers/input/absolute.rs

documentation/input_drivers.html, rustdoc

Missing

Legacy + Rustdoc

GOP / display

src/drivers/video/gop.rs, svga.rs, mesa.rs, drm.rs

documentation/video_advanced.html, documentation/hardware.html

Missing

Legacy HTML

USB xHCI

src/drivers/usb/xhci.rs

documentation/hardware_io.html

Missing

Legacy HTML

Audio driver

src/drivers/audio.rs

documentation/audio.html, documentation/network_audio.html

Missing

Legacy HTML

TCP/IP stack

src/net/*.rs (tcp, udp, ipv4, icmp, dns, ntp, ethernet, rtl8139, wpa2, …)

documentation/network.html

Missing

Legacy HTML

Logger

src/sys/logger.rs, src/platform/logging/

—

Missing

Missing

Crypto boot

src/crypto.rs, src/platform/crypto/

rustdoc crypto

Missing

Rustdoc

COM1 trace

src/platform/com1_trace.rs

—

Missing

Missing

App manager / config / input / theme / pam / polkit / keyring / bubblewrap

src/sys/app_manager.rs, config.rs, input.rs, theme.rs, pam.rs, polkit.rs, keyring.rs, bubblewrap.rs

scattered

Missing

Missing

IPC OSL

src/sys/ipc_osl.rs

—

Missing

Missing

MTRR

src/sys/mtrr.rs

—

Missing

Missing

Keyboard layout

src/sys/keyboard_layout.rs (stub); SDK/lib/p1keyboard-layout/ (US); apps/ps2d, apps/termd

—

newdocs/keyboard-input-and-layout; reference/userspace-input

Good for US; locale deferred

In-tree apps (kernel tree)

src/apps/*.rs, src/apps/deskgui/

overlaps with userspace apps/

Missing

Missing

Engine / 3D (in kernel tree)

src/engine/, src/model.rs, src/image.rs

documentation/engine.html

Missing

Legacy HTML

Render API (in kernel tree)

src/api/*.rs

documentation/api.html

Missing

Legacy HTML

2. Userspace apps (apps/ crates)

Each row is one Cargo package under apps/<name>/. Unless noted, Sphinx coverage is Missing (stub or nothing).

App / crate

Role (short)

Legacy HTML

Sphinx

init

PID 1, spawn graph

documentation/init_daemon.html

canonical boot-and-init §3, userland-matrix

deskgui

Compositor / Neural shell

documentation/deskgui.html, documentation/desktop_guide.html

Missing (only kernel-adjacent narrative in explanation docs)

dps

Shell on PTY slave (apps/dps)

—

explanation/terminal-stack, reference/pty-v1-design §Phase D

termd (gterm)

Graphical terminal on PTY master (apps/termd, package gterm); RGBA via p1_alloc_framebuffer

—

explanation/terminal-stack, newdocs/keyboard-input-and-layout, reference/pty-v1-design §9, explanation/foundation-debt §5.3

settings

Settings UI

documentation/customization.html (tangential)

Missing

wander

File explorer

documentation/file_explorer.html

Missing

surf

Browser shell

—

Missing

evnt

Event / log viewer

—

Missing

login

Session login

documentation/security.html

Missing

sh

Shell

—

Missing

coreutils, kill

Core CLI

documentation/cstd.html (SDK overlap)

Missing

ld

Userspace dynamic linker (ld.elf); eager binding — see coverage-matrix §6

documentation/dynamic_linker.html

Sphinx — reference/dynamic-linking, reference/coverage-matrix §6

ping, ifconfig, netstat, nslookup

Net tools

documentation/network.html

Missing

luad

Lua daemon

—

Missing

p1sc / p1scode_app

P1Script tooling

documentation/p1scode.html

Partial — reference/p1scode-status-and-scope, reference/p1scode-toolchain-workflow

p1s_pkg, p1s_linker, ps1de

Package / linker / IDE

documentation/package_manager.html, documentation/p1sdk.html

Partial — reference/p1scode-toolchain-workflow

oasis

Oasis app

—

Missing

test_app

Test harness

—

Missing

3. SDK & libc

Component

Code

Legacy

Sphinx

cstd (libc shim, syscalls, p1_framebuffer)

SDK/lib/cstd/

documentation/cstd.html, documentation/p1sdk.html

Partial — WM / PTY via other pages; §5.3 p1_alloc_framebuffer

p1window

SDK/lib/p1window/

—

reference/wm-v1-platform-roadmap, explanation/terminal-stack §1b

p1keyboard-layout

SDK/lib/p1keyboard-layout/ — PS/2 set‑1 US QWERTY maps

—

newdocs/keyboard-input-and-layout, reference/userspace-input

p1std (umbrella SDK)

SDK/lib/p1std/

documentation/p1sdk.html

SDK/README.md, reference/wm-v1-platform-roadmap

p1dl (dynamic-linking API)

SDK/lib/p1dl/ + bridge slot SDK/lib/cstd/src/p1dl_bridge.rs

documentation/dynamic_linker.html (older narrative)

Sphinx — reference/dynamic-linking, reference/coverage-matrix §6, reference/sdk-contract, reference/sdk-p1scode-v0-release-notes; SDK/shared-library-development.md (repo)

SDK/loader-fixtures/

hello-so, p1dl-runtime-smoke (.so + smoke app)

—

Sphinx — reference/dynamic-linking, reference/coverage-matrix §6; SDK/shared-library-development.md (repo)

scripts/run_p1dl_runtime_boot_smoke.py

QEMU / staging harness for p1dl + ld.elf

—

Sphinx — reference/dynamic-linking (§6); reference/coverage-matrix §6; SDK/shared-library-development.md (repo)

4. Tooling & build

Area

Location

Legacy

Sphinx

Root kernel crate / UEFI boot

Cargo.toml, src/, esp/

documentation/developer_quickstart.html

Missing

Userland linker

linker/

—

Missing

Build scripts

build.rs, build_all.bat, scripts/, tools/

—

Missing

Ramdisk / staging / dock .lnk

pack_*.py, esp/, reference/launch-paths

—

Partial (launch-paths only)

5. Other trees

Tree

Note

Sphinx

documentation/

Large pre-Sphinx narrative + rustdoc export

Not imported; see reference/legacy-narrative-docs

lua-5.4.6/

Upstream Lua

Missing

libs/, lib/

Legacy / native libs

Missing

6. Dynamic linking & shared objects (matrix summary)

Contract page: reference/dynamic-linking — policy, search paths, p1dl bridge, DL_E_*, acceptance criteria.

Implementation: apps/ld/src/main.rs (ld.elf on the ramdisk as \bin\ld.elf). Local build uses apps/ld/.cargo/config.toml and cargo +nightly check (P1Start target + build-std).

Phase-1 experimental relocation subset (ELF64 x86_64, eager binding only):

  • R_X86_64_RELATIVE, R_X86_64_GLOB_DAT, R_X86_64_JUMP_SLOT

  • R_X86_64_64

  • R_X86_64_PC32, R_X86_64_PLT32 (PLT32 handled like PC32 in this phase), R_X86_64_PC64

  • R_X86_64_GOTPCREL, R_X86_64_GOTPCRELX, R_X86_64_REX_GOTPCRELX (GOT slot addresses come from a loader pre-scan of GLOB_DAT / JUMP_SLOT for the symbol index)

  • R_X86_64_32, R_X86_64_32S

Explicitly out of scope (must fail loudly per contract): symbol versioning (DT_VER*), LD_LIBRARY_PATH, lazy PLT, text relocations, non-PIE .so, R_X86_64_COPY.

Fixtures & workflow (repo): SDK/loader-fixtures/hello-so (outputs hello.so, libreloc_smoke.so, transitive wrap/base pair), SDK/loader-fixtures/p1dl-runtime-smoke, SDK/shared-library-development.md, scripts/run_p1dl_runtime_boot_smoke.py. Ramdisk layout uses E lines in build/image.manifest.

Status: Experimental — not a production SDK contract; static ELFs remain the default (see reference/sdk-contract).

7. How to burn down the matrix

  1. Pick a subsystem (one row).

  2. Add reference/<subsystem>.md or explanation/<subsystem>.md with: purpose, main files, syscalls / wire formats, known bugs / debt links, how to test.

  3. Link it from this matrix (change Missing → Sphinx) and from explanation/documentation-map if it is a “hub” doc.

  4. When a Legacy HTML page is fully superseded, add a redirect note at the top of the new Sphinx page and stop editing the HTML.

This file should be updated whenever a new top-level module or apps/* crate ships.