From 6e2e9e8d052ee875e8934b37316e9f64a21a2698 Mon Sep 17 00:00:00 2001 From: Nexoniarz Date: Mon, 10 Aug 2026 19:10:24 +0200 Subject: [PATCH] schfs: snapshots A snapshot is a tree root that is kept. The B-tree is copy-on-write, so the blocks a committed root reaches are already immutable -- nothing overwrites a block a committed tree can reach -- and retaining one costs a record: (SNAP_OBJECTID, KEY_SNAP, id) -> struct schfs_snap. The record names the root as it was *before* the record was added. Inserting it rewrites the path under copy-on-write and produces a new root, so a snapshot that included its own creation would name a block nobody had written yet. What makes it survive is the derivation. There is no free-space map on disk; it is rebuilt at mount by walking the tree, and that walk now covers every snapshot root as well as the live one. Without it a block reachable only from a snapshot looks free, gets handed out, and overwrites the data the snapshot exists to keep -- silently, surfacing only when the snapshot is read. A snapshot's own tree may hold older snapshot records; those are deliberately not followed, or deleting a snapshot could be undone by an older one's memory of it. Runtime frees are suspended while a snapshot exists. Knowing which freed blocks a snapshot still needs requires per-extent reference counting, which is a design and not a flag; until that exists the safe answer is to free nothing and let the next mount's derivation reclaim what is genuinely unreachable. Allocation is unaffected and stays correct -- it works from the in-use bitmap the derivation filled. The running free-blocks *counter* does drift from the truth while a snapshot is present, which is cosmetic and is reported by the test rather than asserted away. Tested in schfs_objtest: after a snapshot, the live tree shows new contents while the snapshot still shows the old ones; a file deleted from the live tree is still readable through the snapshot; deleting the snapshot removes the record and the space comes back at the next mount. schfs-check passes including the round-trip; bootcheck 108 [ok]. Not yet: snapshots are not reachable by name from userspace -- there is no mount-a-snapshot path, so this is the format and the mechanism, not the feature a user sees. Co-Authored-By: Claude Opus 5 --- include/schfs.h | 32 +++++++++++ kernel/fs/schfs/obj.c | 17 ++++++ kernel/fs/schfs/objw.c | 70 +++++++++++++++++++++++ kernel/fs/schfs/schfs_int.h | 11 ++++ kernel/fs/schfs/space.c | 108 ++++++++++++++++++++++++++++++++++-- tools/schfs_objtest.c | 100 +++++++++++++++++++++++++++++++++ 6 files changed, 333 insertions(+), 5 deletions(-) diff --git a/include/schfs.h b/include/schfs.h index ffe44d7..549f924 100644 --- a/include/schfs.h +++ b/include/schfs.h @@ -39,6 +39,7 @@ #define SCHFS_KEY_ATTR 4 // (ino, ATTR, namehash) -> attribute value #define SCHFS_KEY_INDEX 5 // (idxid, INDEX, valuehash) -> objectid #define SCHFS_KEY_CSUM 6 // (CSUM, CSUM, diskblk) -> uint32 CRC32c +#define SCHFS_KEY_SNAP 7 // (SNAP, SNAP, id) -> struct schfs_snap // Data-block checksums live under one reserved object id, exactly as btrfs // keeps a checksum tree. Tree nodes carry their checksum in their parent @@ -46,6 +47,11 @@ // records "end-to-end checksums" would only cover metadata, which is the part // least likely to rot. #define SCHFS_CSUM_OBJECTID 1ULL +// Snapshots live under their own reserved objectid, as ordinary records in the +// live tree. A snapshot is nothing more than a tree root that is kept: the +// B-tree is copy-on-write, so the blocks a root reaches are already immutable +// as long as nothing frees them. Keeping one costs a record. +#define SCHFS_SNAP_OBJECTID 2ULL // Object ids below this are reserved; the root directory is the first real one. #define SCHFS_FIRST_OBJECTID 16ULL @@ -122,6 +128,32 @@ struct schfs_item { #define SCHFS_VERSION 1 #define SCHFS_LABEL_MAX 32 +// A retained tree root. +// +// The root a snapshot names is a *previous* version of the live tree, and it is +// reached exactly as the live one is -- same node format, same checksums. What +// makes it survive is schfs_space_scan walking it too, so its blocks are never +// handed out again. +// +// The record is stored in the live tree, which means creating one rewrites the +// path to it under copy-on-write and produces a new live root. That is correct +// and is why the snapshot names the root as it was *before* the record was +// added: a snapshot that included its own creation would have to refer to a +// block that does not exist yet. +#define SCHFS_SNAP_NAME_MAX 64 + +// Set on a volume that has at least one snapshot. See schfs_space_free. +#define SCHFS_SPACE_RETAIN_ALL 1 + +struct schfs_snap { + uint64_t root; // block number of the retained tree root + uint64_t root_generation; + uint32_t root_crc; // checksum of that root block + uint32_t pad0; + uint64_t created; // generation the snapshot was taken at + char name[SCHFS_SNAP_NAME_MAX]; +}; + struct schfs_uberblock { uint32_t magic; // SCHFS_MAGIC uint32_t crc; // CRC32c of this struct, this field zeroed diff --git a/kernel/fs/schfs/obj.c b/kernel/fs/schfs/obj.c index 1fa45b1..e6c15a7 100644 --- a/kernel/fs/schfs/obj.c +++ b/kernel/fs/schfs/obj.c @@ -138,6 +138,23 @@ schfs_inode_get(struct schfs_vol *v, struct schfs_cursor *c, return 0; } +int +schfs_snap_get(struct schfs_vol *v, struct schfs_cursor *c, uint64_t id, + struct schfs_snap *out) +{ + struct schfs_key k; + schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id); + + cur_bind(c, v); + unsigned len = sizeof(*out); + int r = schfs_btree_lookup_cur(c, &k, out, &len); + if (r != 0) + return r; + if (len != sizeof(*out)) + return -2; + return 0; +} + /* ------------------------------------------------------------------ */ /* Directories */ /* ------------------------------------------------------------------ */ diff --git a/kernel/fs/schfs/objw.c b/kernel/fs/schfs/objw.c index 4a34545..26f5d71 100644 --- a/kernel/fs/schfs/objw.c +++ b/kernel/fs/schfs/objw.c @@ -42,6 +42,76 @@ schfs_alloc_objectid(struct schfs_vol *v) return v->next_objectid++; } +/* ------------------------------------------------------------------ */ +/* Snapshots */ +/* */ +/* A snapshot is a tree root that is kept. Copy-on-write means the */ +/* blocks that root reaches are already immutable -- nothing overwrites */ +/* a block a committed tree can reach -- so retaining one costs a */ +/* record, and keeping it alive is entirely schfs_space_scan's job. */ +/* ------------------------------------------------------------------ */ + +// Take a snapshot of the volume as it is committed *now*. +// +// The root recorded is the one in v->tree before this call, which is the +// committed state. It cannot be the root this call produces: adding the record +// rewrites the path to it under copy-on-write, so that root does not exist +// until afterwards, and a snapshot naming it would name a block nobody had +// written yet. +// +// The caller commits. Until it does, the record is not on disk and the +// snapshot does not exist -- which is the correct failure mode, because a +// snapshot that survived a crash while the tree it names did not would be a +// dangling root. +int +schfs_snap_create(struct schfs_vol *v, uint64_t id, const char *name, + unsigned namelen) +{ + schfs_cache_invalidate(); + + if (namelen >= SCHFS_SNAP_NAME_MAX) + return -1; + + struct schfs_snap sn; + memset(&sn, 0, sizeof sn); + sn.root = v->tree.root; + sn.root_crc = v->tree.root_crc; + sn.root_generation = v->tree.root_gen; + sn.created = v->tree.generation; + for (unsigned i = 0; i < namelen; i++) + sn.name[i] = name[i]; + + struct schfs_key k; + schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id); + int r = schfs_btree_insert(&v->tree, &v->ctx, &k, &sn, sizeof sn); + if (r == 0) + v->space.flags |= SCHFS_SPACE_RETAIN_ALL; + return r; +} + +// Forget a snapshot. The blocks it was holding are not freed here: they stop +// being reachable, and the next derivation at mount simply does not mark them. +// That is the whole deletion -- there is no reference count to decrement, +// because there never was one. +int +schfs_snap_delete(struct schfs_vol *v, uint64_t id) +{ + schfs_cache_invalidate(); + struct schfs_key k; + schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id); + int r = schfs_btree_delete(&v->tree, &v->ctx, &k); + if (r != 0) + return r; + + // Stop retaining. If other snapshots remain, the next mount's derivation + // sets the flag again -- it is the walk that knows, not this function, and + // guessing here would mean keeping a second count to disagree with it. + // Until that mount the allocator is merely conservative, which is the safe + // direction. + v->space.flags &= ~(unsigned)SCHFS_SPACE_RETAIN_ALL; + return 0; +} + int schfs_inode_put(struct schfs_vol *v, uint64_t ino, const struct schfs_inode *in) { diff --git a/kernel/fs/schfs/schfs_int.h b/kernel/fs/schfs/schfs_int.h index 985f8a0..7809a54 100644 --- a/kernel/fs/schfs/schfs_int.h +++ b/kernel/fs/schfs/schfs_int.h @@ -43,6 +43,8 @@ struct schfs_space { uint64_t free_blocks; uint64_t pending; // bits set in pend[], counted uint64_t hint; // rotating search start + // SCHFS_SPACE_RETAIN_ALL while a snapshot exists -- see schfs_space_free. + unsigned flags; }; // A mounted (or under-construction) volume. @@ -109,6 +111,15 @@ int schfs_vol_format(struct schfs_vol *v, struct schfs_bdev *dev, // discards it — which is exactly what makes the format crash-safe. int schfs_vol_commit(struct schfs_vol *v); +// Snapshots. Create records the *committed* root; the caller commits after. +// Lookup fills `out` for a given id. Deleting forgets the record, and the next +// derivation stops marking what only it reached. +int schfs_snap_create(struct schfs_vol *v, uint64_t id, const char *name, + unsigned namelen); +int schfs_snap_delete(struct schfs_vol *v, uint64_t id); +int schfs_snap_get(struct schfs_vol *v, struct schfs_cursor *c, uint64_t id, + struct schfs_snap *out); + // Block allocation. Returns 0 when the volume is full. // // Not themselves schfs_bdev callbacks: a bdev has one ctx shared by all of its diff --git a/kernel/fs/schfs/space.c b/kernel/fs/schfs/space.c index eea86f2..f2d341d 100644 --- a/kernel/fs/schfs/space.c +++ b/kernel/fs/schfs/space.c @@ -207,6 +207,23 @@ schfs_space_alloc(struct schfs_space *s) void schfs_space_free(struct schfs_space *s, uint64_t blk) { + // A snapshot exists, so this block may still be reachable from it. + // + // Copy-on-write frees the old block whenever one is rewritten, and that is + // exactly the block a snapshot is holding. Freeing it would hand it out + // again and overwrite the data the snapshot exists to keep -- silently, + // with the damage only visible later when the snapshot is read. + // + // Knowing *which* freed blocks a snapshot still needs requires reference + // counting per extent, which is a real design and not a flag. Until that + // exists, the safe answer is to free nothing while a snapshot is present: + // the free map is derived at mount anyway, so everything genuinely + // unreachable is reclaimed on the next mount rather than lost. Conservative + // in the only direction that is safe -- it can under-report free space, and + // can never hand out a block that is still in use. + if (s->flags & SCHFS_SPACE_RETAIN_ALL) + return; + if (blk < SCHFS_FIRST_BLOCK || blk >= s->nblocks) return; if (!bit_test(s->inuse, blk)) @@ -261,6 +278,42 @@ mark_leaf_extents(struct schfs_space *s, const void *blk) } } +// Snapshot roots found while walking, so they can be walked in turn. +// +// Collected rather than descended into immediately: the walk keeps one block +// buffer and a path, and re-entering it from inside itself would need a second +// of each. +#define SNAP_ROOTS_MAX 64 + +struct snap_roots { + int n; + int overflow; + uint64_t nr[SNAP_ROOTS_MAX]; + uint32_t crc[SNAP_ROOTS_MAX]; +}; + +static void +collect_snap_roots(struct snap_roots *sr, const void *blk) +{ + const struct schfs_item *it = SCHFS_ITEMS(blk); + int n = SCHFS_HDR(blk)->nritems; + + for (int i = 0; i < n; i++) { + if (it[i].key.type != SCHFS_KEY_SNAP) + continue; + if (it[i].size != sizeof(struct schfs_snap)) + continue; + if ((int)it[i].offset + (int)it[i].size > SCHFS_BLKSIZE) + continue; + const struct schfs_snap *sn = + (const struct schfs_snap *)((const char *)blk + it[i].offset); + if (sr->n >= SNAP_ROOTS_MAX) { sr->overflow = 1; continue; } + sr->nr[sr->n] = sn->root; + sr->crc[sr->n] = sn->root_crc; + sr->n++; + } +} + // Walk the whole tree, marking every block it reaches. // // Iterative, with one block buffer and a path of block numbers, for the same @@ -268,8 +321,11 @@ mark_leaf_extents(struct schfs_space *s, const void *blk) // the kernel stack is one block in total. Climbing re-reads the parent, so an // internal node is read once per child — mount-time cost that the buffer cache // largely absorbs, in exchange for bounded memory. -int -schfs_space_scan(struct schfs_vol *v) +// Walk one root, marking everything it reaches. Snapshot records encountered +// on the way are collected into `sr` when it is non-null. +static int +scan_root(struct schfs_vol *v, uint64_t root, uint32_t root_crc, + struct snap_roots *sr) { struct schfs_space *s = &v->space; void *blk = v->ctx.a; @@ -281,10 +337,10 @@ schfs_space_scan(struct schfs_vol *v) } path[SCHFS_MAX_LEVEL + 1]; int d = 0; - path[0].nr = v->tree.root; - path[0].crc = v->tree.root_crc; + path[0].nr = root; + path[0].crc = root_crc; path[0].idx = 0; - schfs_space_mark(s, v->tree.root, 1); + schfs_space_mark(s, root, 1); for (;;) { if (schfs_node_read(&v->dev, path[d].nr, path[d].crc, blk) != 0) @@ -292,6 +348,8 @@ schfs_space_scan(struct schfs_vol *v) if (SCHFS_HDR(blk)->level == 0) { mark_leaf_extents(s, blk); + if (sr) + collect_snap_roots(sr, blk); d--; } else if (path[d].idx < SCHFS_HDR(blk)->nritems) { struct schfs_kptr *kp = &SCHFS_KPTRS(blk)[path[d].idx]; @@ -312,3 +370,43 @@ schfs_space_scan(struct schfs_vol *v) return 0; } } + +// Walk the live tree, then every snapshot's tree. +// +// The snapshots have to be walked or the derivation is actively dangerous: a +// block reachable only from a snapshot would look free, be handed out, and +// overwrite the very data the snapshot exists to keep. Nothing would complain +// at the time -- the corruption surfaces later, when the snapshot is read. +// +// The live tree is walked first because that is where the snapshot records +// live; a snapshot's own tree may contain older snapshot records, which are +// deliberately not followed. They name roots the live tree no longer keeps, +// and a snapshot that was deleted should not be resurrected by an older +// snapshot's memory of it. +int +schfs_space_scan(struct schfs_vol *v) +{ + struct snap_roots sr; + sr.n = 0; + sr.overflow = 0; + + int r = scan_root(v, v->tree.root, v->tree.root_crc, &sr); + if (r != 0) + return r; + + if (sr.n > 0) + v->space.flags |= SCHFS_SPACE_RETAIN_ALL; + + for (int i = 0; i < sr.n; i++) { + r = scan_root(v, sr.nr[i], sr.crc[i], 0); + if (r != 0) + return r; + } + + // Refusing is the only safe answer. Carrying on would mean deriving a free + // map that considers a live snapshot's blocks available. + if (sr.overflow) + return -2; + + return 0; +} diff --git a/tools/schfs_objtest.c b/tools/schfs_objtest.c index 7ab1a5b..1f8c727 100644 --- a/tools/schfs_objtest.c +++ b/tools/schfs_objtest.c @@ -552,6 +552,106 @@ main(void) "the tree survives being filled to the brim"); } + /* ---- 8b. snapshots ---- */ + { + // A snapshot is only worth anything if the data it names survives the + // live tree changing underneath it. So: write, snapshot, overwrite, + // and then read *through the snapshot's root* and expect the old bytes. + int r; + uint64_t ino = mkfile(VOL.root_objectid, "snapfile"); + ok(ino != 0, "created a file to snapshot"); + + const char before[] = "BEFORE-THE-SNAPSHOT"; + schfs_file_write(&VOL, ino, 0, before, sizeof before, DATABLK); + if (schfs_vol_commit(&VOL) != 0) { printf(" FAIL: commit\n"); failures++; } + + // The snapshot names the committed root, which is the state just + // written -- not the root this call produces. + r = schfs_snap_create(&VOL, 1, "first", 5); + ok(r == 0, "took a snapshot"); + if (schfs_vol_commit(&VOL) != 0) { printf(" FAIL: commit\n"); failures++; } + + struct schfs_cursor c; + schfs_cursor_init(&c, &VOL.tree, CURBLK); + struct schfs_snap sn; + ok(schfs_snap_get(&VOL, &c, 1, &sn) == 0, "the snapshot record reads back"); + + // Change the live tree: overwrite the file completely. + const char after[] = "AFTER-THE-SNAPSHOT!"; + schfs_file_write(&VOL, ino, 0, after, sizeof after, DATABLK); + if (schfs_vol_commit(&VOL) != 0) { printf(" FAIL: commit\n"); failures++; } + + char buf[64]; + memset(buf, 0, sizeof buf); + schfs_cursor_init(&c, &VOL.tree, CURBLK); + schfs_file_read(&VOL, &c, ino, 0, buf, sizeof after, DATABLK); + ok(memcmp(buf, after, sizeof after) == 0, + "the live tree shows the new contents"); + + // Read through the retained root. Same volume, same block device, a + // tree pointed at the old root -- which is all a snapshot is. + struct schfs_vol snapvol = VOL; + snapvol.tree.root = sn.root; + snapvol.tree.root_crc = sn.root_crc; + snapvol.tree.root_gen = sn.root_generation; + + memset(buf, 0, sizeof buf); + schfs_cursor_init(&c, &snapvol.tree, CURBLK); + long got = schfs_file_read(&snapvol, &c, ino, 0, buf, sizeof before, DATABLK); + ok(got == (long)sizeof before && memcmp(buf, before, sizeof before) == 0, + "the snapshot still shows the OLD contents"); + if (memcmp(buf, before, sizeof before) != 0) + printf(" (snapshot read back \"%s\")\n", buf); + + // And the blocks it holds must not be considered free, or they get + // handed out and the snapshot rots silently. + // Exact agreement is not the invariant once a snapshot exists, and the + // number is the only thing that drifts. Allocation works from the + // in-use bitmap, which the derivation filled by walking the snapshot + // too, so a snapshot's blocks are never handed out. The running + // counter is not corrected for them, so it and the derivation disagree + // until the next mount. Cosmetic, and reported rather than asserted + // away. + uint64_t claimed = remount(); + if (claimed != VOL.free_blocks) + printf(" (note: counter %llu, derived %llu -- the counter " + "drifts while a snapshot exists)\n", + (unsigned long long)claimed, + (unsigned long long)VOL.free_blocks); + + // Deleting the file from the live tree must not disturb the snapshot. + schfs_dir_del(&VOL, VOL.root_objectid, "snapfile", 8); + schfs_object_free(&VOL, ino); + if (schfs_vol_commit(&VOL) != 0) { printf(" FAIL: commit\n"); failures++; } + + memset(buf, 0, sizeof buf); + snapvol = VOL; + snapvol.tree.root = sn.root; + snapvol.tree.root_crc = sn.root_crc; + snapvol.tree.root_gen = sn.root_generation; + schfs_cursor_init(&c, &snapvol.tree, CURBLK); + got = schfs_file_read(&snapvol, &c, ino, 0, buf, sizeof before, DATABLK); + ok(got == (long)sizeof before && memcmp(buf, before, sizeof before) == 0, + "a file deleted from the live tree is still in the snapshot"); + + // Drop it again, so what it was holding becomes reclaimable and the + // volume goes back to exact accounting for the checks that follow. + ok(schfs_snap_delete(&VOL, 1) == 0, "the snapshot can be deleted"); + if (schfs_vol_commit(&VOL) != 0) { printf(" FAIL: commit\n"); failures++; } + + schfs_cursor_init(&c, &VOL.tree, CURBLK); + ok(schfs_snap_get(&VOL, &c, 1, &sn) != 0, + "a deleted snapshot is gone"); + + // Deleting it makes what it held unreachable, and the derivation at + // the next mount is what reclaims it -- there is no refcount to + // decrement. So the derived figure must be at least what the stale + // counter believed; check 9 below then proves exact agreement is back. + claimed = remount(); + ok(VOL.free_blocks >= claimed, + "space the snapshot held is reclaimed at the next mount"); + } + /* ---- 9. the map and its counter still agree ---- */ { uint64_t claimed = remount();