tiny.machine.instance.types

1/// Room for every event one instance doorbell produces, so draining a doorbell2/// has somewhere to put what comes out. The count field says how many of those3/// slots are filled. The value holds the encoded message bytes itself. There4/// are four slots, matching the number of events K0 sends for one terminal5/// input.6pub const EventBatch = struct {7    count: u8,8    storage: [event_batch_max]os.abi.MessageWire,910    /// Borrows the filled slots in the order the events arrived, so a caller11    /// can hash or forward a turn's events without the empty tail. The count12    /// never runs past `event_batch_max`.13    pub fn frames(self: *const EventBatch) []const os.abi.MessageWire {14        std.debug.assert(self.count <= self.storage.len);15        return self.storage[0..self.count];16    }1718    /// Decodes the event sitting at one index, counted from zero, so a caller19    /// can read what that event says. A count or index out of range comes back20    /// as `EventIndexOutOfBounds`. Bytes that will not decode come back as a21    /// message error.22    pub fn event(23        self: *const EventBatch,24        index: usize,25    ) (os.abi.message.Error || error{EventIndexOutOfBounds})!DecodedEvent {26        if (self.count > self.storage.len or index >= self.count) {27            return error.EventIndexOutOfBounds;28        }29        return os.abi.decodeEvent(&self.storage[index]);30    }31};

1/// The state K0 owns and keeps when it is reactivated, so a receipt carries the2/// state the guest keeps across reactivation. The counter holds how many3/// terminal-input turns have finished.4pub const K0State = struct {5    counter: u8,6};

1/// The two ring positions at a settled guest boundary, which are equal there,2/// so a caller reading a receipt learns where the transport stood when the3/// guest came to rest.4pub const SettledTransport = struct {5    request_cursor: u64,6    event_cursor: u64,7};

1pub const event_batch_max: usize = os.k0.events_per_terminal_input;

1pub const types = @import("types.zig");

1const core = @import("machine_instance_core");2const os = @import("os");3const admission = @import("../admission/root.zig");4const checkpoint = @import("../checkpoint/root.zig");5const profile = @import("../profile/root.zig");6const receipt = @import("receipt/root.zig");78pub const BackendAvailability = core.backend.BackendAvailability;9pub const BackendStage = core.backend.BackendStage;10pub const Unavailable = core.backend.Unavailable;11pub const EventBatch = receipt.EventBatch;12pub const ExecutionFingerprint = receipt.ExecutionFingerprint;13pub const K0State = receipt.K0State;14pub const QuiescenceReceipt = receipt.QuiescenceReceipt;15pub const SettledTransport = receipt.SettledTransport;16pub const event_batch_max = receipt.event_batch_max;1718/// Gathers everything one cold start of a K0 guest needs into one value, so a19/// caller supplies all of this at once and knows how long to keep the image and20/// the manifest around. The profile inside it decides which backend runs and21/// under which execution rules. The caller keeps ownership of both slices and22/// may free them once `Instance.init` has returned.23pub const Input = struct {24    profile: profile.Profile,25    elf: []const u8,26    execution_manifest: []const u8,27    expected_execution_fingerprint: ExecutionFingerprint,28    fence: os.abi.ActivationFence,29    initial_time_tick: u64,30    entropy_generation: u64,31    terminal_offset: u64,32    effect_frontier: u64,33    block_root: os.abi.Digest,34    source_root: os.abi.Digest,35    input_frontier: u64,36    terminal_input_offset: u64,37    outstanding_effect: ?admission.EffectRequest,38};3940/// Gathers everything needed to bring a checkpoint back into RAM the caller41/// owns, so a caller supplies all of this at once for a restore. The checkpoint42/// source and the manifest stay the caller's, borrowed only for the length of43/// the `Instance.restore` call.44pub const RestoreInput = struct {45    checkpoint: checkpoint.Source,46    expected_root: checkpoint.Root,47    profile: profile.Profile,48    execution_manifest: []const u8,49    fence: os.abi.ActivationFence,50};5152/// Gathers everything needed for a portable restore whose pages come from an53/// immutable root provider, so the caller supplies a provider and branch54/// storage. The provider and the branch storage arrive as their own arguments55/// to `Instance.restoreShared`. The instance holds the memory behind both until56/// `deinit`.57pub const SharedRestoreInput = struct {58    expected_root: checkpoint.roots.ManifestRoot,59    profile: profile.Profile,60    execution_manifest: []const u8,61    fence: os.abi.ActivationFence,62};6364/// Holds one yield code read off the fixed machine doorbell port, so a caller65/// receives the value a guest yield carries.66pub const Doorbell = struct { code: os.abi.channel.DoorbellCode };6768/// Represents the stage of one lifecycle as a caller can observe it, so the69/// caller knows which lifecycle calls are legal at this moment. A lifecycle70/// call takes some stages and answers with a protocol error in the rest.71pub const RunPhase = enum(u8) {72    closed,73    booting,74    draining_activation,75    awaiting_input,76    input_delivered,77    draining_input,78    awaiting_acknowledgement,79    awaiting_reactivation,80    capturing_checkpoint,81    completing_io,82    failed,83};8485/// Records where a terminal execution fault came from, so a fault that ends a86/// run states its source. The eight sources are device, exception, entry,87/// memory, hypercall, debug, system, and backend.88pub const FaultKind = enum(u8) {89    device,90    exception,91    entry,92    memory,93    hypercall,94    debug,95    system,96    backend,97};9899/// Presents one terminal fault in a single shape across backends, so a caller100/// reads the details once a run has ended in a fault. The code and address101/// fields hold whatever the backend reported for that kind of fault.102pub const Fault = struct {103    kind: FaultKind,104    code: u64,105    address: u64,106};107108/// Reports one execution boundary in the form a caller sees, so every `run`109/// answers with this value and the answer decides whether the lifecycle goes110/// on. A ready or quiescent yield moves the lifecycle to its next stage. A111/// halt, a shutdown, a fault, and every other yield code end execution for that112/// lifecycle.113pub const Exit = union(enum) {114    doorbell: Doorbell,115    halted,116    shutdown,117    fault: Fault,118};