Disk Tutorial

A separate Alquist series for building a real disk stack: MMC hardware, partitions, FAT32 read-only, file loading, ext4, journaled writes, diagnostics, and flash storage.

The Kernel Tutorial grew the machine from first blink to user programs. Storage deserves its own lane. This is not a throwaway demo path: each chapter grows a professional program-driver in small, testable steps, with a clear read-only phase before any write path is allowed near real media.

Shape of the work

The disk stack is split into a small universal core and filesystem-specific modules. The universal core owns the hardware driver, block reads, partition tables, partition devices, request pacing, and shared diagnostics. Filesystem modules own their own on-disk formats: FAT32 first, then ext4, and later flash filesystems. The shell talks to the disk program; the disk program talks to the right module for the selected partition and filesystem.

The safety ladder is explicit: read-only on real SD media, writes only on disposable images, then journaled writes with background diagnostics before writes are trusted on real devices.

The series

• 01MMC and partitions — hardware card driver, read-only LBA reads, partition theory, and MBR parsing
• 02Partition tables — disks with or without maps, MBR/GPT theory, partition boundaries, and unused ranges
• 03FAT32 files — FAT32 directories, short and long names, subdirectory lookup, cluster-chain reads, and printing /ALQ/HELLO.TXT on UART
• exMBR by registers — read LBA 0 and decode the partition table from DATA words
• exFAT32 dir by registers — compute root_dir_lba and list the first directory sector
• 04File loader — read a complete file into a caller-provided buffer for later demos
• 05Kernel loader from disk — pause the disk series and teach the kernel tutorial to load a program file
• 06Ext4 read-only — superblock, feature gates, block groups, inodes, directories, and file loading
• 07Ext4 growth — extents, larger files, cache policy, error reporting, and recovery boundaries
• 08Journaled writes and diagnostics — write transactions, replay, fsck-style checks, and background health programs
• 09FAT32 writes — return to simpler metadata writes after the journal discipline is understood
• 10Flash filesystems — wear, erase blocks, copy-on-write metadata, and flash-specific diagnostics

Long-term contract

The end goal is a complete storage subsystem, not a collection of UART tricks. Early chapters are small because the system is learning the vocabulary of disks: cards, sectors, partitions, directories, files, caches, metadata, failure modes. Later chapters use that vocabulary to build write paths, journal replay, fsck-style repair, and background diagnostic programs without changing the public shape of the disk stack.