tiny.machine.checkpoint.stream

1/// Draws exactly one stream from the reader into empty storage and page-aligned2/// memory that the caller owns. The reader and its buffer sit outside both3/// destinations. Framing, trailing data, a root mismatch, or failed4/// authentication aborts the publication. An abort returns the claimed storage5/// to empty, so the caller can try again with the same storage. The destination6/// memory can hold received bytes after a failure. Success returns a handle7/// borrowing the caller's storage and memory.8pub fn decodeDisjoint(9    reader: *std.Io.Reader,10    expected_root: owner.Root,11    storage: *owner.Storage,12    ram: []align(owner.ram_alignment) u8,13) Error!owner.Checkpoint {14    try validateSource(reader, storage, ram);15    var header_bytes_buffer: [header_bytes]u8 = undefined;16    try readExact(reader, &header_bytes_buffer);17    const decoded = try decode.header(&header_bytes_buffer, expected_root);18    var materialization = try owner.beginMaterialization(storage, ram);19    errdefer owner.abortMaterialization(&materialization);20    try readExact(reader, ram);21    var trailing: [1]u8 = undefined;22    if (try reader.readSliceShort(&trailing) != 0) return error.TrailingData;23    return owner.publishMaterialized(24        &materialization,25        decoded.material,26        expected_root,27        decoded.memory,28    );29}

1/// Checks the durable checkpoint first, then emits a header and the whole2/// normalized memory behind it. The writer and its buffer sit outside the3/// checkpoint handle, the storage behind it, and its memory. When input or4/// output fails partway, the bytes already handed to the writer stay there.5pub fn encodeDisjoint(6    checkpoint: *const owner.Checkpoint,7    writer: *std.Io.Writer,8) Error!void {9    try validateSink(checkpoint, writer);10    const contents = try owner.inspect(checkpoint);11    var header_bytes_buffer: [header_bytes]u8 = undefined;12    encode.header(contents, &header_bytes_buffer);13    try writer.writeAll(&header_bytes_buffer);14    try writer.writeAll(checkpoint.ram);15}

1/// Decodes one fixed 4096-byte header under `expected_root`. The function2/// validates the framing, the reserved ranges, the root fields, and the settled3/// receipt. A decoded root other than `expected_root` returns4/// `CheckpointRootMismatch`. The call returns the material and a memory digest,5/// which the caller authenticates against the memory bytes that follow.6pub fn header(7    input: *const [schema.header_bytes]u8,8    expected_root: owner.Root,9) stream_types.Error!stream_types.Decoded {10    try validateEnvelope(input);11    try validateReserved(input);12    const root_value = try decodeRoot(input);13    if (!std.meta.eql(root_value, expected_root)) {14        return error.CheckpointRootMismatch;15    }16    const memory: owner.MemoryDigest = .{17        .digest = digest(input, schema.MemoryLayout.digest_offset),18    };19    try validateDigest(memory.digest);20    const receipt = try decodeSemantic(input);21    const cpu = decodeCpu(input);22    return .{23        .material = .{24            .profile = root_value.profile,25            .receipt = receipt,26            .cpu = cpu,27            .immutable_image = decodeImmutable(input, cpu),28        },29        .memory = memory,30    };31}

1/// Encodes authenticated checkpoint metadata into one fixed 4096-byte header.2/// Callers supply the `Contents` that checkpoint inspection returned. The call3/// starts from a zero-filled buffer, so every unused byte and every reserved4/// range is zero. The function writes the envelope, the checkpoint root and5/// memory digest, the settled receipt, the CPU restart frame, and the immutable6/// image descriptor.7pub fn header(8    contents: owner.Contents,9    output: *[schema.header_bytes]u8,10) void {11    var encoded: [schema.header_bytes]u8 = @splat(0);12    encodeEnvelope(&encoded);13    encodeRoot(contents, &encoded);14    encodeSemantic(contents.material.receipt, &encoded);15    encodeCpu(contents.material.cpu, &encoded);16    encodeImmutable(contents.material.immutable_image, &encoded);17    output.* = encoded;18}

1pub const encoded_stream_bytes: u64 = 67_112_960;

1pub const page_bytes: u32 = 4096;

1/// The error set covers the framing, identity, alias, storage, and input-output2/// failures of a checkpoint stream. The set includes the reader and writer3/// failures of the standard input-output interfaces and every durable4/// checkpoint failure.5pub const Error = error{6    AbiVersionMismatch,7    BadMagic,8    CheckpointFormatMismatch,9    HeaderBytesMismatch,10    MetadataShapeMismatch,11    PageBytesMismatch,12    ReservedNonzero,13    SinkAliasesCheckpoint,14    SourceAliasesDestination,15    StreamBytesMismatch,16    TrailingData,17    TruncatedStream,18    UnsupportedFlags,19    UnsupportedVersion,20} || std.Io.Reader.ShortError || std.Io.Writer.Error || owner.Error;

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

1//! Moving a machine capture between processes, files, and hosts requires2//! turning that capture into bytes. 4096 contiguous bytes of a machine's3//! memory, named by its zero-based index, form a *page*. The machine's fixed4//! 67,108,864 bytes, addressed from zero and holding 16,384 pages, form its5//! *memory*. A memory image whose page tables have been rewritten to their6//! canonical form and whose boot frame, request ring, event ring, and kernel7//! stack are zeroed is *normalized memory*. A checkpoint holding a complete8//! normalized memory image in two caller-owned regions is a *durable9//! checkpoint*. The calls here write one complete durable checkpoint as bytes10//! and read one back. The fixed 67,112,960-byte encoding of one durable11//! checkpoint, formed by 4096 leading bytes followed by all normalized memory,12//! is the *checkpoint stream*. The stream's first 4096 bytes form the *header*.13//!14//! The digest binding one profile fingerprint to one state digest is the15//! *checkpoint root*. The SHA-256 identity of a normalized memory image is the16//! *memory digest*. The record of a stopped machine boundary with activation17//! authority removed, so one guest state keeps one identity across runs, is the18//! *settled receipt*. The ten register values a restarted machine begins with19//! form the *CPU restart frame*. The kernel image's digest, the initial CPU20//! state it admits, its entry offset, and up to four load ranges placing image21//! bytes in memory form the *immutable image descriptor*. Header byte ranges22//! the writer fills with zero and the reader requires to be zero are the23//! *reserved bytes*. The header encodes the checkpoint root, the memory digest,24//! the settled receipt, the CPU restart frame, and the immutable image25//! descriptor in little-endian fields.26//!27//! A capture arriving as bytes comes from outside the reader's control, so28//! every field it carries has to be checked before the capture is used. Two29//! builds have to agree on the layout down to the byte, so the header states30//! its own field widths and the reader compares each one.31//!32//! The caller-owned metadata region holding a publication status and the33//! authenticated metadata behind it is the *checkpoint storage*. A reader that34//! claimed the caller's storage and then failed would leave that storage35//! unusable.36//!37//! Encoding verifies the checkpoint before it writes a byte.38//!39//! Decoding rejects a wrong magic value, version, header size, flag word,40//! format, stream or memory byte count, page size, interface version, or field41//! width. Decoding requires every reserved range to be zero. Decoding requires42//! the header's checkpoint root to equal the root the caller expected, and it43//! reads that root before the memory bytes arrive. Decoding rejects a stream44//! that ends early and a stream with bytes after the memory image. The45//! fixed-size values needed to recompute an identity and rebuild execution:46//! profile fingerprint, settled receipt, CPU restart frame, and immutable image47//! descriptor, are the *material*. Decoding rejects material that fails its own48//! verification, so a settled receipt that does not check out returns49//! `CheckpointCorrupt`. Decoding rejects a reader whose object or buffer50//! overlaps either destination.51//!52//! A publication claim held open while another source fills the memory,53//! published only after the filled bytes authenticate, is a *materialization*.54//! Decoding conducts that materialization across the caller's checkpoint55//! storage and memory region, authenticating the bytes against the header's56//! memory digest and checkpoint root. A failure after the claim aborts it and57//! returns the storage to empty.5859const codec = @import("codec.zig");60const decode = @import("decode.zig");61const encode = @import("encode.zig");6263pub const Error = codec.Error;64pub const decodeHeader = decode.header;65pub const decodeDisjoint = codec.decodeDisjoint;66pub const encodeHeader = encode.header;67pub const encodeDisjoint = codec.encodeDisjoint;68pub const header_bytes = codec.header_bytes;69pub const stream_bytes = codec.stream_bytes;