lib/machine/src/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

  1 //! A virtual machine runs a guest operating system kernel so that the same run can
  2 //! be produced again later, from stored state, with the result checkable against
  3 //! a recorded identity. The guest kernel boots directly from an ELF image, with
  4 //! no firmware stage in between. The execution rules fix one virtual CPU and one
  5 //! fixed-size region of guest memory.
  6 //!
  7 //! The guest stops only when it signals the host, so every stop is a place the guest
  8 //! chose. When the guest stops idle, the machine produces authenticated evidence
  9 //! that the guest's work settled before anything outside observes it. Every outside
 10 //! influence reaches the guest as a recorded and checked input, bound to the identity
 11 //! of the execution rules and to a digest of the state it arrived against. Each
 12 //! delivered input carries the authority to run the guest work that settles it.
 13 //! The caller supplies all of the machine's memory: the state of each running machine,
 14 //! the guest's memory, and the storage for saved state. The package holds none of
 15 //! its own.
 16 //!
 17 //! Hardware and host make two runs differ in places that are many and easy to miss:
 18 //! instruction results, interrupts, the clock, entropy, device behavior, and scheduling.
 19 //!
 20 //! The package took from KVM, the Linux kernel interface for running a virtual machine
 21 //! on host hardware, documented in the [Linux KVM API](https://docs.kernel.org/virt/kvm/api.html),
 22 //! and from the x86-64 architecture manuals, the
 23 //! [Intel Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html).
 24 //! What it took was one virtual CPU per machine, a fixed guest memory region registered
 25 //! with the host kernel, x86-64 instruction semantics, and direct kernel boot.
 26 //!
 27 //! KVM is one of two backends behind the same execution rules, and the second is
 28 //! a portable x86-64 interpreter that executes the admitted instruction forms in
 29 //! software, the *reference backend*. The backend is chosen together with one execution
 30 //! contract and the determinism claims that pairing makes (a *profile*), and a
 31 //! `portable_x86_64_interpreter_v1` profile selects the interpreter.
 32 //!
 33 //! The package answers the many easy-to-miss places by listing all 42 of them in
 34 //! canonical order, one entry per place (the *inventory*). Each namespace declares
 35 //! the named places it answers for (its *divergence sources*), and the package concatenates
 36 //! those declarations into one list. A test audits the concatenated list against
 37 //! the inventory for exact count and exact order, and a dropped or duplicated place
 38 //! fails it. The inventory records each place's control once per backend, so the
 39 //! interpreter can enforce what KVM only assumes: instruction results are enforced
 40 //! for the interpreter and assumed for KVM.
 41 //!
 42 //! A KVM profile and its portable counterpart carry the same identity of the shared
 43 //! execution rules, computed over the encoded profile with the backend field and
 44 //! the claim fields zeroed (the *contract fingerprint*), so a run under one can
 45 //! be compared against a run under the other. Eight namespaces divide the package:
 46 //! admission, checkpoint, explore, fabric, fault, profile, instance, and world.
 47 //!
 48 //! - *K0*: the restricted kernel from `lib/os` that an instance boots, exchanging
 49 //!   request and event messages with the host through fixed rings in guest RAM.
 50 //! - *guest RAM*: the machine's fixed 67,108,864 bytes of memory, addressed from zero.
 51 //! - *doorbell*: the one-byte guest output port that K0 writes to yield, carrying
 52 //!   `ready`, `quiescent`, or `guest_fault`.
 53 //! - *turn*: one input delivered to a node together with the guest work that settles
 54 //!   it.
 55 //! - *quiescence receipt*: the authenticated evidence a quiescent stop produces for
 56 //!   one turn.
 57 //! - *activation fence*: the world, generation, and token authorized for one run turn.
 58 //! - *instance*: one live K0 execution that borrows its caller-owned storage and its
 59 //!   guest-memory backing until `deinit`.
 60 //! - *instance storage*: the caller-owned bytes holding one instance lifecycle's whole
 61 //!   state, at an address the caller keeps stable.
 62 //! - *checkpoint*: captured machine execution state carrying an identity that any
 63 //!   holder of the bytes can recompute.
 64 
 65 pub const admission = @import("admission/root.zig");
 66 pub const checkpoint = @import("checkpoint/root.zig");
 67 pub const explore = @import("explore/root.zig");
 68 pub const fabric = @import("fabric/root.zig");
 69 pub const fault = @import("fault/root.zig");
 70 pub const profile = @import("profile/root.zig");
 71 pub const instance = @import("instance/root.zig");
 72 pub const world = @import("world/root.zig");
 73 
 74 pub const Capacity = profile.Capacity;
 75 pub const Checkpoint = checkpoint.Checkpoint;
 76 pub const CheckpointCpuState = checkpoint.CpuState;
 77 pub const CheckpointMemoryDigest = checkpoint.MemoryDigest;
 78 pub const CheckpointRamAlignment = checkpoint.ram_alignment;
 79 pub const CheckpointRamBytes = checkpoint.ram_bytes;
 80 pub const CheckpointStateDigest = checkpoint.StateDigest;
 81 pub const CheckpointStorage = checkpoint.Storage;
 82 pub const Contract = profile.Contract;
 83 pub const ContractFingerprint = profile.ContractFingerprint;
 84 pub const ExecutionFingerprint = instance.ExecutionFingerprint;
 85 pub const Fabric = fabric.Fabric;
 86 pub const FabricRoot = fabric.Root;
 87 pub const FaultChoice = fault.Choice;
 88 pub const FaultDecision = fault.Decision;
 89 pub const FaultKind = fault.Kind;
 90 pub const FaultPoint = fault.Point;
 91 pub const Geometry = profile.Geometry;
 92 pub const Instance = instance.Instance;
 93 pub const InstanceExit = instance.Exit;
 94 pub const InstanceInput = instance.Input;
 95 pub const InstanceRestoreError = instance.RestoreError;
 96 pub const InstanceRestoreInput = instance.RestoreInput;
 97 pub const InstanceRestoreResult = instance.RestoreResult;
 98 pub const InstanceSharedRestoreInput = instance.SharedRestoreInput;
 99 pub const InstanceRamAlignment = instance.ram_alignment;
100 pub const InstanceRamBytes = instance.ram_bytes;
101 pub const InstanceStartResult = instance.StartResult;
102 pub const InstanceStorage = instance.Storage;
103 pub const MachineRoot = checkpoint.Root;
104 pub const Profile = profile.Profile;
105 pub const ProfileFingerprint = profile.ProfileFingerprint;
106 pub const QuiescenceReceipt = instance.QuiescenceReceipt;
107 pub const SemanticReceipt = instance.SemanticReceipt;
108 pub const Usage = profile.Usage;
109 
110 pub const determinism_sources = profile.determinism_sources ++
111     instance.determinism_sources ++
112     checkpoint.determinism_sources ++
113     fabric.determinism_sources ++
114     world.determinism_sources;