synth_core/
backend.rs

1//! Backend trait and registry for multi-backend compilation
2//!
3//! Every compiler backend (ARM, aWsm, wasker, w2c2) implements the `Backend`
4//! trait, allowing the CLI and verification framework to treat them uniformly.
5
6use crate::target::TargetSpec;
7use crate::wasm_decoder::DecodedModule;
8use crate::wasm_op::WasmOp;
9use std::collections::HashMap;
10use thiserror::Error;
11
12/// Errors from backend compilation
13#[derive(Debug, Error)]
14pub enum BackendError {
15    #[error("compilation failed: {0}")]
16    CompilationFailed(String),
17
18    #[error("backend not available: {0}")]
19    NotAvailable(String),
20
21    #[error("unsupported configuration: {0}")]
22    UnsupportedConfig(String),
23
24    #[error("external tool error: {0}")]
25    ExternalToolError(String),
26}
27
28/// Memory-bounds safety strategy. Phase 1 of `docs/binary-safety-design.md` §3.1.
29///
30/// - `Mpu`/PMP: rely on hardware (ARM MPU or RV32 PMP) — no inline check.
31/// - `Software`: emit a `CMP/BHS Trap_Handler` (ARM) or `bgeu addr, mem_size, ebreak` (RV32)
32///   before every load/store.
33/// - `Mask`: emit `AND addr, addr, #(mem_size - 1)` — only valid when memory size
34///   is a power of two. Wraps on OOB rather than trapping (fuzz-profile semantics).
35/// - `None`: no bounds enforcement.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
37pub enum SafetyBounds {
38    /// No bounds check (caller assumes the WASM module is trusted)
39    #[default]
40    None,
41    /// ARM MPU / RV32 PMP — hardware enforcement, no inline guard
42    Mpu,
43    /// Software CMP/BHS (ARM) or BGEU+EBREAK (RV32) per access
44    Software,
45    /// AND-mask, requires power-of-two memory size
46    Mask,
47}
48
49impl SafetyBounds {
50    /// Parse the `--safety-bounds` argument value.
51    pub fn parse(s: &str) -> std::result::Result<Self, String> {
52        match s {
53            "none" => Ok(SafetyBounds::None),
54            "mpu" | "pmp" => Ok(SafetyBounds::Mpu),
55            "software" | "soft" => Ok(SafetyBounds::Software),
56            "mask" | "masking" => Ok(SafetyBounds::Mask),
57            other => Err(format!(
58                "unknown --safety-bounds value '{}'; expected one of: none, mpu, software, mask",
59                other
60            )),
61        }
62    }
63
64    /// String form used in the safety manifest.
65    pub fn as_str(self) -> &'static str {
66        match self {
67            SafetyBounds::None => "none",
68            SafetyBounds::Mpu => "mpu",
69            SafetyBounds::Software => "software",
70            SafetyBounds::Mask => "mask",
71        }
72    }
73}
74
75/// Configuration for a compilation run
76#[derive(Debug, Clone)]
77pub struct CompileConfig {
78    /// Optimization level (0 = none, 1 = fast, 2 = default, 3 = aggressive)
79    pub opt_level: u8,
80    /// Target specification
81    pub target: TargetSpec,
82    /// Legacy: enable software bounds checking for memory operations.
83    /// Deprecated in favor of `safety_bounds`. When set, equivalent to
84    /// `SafetyBounds::Software`. Kept for backwards compatibility with
85    /// callers that haven't migrated yet.
86    pub bounds_check: bool,
87    /// Phase-1 unified safety-bounds knob. If `bounds_check` is `true` and
88    /// this is `None`, the legacy field wins (back-compat). If both are set,
89    /// `safety_bounds` wins.
90    pub safety_bounds: SafetyBounds,
91    /// Hardware profile name (e.g. "nrf52840", "stm32f407")
92    pub hardware: String,
93    /// Skip optimization passes (direct instruction selection)
94    pub no_optimize: bool,
95    /// Use Loom-compatible optimization preset
96    pub loom_compat: bool,
97    /// Number of imported functions (calls to indices below this use Meld dispatch)
98    pub num_imports: u32,
99    /// AAPCS integer-argument count per function, indexed by full WASM function
100    /// index (imports first, then locals). Lets `Call` marshal the right number
101    /// of operand-stack values into R0–R3 (issue #195). Empty = pass no args
102    /// (pre-#195 behaviour).
103    pub func_arg_counts: Vec<u32>,
104    /// AAPCS integer-argument count per function type, indexed by type index.
105    /// Used by `call_indirect` (issue #195).
106    pub type_arg_counts: Vec<u32>,
107}
108
109impl CompileConfig {
110    /// Resolve the effective safety-bounds setting, honouring the legacy
111    /// `bounds_check` field as a fallback. Used by backends to pick the
112    /// inline-check shape.
113    pub fn effective_safety_bounds(&self) -> SafetyBounds {
114        match (self.safety_bounds, self.bounds_check) {
115            (SafetyBounds::None, true) => SafetyBounds::Software,
116            (s, _) => s,
117        }
118    }
119}
120
121impl Default for CompileConfig {
122    fn default() -> Self {
123        Self {
124            opt_level: 2,
125            target: TargetSpec::cortex_m4(),
126            bounds_check: false,
127            safety_bounds: SafetyBounds::None,
128            hardware: String::new(),
129            no_optimize: false,
130            loom_compat: false,
131            num_imports: 0,
132            func_arg_counts: Vec::new(),
133            type_arg_counts: Vec::new(),
134        }
135    }
136}
137
138/// A relocation entry produced during compilation
139///
140/// Records that a BL instruction at `offset` bytes into the function's code
141/// targets an external symbol (e.g., `__meld_dispatch_import`). The linker
142/// resolves these when combining the Synth object with the Kiln bridge.
143#[derive(Debug, Clone, PartialEq, Eq)]
144pub struct CodeRelocation {
145    /// Byte offset within the function's machine code where the BL resides
146    pub offset: u32,
147    /// Target symbol name (e.g., "__meld_dispatch_import")
148    pub symbol: String,
149}
150
151/// A single compiled function
152#[derive(Debug, Clone)]
153pub struct CompiledFunction {
154    /// Function name (from WASM export or generated)
155    pub name: String,
156    /// Raw machine code bytes
157    pub code: Vec<u8>,
158    /// Original WASM ops (retained for verification)
159    pub wasm_ops: Vec<WasmOp>,
160    /// Relocations for external symbol references (BL to bridge functions)
161    pub relocations: Vec<CodeRelocation>,
162}
163
164/// Result of compiling a full module
165#[derive(Debug)]
166pub struct CompilationResult {
167    /// Compiled functions
168    pub functions: Vec<CompiledFunction>,
169    /// Complete ELF binary (if backend produces one directly)
170    pub elf: Option<Vec<u8>>,
171    /// Name of the backend that produced this result
172    pub backend_name: String,
173}
174
175/// What a backend can and cannot do
176#[derive(Debug, Clone)]
177pub struct BackendCapabilities {
178    /// Backend produces complete ELF files (external backends like aWsm)
179    pub produces_elf: bool,
180    /// Backend supports per-rule verification (only our custom ARM backend)
181    pub supports_rule_verification: bool,
182    /// Backend supports binary-level verification (all backends via disassembly)
183    pub supports_binary_verification: bool,
184    /// Backend is an external tool (not a library)
185    pub is_external: bool,
186}
187
188/// Trait that every compilation backend implements
189pub trait Backend: Send + Sync {
190    /// Human-readable backend name
191    fn name(&self) -> &str;
192
193    /// What this backend can do
194    fn capabilities(&self) -> BackendCapabilities;
195
196    /// Which targets this backend supports
197    fn supported_targets(&self) -> Vec<TargetSpec>;
198
199    /// Compile an entire decoded WASM module
200    fn compile_module(
201        &self,
202        module: &DecodedModule,
203        config: &CompileConfig,
204    ) -> std::result::Result<CompilationResult, BackendError>;
205
206    /// Compile a single function from WASM ops to machine code
207    fn compile_function(
208        &self,
209        name: &str,
210        ops: &[WasmOp],
211        config: &CompileConfig,
212    ) -> std::result::Result<CompiledFunction, BackendError>;
213
214    /// Check if this backend is available (external tools installed, etc.)
215    fn is_available(&self) -> bool;
216}
217
218/// Registry of available backends
219pub struct BackendRegistry {
220    backends: HashMap<String, Box<dyn Backend>>,
221}
222
223impl BackendRegistry {
224    pub fn new() -> Self {
225        Self {
226            backends: HashMap::new(),
227        }
228    }
229
230    /// Register a backend under its name
231    pub fn register(&mut self, backend: Box<dyn Backend>) {
232        let name = backend.name().to_string();
233        self.backends.insert(name, backend);
234    }
235
236    /// Get a backend by name
237    pub fn get(&self, name: &str) -> Option<&dyn Backend> {
238        self.backends.get(name).map(|b| b.as_ref())
239    }
240
241    /// List all registered backends
242    pub fn list(&self) -> Vec<&dyn Backend> {
243        self.backends.values().map(|b| b.as_ref()).collect()
244    }
245
246    /// List backends that are actually available (installed and working)
247    pub fn available(&self) -> Vec<&dyn Backend> {
248        self.backends
249            .values()
250            .filter(|b| b.is_available())
251            .map(|b| b.as_ref())
252            .collect()
253    }
254}
255
256impl Default for BackendRegistry {
257    fn default() -> Self {
258        Self::new()
259    }
260}
261
262#[cfg(test)]
263mod tests {
264    use super::*;
265
266    #[test]
267    fn test_registry_empty() {
268        let reg = BackendRegistry::new();
269        assert!(reg.list().is_empty());
270        assert!(reg.available().is_empty());
271        assert!(reg.get("arm").is_none());
272    }
273
274    #[test]
275    fn test_compile_config_default() {
276        let config = CompileConfig::default();
277        assert_eq!(config.opt_level, 2);
278        assert!(!config.bounds_check);
279        assert_eq!(config.safety_bounds, SafetyBounds::None);
280        assert!(!config.no_optimize);
281    }
282
283    #[test]
284    fn safety_bounds_parse_round_trip() {
285        for s in ["none", "mpu", "software", "mask"] {
286            let sb = SafetyBounds::parse(s).unwrap();
287            assert_eq!(sb.as_str(), s);
288        }
289        assert_eq!(SafetyBounds::parse("pmp").unwrap(), SafetyBounds::Mpu);
290        assert_eq!(SafetyBounds::parse("soft").unwrap(), SafetyBounds::Software);
291        assert!(SafetyBounds::parse("nonsense").is_err());
292    }
293
294    #[test]
295    fn effective_safety_bounds_legacy_promotes_to_software() {
296        let cfg = CompileConfig {
297            bounds_check: true,
298            ..Default::default()
299        };
300        assert_eq!(cfg.effective_safety_bounds(), SafetyBounds::Software);
301    }
302
303    #[test]
304    fn effective_safety_bounds_new_field_wins() {
305        let cfg = CompileConfig {
306            bounds_check: true,
307            safety_bounds: SafetyBounds::Mpu,
308            ..Default::default()
309        };
310        assert_eq!(cfg.effective_safety_bounds(), SafetyBounds::Mpu);
311    }
312}
synth_core/backend.rs

synth_core/
backend.rs
