nexoniarz/SchOS
nexoniarz/SchOS
Watch
1
0
Fork
You've already forked SchOS
 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

schfs: snapshots

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Nexoniarz 2026-08-10 19:10:24 +02:00
commit 6e2e9e8d05
6 changed files with 333 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

17
kernel/fs/schfs/obj.c
View file

@ -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 */
/* ------------------------------------------------------------------ */

70
kernel/fs/schfs/objw.c
View file

@ -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)
{

11
kernel/fs/schfs/schfs_int.h
View file

@ -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

108
kernel/fs/schfs/space.c
View file

@ -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;
}