cove_ir/
lib.rs

1//! The executable IR Cove is lowered to: one linear memory, one word stack,
2//! one slot numbering.
3//!
4//! [ADR 0034](../../../docs/adr/0034-one-physical-word-stack.md) decides what
5//! this is, and [`docs/LINEAR_VM.md`](../../../docs/LINEAR_VM.md) writes the
6//! design out at the level an implementer needs. The short version:
7//!
8//! - There is **one linear memory**, addressed in eight-byte words. The stack
9//!   region is reserved at `[0, STACK_WORDS)`; the heap region begins at
10//!   `STACK_WORDS`. An address is a word index into that one space, so
11//!   nothing changes value when the two regions are later placed in one
12//!   block.
13//! - There is **one stack region**. A frame is a run of words, named by a
14//!   `frame_base`, and a slot is `memory[frame_base + slot]`. Parameters,
15//!   locals, temporaries and captures share the numbering.
16//! - A word is **untagged**. What it means comes from [`Repr`], and the only
17//!   question the collector asks the static side is which slots are
18//!   [`Repr::Ref`].
19//! - The IR is a **register machine**. Every instruction names its operands
20//!   and destination by slot; there is no operand stack.
21//! - A **place is a one-word address**. There is no place object, no place
22//!   stack and no table of places.
23//! - The public `Value` is a **boundary**, not a store. It is materialised at
24//!   Host calls, entry results and trace captures, and nowhere else.
25//!
26//! # This is not a continuation of anything
27//!
28//! It is a clean-room replacement. No instruction, storage region, admission
29//! predicate or naming convention is carried over from the IR it replaces,
30//! and nothing here exists to be compatible with it. In particular there is
31//! no `Unsupported`: a lowering that met something it had not been taught
32//! would be a bug in the lowering, not a program the backend declines. The
33//! predecessor's per-refusal extension mechanism is exactly what ADR 0034
34//! forbids reconstructing.
35//!
36//! # This is a lowering, not a second source of truth
37//!
38//! `cove-sema` has already answered what every reference denotes and what
39//! every expression's type is. Nothing here re-derives that; it records the
40//! answers in a shape the machine can act on without asking again. Where the
41//! two could disagree, the checker is right by construction, because the
42//! lowering reads its answers rather than recomputing them.
43
44pub mod bytecode;
45pub mod inst;
46pub mod layout;
47pub mod lower;
48pub mod print;
49pub mod program;
50pub mod repr;
51pub mod verify;
52
53pub use bytecode::{EncodedInst, MAX_FRAME_WORDS};
54pub use inst::{ArithOp, CmpOp, Compare, Convert, Inst, Len, Num, Pc, Slot};
55pub use layout::{
56    enum_layout, struct_layout, Case, Field, Layout, LayoutId, Part, Shape, SHARED_STATE,
57    SHARED_VALUE,
58};
59pub use lower::{lower, lower_entry, lower_roots};
60pub use program::{
61    Arg, ArgsId, Builtin, BuiltinId, Capture, CaseId, Function, FunctionId, HostOp, HostOpId,
62    Local, Program, StrId, Table, TableId,
63};
64pub use repr::{RefMap, Repr};
65pub use verify::{verify, Invalid};
cove_ir/lib.rs

cove_ir/
lib.rs
