ZLFS: multi-block inode map (format v2) and cached reads

Two limits fall: the 512-inode ceiling of the single-block inode map,
and the uncached (B_INVAL) read path.

Format v2: the checkpoint block now carries zc_imap_nblocks and, right
after its header, a little-endian array of the inode-map block LBAs, so
one checkpoint addresses about 500 map blocks -- roughly 256000 inodes
at a 4 KB block size (ZLFS_MAXINO).  The in-core map is allocated in
whole blocks and grown on demand by zlfs_imap_grow; a commit writes
however many map blocks the inode count needs, snapshotting zm_ninodes
once so the block count, the entries written, and zc_ninodes always
agree.  The cleaner's durable pass re-reads the checkpoint block and
walks every map block it names (the zm_imap_lba field is gone).  Mount
validates the map-block LBAs and rejects v1 images (version bump);
newfs_zlfs writes the new layout.

Reads now go through the buffer cache.  This is coherent with the raw
zoned writes because the log never overwrites a live LBA: contents
change only when a zone is reset, and both reset sites (the cleaner and
the superblock-zone ping-pong) now purge the device's cached buffers
via vinvalbuf before the LBAs can be reused.

Add zlfs-manyfiles.sh: creates 700 files (past the old 512 ceiling),
verifies the population and sampled contents across a remount, then
checks removal persists.  functional_testing.md updated.

Author: xsub

README.md

@@ -348,10 +348,12 @@ On-disk format (`sys/sys/zlfs.h`):
   because NVMe ZNS namespaces have no conventional zones; the header
   documents append rules, mount discovery, the block-size bootstrap, and
   the both-zones-full crash recovery case.
-- The checkpoint locates a block-sized inode map (inode number to device
-  LBA) and the root inode.  Directories are arrays of fixed 128-byte
-  entries.  Inodes carry twelve direct block pointers plus a single
-  indirect block.
+- The checkpoint locates the inode map (inode number to device LBA) and
+  the root inode.  The map spans multiple blocks -- the checkpoint block
+  carries the array of map-block LBAs after its header, addressing about
+  256000 inodes at a 4 KB block size (format v2).  Directories are
+  arrays of fixed 128-byte entries.  Inodes carry twelve direct block
+  pointers plus a single indirect block.
 
 Userland:
 
@@ -415,15 +417,15 @@ Current limitations (documented in the code; each is a natural next step):
   live and superseded blocks are not compacted (a copying cleaner is
   future work), so space in mixed zones is reclaimed only once
   everything in them is superseded.
-- ZLFS blocks are read uncached (`B_INVAL`): raw zoned writes and zone
-  resets bypass the buffer cache, so caching would serve stale data once
-  a zone is recycled.  Proper buffer-cache integration is future work.
+- Reads go through the buffer cache.  This is coherent with the raw
+  zoned writes because the log never overwrites a live LBA; the cache
+  is purged whenever a zone reset makes cached blocks stale.
 - The commit path is not yet safe against concurrent vnode operations.
 
 Remaining sequence toward a general-purpose filesystem:
 
-1. Double/triple indirect blocks and block-level buffer-cache integration
-   (so files need not be buffered whole and reads cache safely).
+1. Double/triple indirect blocks and per-block dirty tracking (so files
+   need not be buffered whole in memory).
 2. A copying cleaner (compact mixed live/dead zones).
 3. Concurrency-safe commit.
 

functional_testing.md

@@ -36,6 +36,8 @@ size 4096; superblock (SB) zones 0-1, 126 data zones.
 
 | Feature | Commit | Verified so far | Missing evidence |
 |---|---|---|---|
+| Multi-block inode map (format v2: checkpoint carries the map-block LBA array; ~256k inodes at 4k; in-core map grows on demand) | pending push | adversarial round in progress | `zlfs-manyfiles.sh sd1c` (700 files > old 512 ceiling, remount, count + sampled contents); needs kernel rebuild AND `newfs_zlfs` reinstall (v2), plus reformat — v1 images are rejected |
+| Read caching restored (no more blanket `B_INVAL`; cache purged via `vinvalbuf` after any zone reset) | pending push | adversarial round in progress | churn v2 rerun must still PASS (the reset-purge path is exercised by the cleaner run at ~i120 and the remount) |
 | SB-zone recycling (reset stale SB zone on ping-pong) | `422cb631771` | 2 adversarial rounds (caught FWRITE and wp-tracking bugs, then pass) | never exercised on VM: one SB zone holds 16384 superblocks (131072 LBAs / 8 per SB), so the first ping-pong needs ~16k commits; churn v2 produces ~300 — a dedicated many-commit test or a smaller-zone QEMU profile is needed |
 
 ## 3. Under analysis / known gaps
@@ -46,7 +48,8 @@ size 4096; superblock (SB) zones 0-1, 126 data zones.
 | Corrupt-metadata hardening | a self-referential indirect entry (entry LBA == `zi_ib[0]`) would sleep forever in `getblk` (B_BUSY held by caller) | unreachable with well-formed metadata (allocator hands out distinct LBAs) | add bounds/identity checks on indirect entries when fsck-style validation is designed |
 | `statfs` free-space approximation | `f_bfree` counts EMPTY-condition zones only; mixed zones count as used; live_bytes is a zero/nonzero flag, inflated by duplicate marking | cosmetic accounting | proper per-zone byte accounting with the copying cleaner |
 | `zst_live_bytes` semantics | only tested against 0 in the reset loop; not a true byte count | none today; trap for future code | rename or fix when the copying cleaner needs real counts |
-| Inode map is a single block | hard cap of 512 inode numbers (510 usable files/dirs alive at once); numbers are now reused after removal, but the live-count ceiling stands | churning workloads fine; wide trees will hit ENOSPC at 510 live inodes | multi-block inode map (format change) |
+| Inode ceiling (was: single-block map, 512) | format v2 raises the cap to `ZLFS_CKPT_NIMAP * epb` (~256000 at a 4 KB block: ~500 map-block LBAs fit in the checkpoint block) | wide trees fine now; the ~256k cap is structural until the map gets its own indirection | none planned; revisit only if a workload needs more |
+| `zlfs_imap_grow` swaps `zm_imap` under `zm_lock` only | readers (`read_dinode`, commit, cleaner pass 2, remove/rmdir/rename) index the map without `zm_lock`; safe today because all accesses are single-expression under the kernel lock and grow has no sleep between copy and install — a latent use-after-free the moment these paths run MP-unlocked | none under the current single-threaded assumption | take `zm_lock` (or `zm_wlock`) in map readers as part of the concurrency-safe-commit phase |
 
 ## 4. Later (roadmap order)
 

regress/sys/sys/dkzone/zlfs-manyfiles.sh

@@ -0,0 +1,82 @@
+#!/bin/sh
+set -eu
+
+# ZLFS multi-block inode map test.
+#
+# Creates more files than a single-block inode map can hold (512
+# entries at a 4096-byte block), so the checkpoint must reference
+# multiple map blocks (format v2), and verifies the whole population
+# survives a remount.
+#
+# WARNING: this reformats the given disk with newfs_zlfs.
+
+usage()
+{
+	echo "usage: $0 disk [mount-point [count]]" >&2
+	echo "example: $0 sd1c /mnt/zlfs 700" >&2
+	echo "warning: this reformats the disk with newfs_zlfs" >&2
+	exit 1
+}
+
+die()
+{
+	echo "$0: $*" >&2
+	exit 1
+}
+
+section()
+{
+	echo
+	echo "== $* =="
+}
+
+disk=${1-}
+mnt=${2-/mnt/zlfs}
+count=${3-700}
+
+[ -n "$disk" ] && [ $# -le 3 ] || usage
+[ "$(id -u)" -eq 0 ] || die "must run as root"
+
+dev=/dev/$disk
+
+section "newfs + mount"
+umount "$mnt" 2>/dev/null || true
+newfs_zlfs "$disk"
+mkdir -p "$mnt"
+mount_zlfs "$dev" "$mnt"
+
+section "create $count files (over the old 512-inode ceiling)"
+mkdir "$mnt/many"
+i=0
+while [ "$i" -lt "$count" ]; do
+	echo "payload-$i" > "$mnt/many/f$i" ||
+	    die "create failed at file $i"
+	i=$((i + 1))
+done
+sync
+n=$(ls "$mnt/many" | wc -l | tr -d ' ')
+[ "$n" -eq "$count" ] || die "expected $count files, found $n"
+echo "  ok: $count files created and committed"
+
+section "population survives remount?"
+umount "$mnt"
+mount_zlfs "$dev" "$mnt"
+n=$(ls "$mnt/many" | wc -l | tr -d ' ')
+[ "$n" -eq "$count" ] || die "after remount: expected $count, found $n"
+[ "$(cat "$mnt/many/f0")" = "payload-0" ] || die "f0 corrupted"
+mid=$((count / 2))
+[ "$(cat "$mnt/many/f$mid")" = "payload-$mid" ] || die "f$mid corrupted"
+last=$((count - 1))
+[ "$(cat "$mnt/many/f$last")" = "payload-$last" ] || die "f$last corrupted"
+echo "  ok: $count files and sampled contents intact after remount"
+
+section "cleanup: remove all, rmdir, remount"
+rm "$mnt"/many/f*
+rmdir "$mnt/many"
+sync
+umount "$mnt"
+mount_zlfs "$dev" "$mnt"
+[ ! -d "$mnt/many" ] || die "directory resurrected after remount"
+echo "  ok: removal persisted"
+
+section "PASS"

sbin/newfs_zlfs/newfs_zlfs.c

@@ -453,17 +453,20 @@ write_filesystem(int fd, const char *path, const struct zone_geometry *g,
 	    sizeof(imap_ent));
 	write_block(fd, path, lba[ZLFS_MKFS_IMAP], secsize, blk, block_size);
 
-	/* Block 6: checkpoint. */
+	/* Block 6: checkpoint (one-block inode map; LBA follows header). */
 	memset(blk, 0, block_size);
 	memset(&zc, 0, sizeof(zc));
 	zc.zc_magic = htole32(ZLFS_MAGIC);
 	zc.zc_version = htole32(ZLFS_VERSION);
 	zc.zc_generation = htole64(0);
 	zc.zc_root_ino = htole64(ZLFS_ROOT_INO);
-	zc.zc_imap_lba = htole64(lba[ZLFS_MKFS_IMAP]);
+	zc.zc_imap_nblocks = htole64(1);
 	zc.zc_ninodes = htole64(ZLFS_FIRST_INO + 1);
 	memcpy(zc.zc_uuid, uuid, sizeof(zc.zc_uuid));
 	memcpy(blk, &zc, sizeof(zc));
+	imap_ent = htole64(lba[ZLFS_MKFS_IMAP]);
+	memcpy(blk + sizeof(struct zlfs_checkpoint), &imap_ent,
+	    sizeof(imap_ent));
 	crc = crc32c(blk, block_size);
 	((struct zlfs_checkpoint *)blk)->zc_checksum = htole64(crc);
 	write_block(fd, path, lba[ZLFS_MKFS_CKPT], secsize, blk, block_size);

sys/sys/zlfs.h

@@ -51,7 +51,7 @@
 #include <sys/types.h>
 
 #define ZLFS_MAGIC	0x54BDCC01	/* "ZLFS" NEW */
-#define ZLFS_VERSION	1
+#define ZLFS_VERSION	2	/* 2: multi-block inode map */
 
 /* Zones reserved at the start of the device for the superblock log. */
 #define ZLFS_SB_ZONES	2
@@ -181,22 +181,31 @@ struct zlfs_dirent {
 /*
  * Checkpoint: the filesystem's mount entry point.  zs_checkpoint_lba
  * in the superblock points at the newest checkpoint block.  The
- * checkpoint locates the inode map -- a block-sized little-endian
- * array of u_int64_t device LBAs indexed by inode number, where
- * imap[ino] == 0 means the inode does not exist -- and names the root
- * inode.  zc_checksum is CRC32C over the whole zs_block_size-sized
- * block with zc_checksum taken as zero.
+ * checkpoint locates the inode map -- a little-endian array of
+ * u_int64_t device LBAs indexed by inode number, where imap[ino] == 0
+ * means the inode does not exist -- and names the root inode.
+ *
+ * The map spans zc_imap_nblocks block-sized extents; their device LBAs
+ * are a little-endian u_int64_t array that starts immediately after
+ * this header inside the checkpoint block, so a checkpoint addresses
+ * up to ZLFS_CKPT_NIMAP(bsize) map blocks (about 500 at a 4096-byte
+ * block, or ~256000 inodes).  zc_checksum is CRC32C over the whole
+ * zs_block_size-sized block with zc_checksum taken as zero.
  */
 struct zlfs_checkpoint {
 	u_int32_t	zc_magic;	/* ZLFS_MAGIC */
 	u_int32_t	zc_version;	/* ZLFS_VERSION */
 	u_int64_t	zc_generation;	/* matches the superblock generation */
 	u_int64_t	zc_root_ino;
-	u_int64_t	zc_imap_lba;	/* device LBA of the inode-map block */
+	u_int64_t	zc_imap_nblocks; /* inode-map blocks; LBAs follow */
 	u_int64_t	zc_ninodes;	/* number of inode-map entries */
 	u_int8_t	zc_uuid[16];	/* must match the superblock UUID */
 	u_int64_t	zc_reserved[4];
 	u_int64_t	zc_checksum;
 };
 
+/* Inode-map block LBAs storable in one checkpoint block. */
+#define ZLFS_CKPT_NIMAP(bsize) \
+	(((bsize) - sizeof(struct zlfs_checkpoint)) / sizeof(u_int64_t))
+
 #endif /* _SYS_ZLFS_H_ */

sys/zlfs/zlfs_alloc.c

@@ -226,36 +226,67 @@ zlfs_clean(struct zlfs_mount *zmp)
 	struct zlfs_zone_state *zst;
 	struct zlfs_node *znp;
 	struct buf *bp;
-	u_int64_t *dimap;
+	const struct zlfs_checkpoint *dc;
+	u_int64_t *dimap, *lbas;
 	u_int32_t bsize = zmp->zm_super.zs_block_size;
-	u_int64_t i, ino, lba, maxino = bsize / sizeof(u_int64_t);
-	int error;
+	u_int64_t i, j, ino, lba, nblocks, epb = bsize / sizeof(u_int64_t);
+	int error, nreset = 0;
 
 	for (i = 0; i < zmp->zm_nzones; i++)
 		zmp->zm_zones[i].zst_live_bytes = 0;
 
-	/* Metadata roots of the durable checkpoint. */
+	/* Metadata root: the durable checkpoint block. */
 	zlfs_gc_mark(zmp, zmp->zm_super.zs_checkpoint_lba);
-	zlfs_gc_mark(zmp, zmp->zm_imap_lba);
 
-	/* Pass 1: the durable live set, from the on-disk inode map. */
-	if (zmp->zm_imap_lba != 0) {
-		if (zlfs_bread_block(zmp, zmp->zm_imap_lba, &bp) != 0)
+	/*
+	 * Pass 1: the durable live set.  Re-read the checkpoint block to
+	 * find the inode-map blocks it references, mark them, and walk
+	 * every inode they name.
+	 */
+	if (zmp->zm_super.zs_checkpoint_lba != 0) {
+		if (zlfs_bread_block(zmp, zmp->zm_super.zs_checkpoint_lba,
+		    &bp) != 0)
 			return;
-		dimap = malloc(bsize, M_TEMP, M_WAITOK);
-		memcpy(dimap, bp->b_data, bsize);
+		dc = (const struct zlfs_checkpoint *)bp->b_data;
+		nblocks = letoh64(dc->zc_imap_nblocks);
+		if (nblocks == 0 || nblocks > ZLFS_CKPT_NIMAP(bsize)) {
+			brelse(bp);
+			return;		/* unusable map; reclaim nothing */
+		}
+		lbas = mallocarray(nblocks, sizeof(u_int64_t), M_TEMP,
+		    M_WAITOK);
+		for (j = 0; j < nblocks; j++)
+			lbas[j] = letoh64(((const u_int64_t *)
+			    ((const u_int8_t *)bp->b_data +
+			    sizeof(struct zlfs_checkpoint)))[j]);
 		brelse(bp);
-		for (ino = 0; ino < maxino; ino++) {
-			lba = letoh64(dimap[ino]);
-			if (lba == 0)
+
+		dimap = malloc(bsize, M_TEMP, M_WAITOK);
+		for (j = 0; j < nblocks; j++) {
+			if (lbas[j] == 0)
 				continue;
-			if (zlfs_gc_mark_inode(zmp, lba) != 0) {
-				free(dimap, M_TEMP, bsize);
-				return;
+			zlfs_gc_mark(zmp, lbas[j]);
+			if (zlfs_bread_block(zmp, lbas[j], &bp) != 0)
+				goto pass1_fail;
+			memcpy(dimap, bp->b_data, bsize);
+			brelse(bp);
+			for (ino = 0; ino < epb; ino++) {
+				lba = letoh64(dimap[ino]);
+				if (lba == 0)
+					continue;
+				if (zlfs_gc_mark_inode(zmp, lba) != 0)
+					goto pass1_fail;
 			}
 		}
 		free(dimap, M_TEMP, bsize);
+		free(lbas, M_TEMP, nblocks * sizeof(u_int64_t));
+		goto pass1_done;
+pass1_fail:
+		free(dimap, M_TEMP, bsize);
+		free(lbas, M_TEMP, nblocks * sizeof(u_int64_t));
+		return;
 	}
+pass1_done:
 
 	/* Pass 2: the in-core live set, through zm_imap. */
 	for (ino = 0; ino < zmp->zm_ninodes; ino++) {
@@ -297,7 +328,16 @@ zlfs_clean(struct zlfs_mount *zmp)
 			continue;		/* best effort */
 		zst->zst_wp_lba = zst->zst_start_lba;
 		zst->zst_cond = DK_ZONE_COND_EMPTY;
+		nreset++;
 	}
+
+	/*
+	 * Cached buffers for the reset zones would serve stale contents
+	 * once their LBAs are reused; drop the device's cache before the
+	 * allocator can hand them out again.
+	 */
+	if (nreset > 0)
+		zlfs_cache_purge_dev(zmp);
 }
 
 /*
@@ -378,7 +418,8 @@ zlfs_log_init(struct zlfs_mount *zmp, const struct dk_zone *sbz)
 	 * an empty full-block map with only the reserved inodes.
 	 */
 	if (zmp->zm_imap == NULL) {
-		zmp->zm_imap = malloc(zmp->zm_super.zs_block_size, M_ZLFS,
+		zmp->zm_imap_alloc = zmp->zm_super.zs_block_size;
+		zmp->zm_imap = malloc(zmp->zm_imap_alloc, M_ZLFS,
 		    M_WAITOK | M_ZERO);
 		zmp->zm_ninodes = ZLFS_FIRST_INO;
 	}