vihaco_cpu/lib.rs
1// SPDX-FileCopyrightText: 2026 The vihaco Authors
2// SPDX-License-Identifier: MIT
3
4//! Checked word-stack CPU component.
5//!
6//! Enable `vihaco-cpu/typed-declarations` to use the `cpu` runtime dialect and
7//! per-instruction `Execute` implementations. This forwards to the lower runtime
8//! crates; facade applications can instead enable `vihaco/typed-declarations`.
9//! Feature-off use retains the legacy instruction enums and `CPUMessage`.
10//!
11//! The nondefault `program-image-execution` feature implies `typed-declarations`
12//! and switches CPU handlers to typed operands and stack result effects.
13//! `vihaco_stdlib::ExecutionState` owns locals, operands, frames, and the program
14//! counter. Heap storage remains on CPU and uses the same typed transfers.
15//!
16//! With this feature, program instructions and their lowering helpers live in
17//! `vihaco_stdlib::program`; CPU exposes only computation and heap instructions.
18//! The following syntax description and example describe the typed-only route.
19//!
20//! Typed instruction syntax retains readable literals until explicit lowering
21//! encodes them into runtime `Word` payloads. Branch and call targets accept
22//! numeric addresses or `@name` symbols; function references accept numeric
23//! indices or function symbols. String constants accept indices or quoted text.
24//! Loaders supply `lower::LabelLookup`, `lower::FunctionLookup`, and
25//! `lower::StringIntern` to resolve them. `vihaco_stdlib::ProgramImage` implements
26//! string interning using its section string table. Heap references remain numeric.
27//! For explicit metadata, [`vihaco_module::loader::MetadataLoweringContext`] implements
28//! all three lookup capabilities and interns strings after the header's table.
29//! It works with `ParsedModule::lower_with_metadata` in `vihaco-syntax`.
30//! `@name:` symbol definitions in `.text` occupy no executable slot. Symbols,
31//! `function_start`, and `function_end` have no runtime instruction leaves.
32//! Composite source uses `device::dialect::mnemonic`, for example
33//! `host::cpu::const_i64 -42`. Generated aggregate bytecode codecs are separate work.
34//!
35//! ```
36//! # #[cfg(all(feature = "typed-declarations", not(feature = "program-image-execution")))]
37//! # {
38//! use vihaco_runtime::{Execute, NoMessage, Lower, Parse, Syntax, chumsky::Parser as _};
39//! use vihaco_module::host::StackMemory;
40//! use vihaco_cpu::{CPU, cpu, encode_i64, StepOutcome};
41//! let instruction = cpu::ConstI64::<Syntax>::parser().parse("const_i64 -42")
42//! .into_result().unwrap();
43//! let instruction = instruction.lower(&mut ()).unwrap();
44//! assert_eq!(instruction, cpu::ConstI64(encode_i64(-42)));
45//! let mut cpu = CPU::default();
46//! assert_eq!(cpu.execute(&instruction, NoMessage::new()).unwrap(), StepOutcome::Continue);
47//! assert_eq!(cpu.stack(), &[encode_i64(-42)]);
48//! # }
49//! ```
50
51#[cfg(not(feature = "program-image-execution"))]
52mod data;
53
54#[cfg(feature = "program-image-execution")]
55#[path = "program_cpu.rs"]
56mod data;
57
58#[cfg(feature = "typed-declarations")]
59#[cfg_attr(not(feature = "program-image-execution"), path = "cpu.rs")]
60#[cfg_attr(feature = "program-image-execution", path = "computation.rs")]
61mod dialect;
62
63#[cfg(not(feature = "typed-declarations"))]
64mod display;
65
66#[cfg(not(feature = "typed-declarations"))]
67mod instruction;
68
69#[cfg(feature = "typed-declarations")]
70pub use dialect::cpu;
71
72#[cfg(feature = "typed-declarations")]
73mod execute;
74
75#[cfg(all(
76 feature = "typed-declarations",
77 not(feature = "program-image-execution")
78))]
79mod literal;
80
81#[cfg(all(
82 feature = "typed-declarations",
83 not(feature = "program-image-execution")
84))]
85pub mod lower;
86
87#[cfg(all(
88 feature = "typed-declarations",
89 not(feature = "program-image-execution")
90))]
91pub mod message;
92
93#[cfg(all(
94 feature = "typed-declarations",
95 not(feature = "program-image-execution")
96))]
97pub mod operand;
98
99#[cfg(feature = "typed-declarations")]
100#[doc(hidden)]
101pub use data::{__vihaco_fields_CPU, __vihaco_inventory_CPU};
102
103#[cfg(not(feature = "program-image-execution"))]
104mod outcome;
105pub mod word;
106
107pub use data::CPU;
108
109#[cfg(not(feature = "typed-declarations"))]
110pub use data::CPUMessage;
111
112#[cfg(not(feature = "typed-declarations"))]
113pub use data::{RuntimeInstruction, SurfaceInstruction};
114
115#[cfg(not(feature = "typed-declarations"))]
116pub use instruction::{SurfaceType, SurfaceValue};
117
118#[cfg(not(feature = "program-image-execution"))]
119pub use outcome::StepOutcome;
120pub use word::{
121 Word, decode_bool, decode_f32, decode_f64, decode_function_ref, decode_heap_ref, decode_i32,
122 decode_i64, decode_string_id, decode_u32, decode_u64, encode_bool, encode_f32, encode_f64,
123 encode_function_ref, encode_heap_ref, encode_i32, encode_i64, encode_string_id, encode_u32,
124 encode_u64,
125};
126
127#[cfg(all(test, not(feature = "typed-declarations")))]
128mod tests {
129 use super::*;
130
131 #[test]
132 fn surface_instruction_implements_surface_marker() {
133 fn require_surface_instruction<T: vihaco_parser::SurfaceInstruction>() {}
134
135 require_surface_instruction::<SurfaceInstruction>();
136 }
137}