tiny.machine.checkpoint.hot

1/// The capacity fixes how much storage a caller supplies for a capped number of2/// changed pages. The byte counts cover one two-byte index and one aligned3/// 4096-byte page for each slot.4pub const Capacity = struct {5    pages: u16,6    index_storage_bytes: u32,7    page_storage_bytes: u32,89    /// The function derives the exact byte counts for `pages` slots. A count10    /// above 16,384 returns `DeltaCapacityExceeded`.11    pub fn derive(pages: usize) error{DeltaCapacityExceeded}!Capacity {12        if (pages > page_count) return error.DeltaCapacityExceeded;13        const index_storage_bytes = std.math.mul(14            usize,15            pages,16            @sizeOf(u16),17        ) catch return error.DeltaCapacityExceeded;18        const page_storage_bytes = std.math.mul(19            usize,20            pages,21            page_bytes,22        ) catch return error.DeltaCapacityExceeded;23        return .{24            .pages = @intCast(pages),25            .index_storage_bytes = @intCast(index_storage_bytes),26            .page_storage_bytes = @intCast(page_storage_bytes),27        };28    }29};

1/// The record holds the restore result from a snapshot. The `copied_pages`2/// field counts the changed pages written into the caller-owned destination3/// memory.4pub const Materialized = struct {5    material: checkpoint.Material,6    copied_pages: u16,7};

1/// The snapshot holds a changed-page checkpoint borrowing a durable parent and2/// the captured storage. The caller preserves the parent, the indices, and the3/// page bytes for the snapshot's lifetime.4pub const Snapshot = struct {5    parent: *const checkpoint.Checkpoint,6    identity_value: checkpoint.Identity,7    memory: checkpoint.MemoryDigest,8    material: checkpoint.Material,9    indices: []const u16,10    pages: []align(page_bytes) const u8,1112    /// The function reports how many ordered changed pages the snapshot holds.13    /// A caller uses this count to size a report or a later publication.14    pub fn dirtyPageCount(self: *const @This()) u16 {15        std.debug.assert(self.indices.len <= page_count);16        return @intCast(self.indices.len);17    }1819    /// The function revalidates the parent, the changed pages, the memory20    /// digest, and the stored identity. A recomputed value differing from the21    /// stored one returns `CheckpointCorrupt`.22    pub fn identity(self: *const @This()) checkpoint.DurableError!checkpoint.Identity {23        return (try inspect(self)).identity;24    }2526    fn inspect(self: *const @This()) checkpoint.DurableError!Inspection {27        const parent_contents = try checkpoint.inspect(self.parent);28        try checkpoint.validateParent(self.material, parent_contents.material);29        try checkpoint.validateDeltaImage(30            self.indices,31            self.material.immutable_image,32        );33        const memory = try checkpoint.deltaDigest(34            self.parent.ram,35            self.indices,36            self.pages,37        );38        if (!std.meta.eql(memory, self.memory)) {39            return error.CheckpointCorrupt;40        }41        const actual = try checkpoint.identify(self.material, memory);42        if (!std.meta.eql(actual, self.identity_value)) {43            return error.CheckpointCorrupt;44        }45        return .{ .parent = parent_contents, .identity = actual };46    }4748    /// The function returns the fully verified child checkpoint root.49    pub fn root(self: *const @This()) checkpoint.DurableError!checkpoint.Root {50        return (try self.identity()).root;51    }5253    /// The function verifies `expected` and requires the destination to already54    /// hold the parent memory image. The snapshot storage and the destination55    /// memory must be disjoint. The call returns the verified identity.56    pub fn prepareForRestore(57        self: *const @This(),58        expected: checkpoint.Root,59        destination: []align(page_bytes) const u8,60    ) Error!checkpoint.Identity {61        const inspection = try inspect(self);62        if (!std.meta.eql(inspection.identity.root, expected)) {63            return error.CheckpointRootMismatch;64        }65        try validateDestinationAgainst(self, destination, inspection.parent);66        return inspection.identity;67    }6869    /// The function overlays the changed pages on authenticated parent memory,70    /// then verifies the child memory digest. The call returns the material and71    /// the number of copied pages. Pages already copied stay in the destination72    /// when the closing digest check fails.73    pub fn materializeForRestore(74        self: *const @This(),75        expected: checkpoint.Root,76        destination: []align(page_bytes) u8,77    ) Error!Materialized {78        const inspection = try inspect(self);79        if (!std.meta.eql(inspection.identity.root, expected)) {80            return error.CheckpointRootMismatch;81        }82        try validateDestinationAgainst(self, destination, inspection.parent);83        for (self.indices, 0..) |page_index, index| {84            const start = @as(usize, page_index) * page_bytes;85            const source = self.pages[index * page_bytes ..][0..page_bytes];86            @memcpy(destination[start..][0..page_bytes], source);87        }88        const restored = try checkpoint.validatedMemoryDigest(89            destination,90            self.material.immutable_image,91        );92        if (!std.meta.eql(restored, self.memory)) {93            return error.MemoryDigestMismatch;94        }95        return .{96            .material = self.material,97            .copied_pages = self.dirtyPageCount(),98        };99    }100101    /// The function returns the durable parent's complete normalized memory.102    pub fn evidenceRam(103        self: *const @This(),104    ) []align(page_bytes) const u8 {105        return self.parent.ram;106    }107108    /// The function answers whether a byte range touches the snapshot value,109    /// the parent handle, the storage and memory behind that parent, or the110    /// captured index and page arrays.111    pub fn aliases(self: *const @This(), bytes: []const u8) bool {112        return buffersOverlap(bytes, std.mem.asBytes(self)) or113            buffersOverlap(bytes, std.mem.asBytes(self.parent)) or114            buffersOverlap(bytes, &self.parent.storage.bytes) or115            buffersOverlap(bytes, self.parent.ram) or116            buffersOverlap(bytes, std.mem.sliceAsBytes(self.indices)) or117            buffersOverlap(bytes, self.pages);118    }119};

1/// The storage holds the caller-owned output arrays for one changed-page2/// capture. The value borrows both slices. The caller keeps their addresses and3/// captured prefixes unchanged for as long as a snapshot can be used.4pub const Storage = struct {5    capacity: Capacity,6    indices: []u16,7    pages: []align(page_bytes) u8,89    /// The function joins an index slice and a page slice that carry the same10    /// number of slots. Every index slot has one aligned page behind it in the11    /// page storage. More than 16,384 indices returns `DeltaCapacityExceeded`.12    /// Any other page-storage length returns `DeltaStorageMismatch`.13    pub fn init(14        indices: []u16,15        pages: []align(page_bytes) u8,16    ) Error!Storage {17        const capacity = try Capacity.derive(indices.len);18        if (pages.len != capacity.page_storage_bytes) {19            return error.DeltaStorageMismatch;20        }21        return .{22            .capacity = capacity,23            .indices = indices,24            .pages = pages,25        };26    }27};

1pub const page_count: usize = core.layout.ram_bytes / page_bytes;

1/// The error set combines the failures of a durable checkpoint with destination2/// aliasing for a snapshot.3pub const Error = checkpoint.DurableError || HotError;

1/// The function captures ordered changed pages from live memory against a2/// durable parent. The material must share the parent's profile fingerprint,3/// immutable image descriptor, and execution fingerprint. The supplied storage4/// bounds the captured page count, and exceeding it returns5/// `DeltaCapacityExceeded`. Failures before the identity is built leave both6/// arrays unchanged, and rejection of the identity can leave both arrays7/// changed. On success the returned snapshot holds borrowed references to the8/// parent and to both output arrays.9pub fn capture(10    parent: *const checkpoint.Checkpoint,11    material: checkpoint.Material,12    current: []align(page_bytes) const u8,13    storage: Storage,14) Error!Snapshot {15    const parent_contents = try checkpoint.inspect(parent);16    try checkpoint.validateParent(material, parent_contents.material);17    try validateStorage(storage);18    try validateStorageAliases(parent, storage);19    const delta = try checkpoint.captureDelta(20        parent.ram,21        current,22        material.immutable_image,23        storage.indices,24        storage.pages,25    );26    const count: usize = delta.page_count;27    const identity_value = try checkpoint.identify(material, delta.memory);28    return .{29        .parent = parent,30        .identity_value = identity_value,31        .memory = delta.memory,32        .material = material,33        .indices = storage.indices[0..count],34        .pages = storage.pages[0 .. count * page_bytes],35    };36}

1pub const maximum_capacity = Capacity.derive(page_count) catch unreachable;

1//! Recording a running machine often costs too much when every capture copies2//! and hashes all 67,108,864 bytes, because an execution changes only a small3//! part of that data between two captures. The machine's fixed 67,108,8644//! bytes, addressed from zero, holding 16,384 pages, are its *memory*. A memory5//! image whose page tables have been rewritten to their canonical form and6//! whose boot frame, request ring, event ring, and kernel stack are zeroed is7//! *normalized memory*. A checkpoint holding a complete normalized memory image8//! in two caller-owned regions is a *durable checkpoint*. A block of 40969//! contiguous bytes of memory, named by its zero-based index, is a *page*. The10//! calls here record only the pages that differ from a durable checkpoint11//! already written down. A page whose bytes differ from the parent image's page12//! at the same index is a *changed page*. Changed pages recorded as strictly13//! ascending indices with one matching 4096-byte page record per index are14//! *ordered changed pages*. A checkpoint holding ordered changed pages against15//! a durable parent is a *hot snapshot*.16//!17//! A partial record is worth having only when it still yields the name the full18//! image would carry. This code takes from no outside source: it takes its19//! digests from the sibling digest schema inside this package. The complete20//! binary tree over the 16,384 page digests, 14 levels deep, is the *page21//! tree*. The SHA-256 identity of a normalized memory image, binding the page22//! tree's root to the fixed memory geometry, is the *memory digest*. Folding23//! the changed pages into the same page tree produces the same memory digest as24//! the full image.25//!26//! A snapshot borrows its parent handle and two caller-owned arrays, one for27//! ordered page indices and one for the matching page bytes. The caller's array28//! length fixes how many changed pages fit, and a capture that would exceed it29//! leaves both arrays unchanged.30//!31//! The memory image of a running machine, before normalization, is its *live32//! memory*. Capture checks the parent relationship and the live memory before33//! it writes anything into those arrays.34//!35//! A page table, boot frame, request ring, event ring, or stack page, which a36//! capture takes from the parent, is a *retained page*. Page tables, the boot37//! frame, the transport rings, and the stack keep their parent bytes, so38//! per-run state never enters a snapshot as a changed page.39//!40//! Restore starts from the parent's memory already present in the destination,41//! and the snapshot requires that memory to hash to the parent's memory digest42//! before it writes anything.43//!44//! Restore then lays each changed page over that memory and hashes the result,45//! comparing it with the memory digest the snapshot recorded.4647const owner = @import("owner.zig");4849pub const Error = owner.Error;50pub const Capacity = owner.Capacity;51pub const Materialized = owner.Materialized;52pub const Snapshot = owner.Snapshot;53pub const Storage = owner.Storage;54pub const capture = owner.capture;55pub const maximum_capacity = owner.maximum_capacity;56pub const page_bytes = owner.page_bytes;57pub const page_count = owner.page_count;

1pub const hot = @import("hot/root.zig");