tiny.machine.instance

1pub const AcknowledgeError = input_admission.Error ||2    os.abi.ring.Error || quiescence_receipt.Error || ProtocolError || OwnerError ||3    core.memory.Error;

1pub const BasisError = ProtocolError || os.abi.ring.Error || core.memory.Error;

1pub const CaptureCheckpointError = QuiescenceReceiptError || OwnerError ||2    checkpoint.Error || core.provenance.Error || layout.Error || core.memory.Error;

1pub const CaptureHotError = QuiescenceReceiptError || OwnerError ||2    checkpoint.Error || core.provenance.Error || layout.Error || core.memory.Error;

1pub const DeliveryError = input_admission.Error ||2    delivery.Error || os.abi.ring.Error || ProtocolError || core.memory.Error;

1pub const EventError = os.abi.message.Error ||2    os.abi.ring.Error || ProtocolError || OwnerError || core.memory.Error;

1pub const InitError = MachineError ||2    profile.Error ||3    image_admission.Error ||4    input_admission.Error ||5    os.abi.boot.Error ||6    os.abi.ring.Error ||7    layout.Error;

1pub const MemoryError = core.memory.Error || error{Closed};

1pub const QuiescenceReceiptError = os.abi.ring.Error ||2    quiescence_receipt.Error || QuiescenceProtocolError || core.memory.Error;

1pub const ReactivateError = os.abi.boot.Error ||2    os.abi.ring.Error || backend.RestartFailure || ProtocolError ||3    OwnerError || layout.Error;

1pub const RunError = backend.RunFailure || ProtocolError;

1/// Boots a guest with accelerator semantics through a caller-supplied callback,2/// so a backend harness can supply its own start callback while keeping the3/// rest of the path unchanged. The call answers with the same start outcome as4/// `init`.5pub fn initWithStart(6    storage: *Storage,7    ram: []align(layout.page_bytes) u8,8    input: types.Input,9    context: ?*anyopaque,10    start: backend.StartFunction,11) StartResult {12    return initSelected(13        storage,14        ram,15        input,16        .accelerator,17        context,18        start,19    );20}

1/// Restores a guest with accelerator semantics through a caller-supplied2/// callback, so a backend harness can substitute the backend acquire callback3/// during a restore. The checkpoint and the profile are checked first, and the4/// callback runs after.5pub fn restoreWithAcquire(6    storage: *Storage,7    ram: []align(layout.page_bytes) u8,8    input: types.RestoreInput,9    context: ?*anyopaque,10    acquire: backend.RestoreAcquireFunction,11) RestoreResult {12    return restoreSelected(13        storage,14        ram,15        input,16        .accelerator,17        context,18        acquire,19    );20}

1pub const run_stutter_limit: usize = 128;

1pub const storage_alignment: usize = @alignOf(OwnerState);

1pub const storage_bytes: usize = @sizeOf(OwnerState);

1/// Checks whether a direct restore would work and brings no backend up, so a2/// caller verifies the operation before committing resources to it. The storage3/// and the destination RAM are left as they were. When the restore would work,4/// the call reports the checkpoint identity it verified.5pub fn validateRestore(6    storage: *Storage,7    ram: []align(layout.page_bytes) u8,8    input: types.RestoreInput,9) RestoreError!checkpoint.Identity {10    const selected: BackendKind = switch (input.profile.backend) {11        .linux_kvm_single_vcpu_v1 => .accelerator,12        .portable_x86_64_interpreter_v1 => .reference,13    };14    return validateRestoreSelected(storage, ram, input, selected);15}

1/// Accepts exactly one byte count, the value of `storage_bytes`, so a caller2/// allocating storage knows the size is right before starting anything. Any3/// other count comes back as `StorageBytesMismatch`.4pub fn validateStorageBytes(bytes: usize) error{StorageBytesMismatch}!void {5    if (bytes != storage_bytes) return error.StorageBytesMismatch;6}

1/// Checking a batch can go wrong in more ways than checking a receipt, so this2/// error set reports the failures coming from decoding the bytes, matching the3/// fence, checking the receipt, bounding the count, or comparing the4/// transcript.5pub const EventBatchError = os.abi.message.Error ||6    os.abi.wire.FenceError ||7    Error ||8    EventBatchOwnerError;

1/// A checkpoint keeps the authority-free form, so the call checks the receipt2/// and copies out the form checkpoints work from.3pub fn projectSemantic(4    value: types.QuiescenceReceipt,5) Error!types.SemanticReceipt {6    try verify(value);7    return semanticReceipt(value);8}

1/// Naming a stored guest state takes its digest, so the call checks the value,2/// then hashes its canonical fields.3pub fn semanticReceiptDigest(4    value: types.SemanticReceipt,5) Error!os.abi.Digest {6    try validateSemantic(value);7    return semanticReceiptHash(value);8}

1/// A receipt binds itself to the events a turn produced, so the call hashes the2/// filled slots as raw bytes, together with how many there are and the order3/// they sit in. The count has to be at least one and no more than4/// `event_batch_max`, which the call asserts.5pub fn transcriptDigest(batch: *const types.EventBatch) os.abi.Digest {6    std.debug.assert(batch.count > 0);7    std.debug.assert(batch.count <= batch.storage.len);8    var hasher = Sha256.init(.{});9    hasher.update(transcript_domain);10    hashInteger(&hasher, batch.count);11    for (batch.frames()) |*frame| hasher.update(frame);12    var output: os.abi.Digest = undefined;13    hasher.final(&output);14    return output;15}

1/// The events a turn produced have to belong to that turn, so the call decodes2/// each filled slot and requires the handed-in fence on every encoded message3/// in the kernel wire form, or frame. A fence that fails its own check, a count4/// past the slots, or a frame that will not decode all come back as5/// `EventBatchError`.6pub fn verifyEventBatch(7    batch: *const types.EventBatch,8    expected_fence: os.abi.ActivationFence,9) EventBatchError!void {10    try os.abi.wire.validateFence(expected_fence);11    if (batch.count > batch.storage.len) {12        return error.EventBatchCountInvalid;13    }14    for (batch.storage[0..batch.count]) |*frame| {15        const decoded = try os.abi.decodeEvent(frame);16        if (!os.abi.wire.equalFence(decoded.header.fence, expected_fence)) {17            return error.EventBatchFenceMismatch;18        }19    }20}

1/// One call ties a batch, a receipt, and a fence together, so the call checks2/// the receipt against the fence, compares the batch's raw transcript digest3/// with the one the receipt carries, and then checks every frame.4pub fn verifyEventBatchReceipt(5    batch: *const types.EventBatch,6    value: types.QuiescenceReceipt,7    expected_fence: os.abi.ActivationFence,8) EventBatchError!void {9    try verifyForFence(value, expected_fence);10    if (batch.count == 0 or batch.count > batch.storage.len) {11        return error.EventBatchCountInvalid;12    }13    if (!std.mem.eql(14        u8,15        &transcriptDigest(batch),16        &value.event_transcript_digest,17    )) {18        return error.EventTranscriptMismatch;19    }20    try verifyEventBatch(batch, expected_fence);21}

1/// A valid receipt from some other turn is worse than none, so the call checks2/// the receipt and then requires its world, generation, and token to match the3/// ones handed in.4pub fn verifyForFence(5    value: types.QuiescenceReceipt,6    expected_fence: os.abi.ActivationFence,7) Error!void {8    try verify(value);9    if (!os.abi.wire.equalFence(value.fence, expected_fence)) {10        return error.InvalidQuiescenceReceipt;11    }12}

1/// A semantic receipt read back out of storage has to stand on its own, so the2/// call runs every invariant the authority-free form has. A value that3/// disagrees with itself comes back as `InvalidQuiescenceReceipt`.4pub fn verifySemantic(value: types.SemanticReceipt) Error!void {5    try validateSemantic(value);6}

1//! Two runs of one guest operating system from one starting state with one set2//! of inputs do the same work and land in the same place. This code boots one3//! small restricted kernel image, runs it inside the guest's RAM, and brings it4//! to rest at points where a caller can read the state out and copy it. The5//! guest's RAM is a fixed 67,108,864 bytes addressed from zero, which hold6//! 16,384 pages of 4096 bytes, each page at a 4096-aligned address and named by7//! its zero-based index. The host and the guest pass work to each other through8//! two message queues at fixed addresses in that RAM, one carrying requests and9//! one carrying events.10//!11//! A second run has to do what the first did, so nothing the host happens to be12//! doing may reach the guest. A caller needs a place to stop where no work is13//! in flight, because a stop like that is the only one worth copying and14//! resuming. Someone reading the bytes later has to be able to tell that one15//! stop happened under one stated authority with one stated input, with the16//! machine long gone. The caller owns the memory: this code takes the bytes17//! holding one run's whole state and the guest's RAM from the caller, and keeps18//! both at fixed addresses until the run is closed.19//!20//! Running a guest on real hardware lets the host show through, by way of21//! interrupts, timing, the processor's own identification, devices this design22//! does not model, and instructions that read a clock or a hardware random23//! source. An instruction whose answer comes from the host makes the second run24//! differ, and noticing once the guest is already running is too late to help.25//! Stopping wherever the instruction pointer happens to be leaves messages part26//! drained and work outstanding, so the guest has to pick the moment. A machine27//! with no virtualization at all still has to produce the same answer.28//!29//! Linux KVM, the Linux kernel interface for running a virtual machine on host30//! hardware, faced the same execution problem. Its answer, in the [Linux KVM31//! API](https://docs.kernel.org/virt/kvm/api.html), is a shape a host program32//! follows: open the KVM device, make one virtual machine and one virtual CPU,33//! give the kernel regions of the program's own memory to serve as the guest's34//! physical memory, and enter the guest with a call that comes back at every35//! boundary the host has to deal with. This code follows that shape: one36//! virtual machine, one virtual CPU, one fixed region of caller memory37//! registered as the guest's, a kernel entered with no firmware ahead of it,38//! and a loop that runs and then deals with one boundary. This code also takes39//! KVM's read-only regions, giving the guest's executable pages to the kernel40//! in a form the guest cannot write.41//!42//! The code that executes the guest's instructions (a *backend*) is a named43//! choice. One record holds that choice, carries its determinism claims, and44//! pins the rules that code must follow (a *profile*), so a second45//! implementation can answer to the same rules. A portable x86-64 interpreter,46//! the *reference backend*, executes the admitted instruction shapes in47//! software and reaches the same evidence on a machine with no KVM. Every48//! instruction the guest may run is settled before the run starts, out of the49//! kernel image's own record listing each admitted instruction position with50//! its address and its instruction shape (an *execution manifest*), so an51//! instruction whose answer would come from the host never gets to run. The52//! boundaries a general host program would service, among them memory-mapped53//! device access and hypercalls, end execution here as faults, because a run54//! that arrived at one of them leaned on a device this design does not model.55//! The guest's single way out is one byte written to one output port (a56//! *doorbell*), whose value is a yield code saying that the guest is ready, has57//! come to rest, or has faulted.58//!59//! Each outside input is checked against the position the guest has reached60//! before the guest can see it (*admission*), in the `admission` namespace.61//! Work proceeds one delivered input at a time, with the guest work that62//! settles it, a *turn*. That turn proceeds under an authority of three values63//! carried together, an *activation fence*: a world, a generation, and a token.64//! A turn that takes an input first pulls out the events the guest's stop65//! produced, then acknowledges the input, then offers up the evidence for that66//! turn. That authenticated evidence, a *quiescence receipt*, binds the67//! authority, the checked input, the evidence of which execution ran, both ring68//! positions, and the stopped guest state. `reactivate` puts a newer authority69//! in place for the next turn.70//!71//! Callers hand over `Storage` (the caller-owned bytes holding one lifecycle's72//! whole state at an address the caller keeps stable) for one run at a time. A73//! direct start and a direct restore also hand over page-aligned guest RAM. A74//! shared restore hands over two things in place of that RAM: the75//! content-addressed store that owns every stored byte of a checkpoint, and a76//! fixed pool of caller-owned pages where the restore places its writes. The77//! live execution (an *instance*) keeps every one of those buffers until78//! `deinit`.79//!80//! - *K0*: the restricted kernel from the `lib/os` package that an instance81//!   boots.82//! - *execution contract*: the execution rules one profile kind shares across83//!   backends, fixing RAM geometry, transport sizes, the determinism identity,84//!   and capacity limits.85//! - *exit*: one public execution boundary an instance reports, a doorbell86//!   code, a halt, a shutdown, or a fault.87//! - *event batch*: fixed storage for every event K0 emits at one doorbell.88//! - *root store*: the authenticated, caller-supplied content-addressed store89//!   that owns every stored byte of a checkpoint.90//! - *branch page pool*: the fixed pool of caller-owned pages where a shared91//!   restore places its writes.9293const core = @import("machine_instance_core");94const owner = @import("owner.zig");95const profile = @import("../profile/root.zig");96const receipt = @import("receipt/root.zig");9798pub const types = @import("types.zig");99100pub const BackendAvailability = types.BackendAvailability;101pub const BackendStage = types.BackendStage;102pub const Doorbell = types.Doorbell;103pub const DecodedEvent = types.DecodedEvent;104pub const ExecutionFingerprint = types.ExecutionFingerprint;105pub const Exit = types.Exit;106pub const Fault = types.Fault;107pub const FaultKind = types.FaultKind;108pub const AcknowledgeError = owner.AcknowledgeError;109pub const BasisError = owner.BasisError;110pub const CaptureCheckpointError = owner.CaptureCheckpointError;111pub const CaptureHotError = owner.CaptureHotError;112pub const DeliveryError = owner.DeliveryError;113pub const EventError = owner.EventError;114pub const EventBatchError = receipt.EventBatchError;115pub const EventBatch = types.EventBatch;116pub const InitError = owner.InitError;117pub const Input = types.Input;118pub const Instance = owner.Instance;119pub const K0State = types.K0State;120pub const MemoryError = owner.MemoryError;121pub const QuiescenceReceipt = types.QuiescenceReceipt;122pub const SemanticReceipt = receipt.SemanticReceipt;123pub const QuiescenceReceiptError = owner.QuiescenceReceiptError;124pub const ReactivateError = owner.ReactivateError;125pub const RestoreError = owner.RestoreError;126pub const RestoreInput = types.RestoreInput;127pub const RestoreResult = owner.RestoreResult;128pub const SharedRestoreInput = types.SharedRestoreInput;129pub const RunError = owner.RunError;130pub const RunPhase = types.RunPhase;131pub const SettledTransport = types.SettledTransport;132pub const StartResult = owner.StartResult;133pub const Storage = owner.Storage;134pub const Unavailable = types.Unavailable;135pub const storage_alignment = owner.storage_alignment;136pub const storage_bytes = owner.storage_bytes;137pub const run_stutter_limit = owner.run_stutter_limit;138pub const event_batch_max = types.event_batch_max;139pub const ram_alignment = core.layout.page_bytes;140pub const ram_bytes = core.layout.ram_bytes;141pub const eventTranscriptDigest = receipt.transcriptDigest;142pub const initWithStart = owner.initWithStart;143pub const projectSemanticReceipt = receipt.projectSemantic;144pub const restoreWithAcquire = owner.restoreWithAcquire;145pub const semanticReceiptDigest = receipt.semanticReceiptDigest;146pub const validateStorageBytes = owner.validateStorageBytes;147pub const validateRestore = owner.validateRestore;148pub const verifyQuiescenceReceipt = receipt.verifyForFence;149pub const verifyEventBatch = receipt.verifyEventBatch;150pub const verifyEventBatchReceipt = receipt.verifyEventBatchReceipt;151pub const verifySemanticReceipt = receipt.verifySemantic;152153pub const determinism_sources = [_]profile.DeterminismSource{154    .executable_bytes,155    .instruction_forms,156    .instruction_flags,157    .initial_cpu_state,158    .backend_instruction_result,159    .cpuid_vendor,160    .cpuid_signature,161    .cpuid_page_size_extension,162    .cpuid_physical_address_extension,163    .cpuid_conditional_move,164    .cpuid_execute_disable,165    .cpuid_long_mode,166    .cpuid_address_widths,167    .cpuid_leaf_range,168    .guest_schedule,169    .host_run_stutter,170    .guest_interrupt,171    .host_signal_interrupt,172    .channel_device,173    .doorbell_exit,174    .unmodeled_device_exit,175    .cpu_clock_instruction,176    .cpu_entropy_instruction,177};

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