1 use crate::Config; 2 use crate::RRConfig; 3 use crate::prelude::*; 4 #[cfg(feature = "runtime")] 5 pub use crate::runtime::code_memory::CustomCodeMemory; 6 #[cfg(feature = "runtime")] 7 use crate::runtime::type_registry::TypeRegistry; 8 #[cfg(feature = "runtime")] 9 use crate::runtime::vm::{GcRuntime, ModuleRuntimeInfo}; 10 use alloc::sync::Arc; 11 use core::ptr::NonNull; 12 #[cfg(target_has_atomic = "64")] 13 use core::sync::atomic::{AtomicU64, Ordering}; 14 #[cfg(any(feature = "cranelift", feature = "winch"))] 15 use object::write::{Object, StandardSegment}; 16 #[cfg(feature = "std")] 17 use std::{fs::File, path::Path}; 18 use wasmparser::WasmFeatures; 19 use wasmtime_environ::{FlagValue, ObjectKind, TripleExt, Tunables}; 20 21 mod serialization; 22 23 /// An `Engine` which is a global context for compilation and management of wasm 24 /// modules. 25 /// 26 /// An engine can be safely shared across threads and is a cheap cloneable 27 /// handle to the actual engine. The engine itself will be deallocated once all 28 /// references to it have gone away. 29 /// 30 /// Engines store global configuration preferences such as compilation settings, 31 /// enabled features, etc. You'll likely only need at most one of these for a 32 /// program. 33 /// 34 /// ## Engines and `Clone` 35 /// 36 /// Using `clone` on an `Engine` is a cheap operation. It will not create an 37 /// entirely new engine, but rather just a new reference to the existing engine. 38 /// In other words it's a shallow copy, not a deep copy. 39 /// 40 /// ## Engines and `Default` 41 /// 42 /// You can create an engine with default configuration settings using 43 /// `Engine::default()`. Be sure to consult the documentation of [`Config`] for 44 /// default settings. 45 #[derive(Clone)] 46 pub struct Engine { 47 inner: Arc<EngineInner>, 48 } 49 50 struct EngineInner { 51 config: Config, 52 features: WasmFeatures, 53 tunables: Tunables, 54 #[cfg(any(feature = "cranelift", feature = "winch"))] 55 compiler: Option<Box<dyn wasmtime_environ::Compiler>>, 56 #[cfg(feature = "runtime")] 57 allocator: Box<dyn crate::runtime::vm::InstanceAllocator + Send + Sync>, 58 #[cfg(feature = "runtime")] 59 gc_runtime: Option<Arc<dyn GcRuntime>>, 60 #[cfg(feature = "runtime")] 61 profiler: Box<dyn crate::profiling_agent::ProfilingAgent>, 62 #[cfg(feature = "runtime")] 63 signatures: TypeRegistry, 64 #[cfg(all(feature = "runtime", target_has_atomic = "64"))] 65 epoch: AtomicU64, 66 67 /// One-time check of whether the compiler's settings, if present, are 68 /// compatible with the native host. 69 compatible_with_native_host: crate::sync::OnceLock<Result<(), String>>, 70 71 /// The canonical empty `ModuleRuntimeInfo`, so that each store doesn't need 72 /// allocate its own copy when creating its default caller instance or GC 73 /// heap. 74 #[cfg(feature = "runtime")] 75 empty_module_runtime_info: ModuleRuntimeInfo, 76 } 77 78 impl core::fmt::Debug for Engine { fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result79 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { 80 f.debug_tuple("Engine") 81 .field(&Arc::as_ptr(&self.inner)) 82 .finish() 83 } 84 } 85 86 impl Default for Engine { default() -> Engine87 fn default() -> Engine { 88 Engine::new(&Config::default()).unwrap() 89 } 90 } 91 92 impl Engine { 93 /// Creates a new [`Engine`] with the specified compilation and 94 /// configuration settings. 95 /// 96 /// # Errors 97 /// 98 /// This method can fail if the `config` is invalid or some 99 /// configurations are incompatible. 100 /// 101 /// For example, feature `reference_types` will need to set 102 /// the compiler setting `unwind_info` to `true`, but explicitly 103 /// disable these two compiler settings will cause errors. new(config: &Config) -> Result<Engine>104 pub fn new(config: &Config) -> Result<Engine> { 105 let config = config.clone(); 106 let (mut tunables, features) = config.validate()?; 107 108 #[cfg(feature = "runtime")] 109 if tunables.signals_based_traps { 110 // Ensure that crate::runtime::vm's signal handlers are 111 // configured. This is the per-program initialization required for 112 // handling traps, such as configuring signals, vectored exception 113 // handlers, etc. 114 #[cfg(has_native_signals)] 115 crate::runtime::vm::init_traps(config.macos_use_mach_ports); 116 if !cfg!(miri) { 117 #[cfg(all(has_host_compiler_backend, feature = "debug-builtins"))] 118 crate::runtime::vm::debug_builtins::init(); 119 } 120 } 121 122 #[cfg(any(feature = "cranelift", feature = "winch"))] 123 let (config, compiler) = if config.has_compiler() { 124 let (config, compiler) = config.build_compiler(&mut tunables, features)?; 125 (config, Some(compiler)) 126 } else { 127 (config.clone(), None) 128 }; 129 #[cfg(not(any(feature = "cranelift", feature = "winch")))] 130 let _ = &mut tunables; 131 132 #[cfg(feature = "runtime")] 133 let empty_module_runtime_info = ModuleRuntimeInfo::bare(try_new( 134 wasmtime_environ::Module::new(wasmtime_environ::StaticModuleIndex::from_u32(0)), 135 )?)?; 136 137 Ok(Engine { 138 inner: try_new::<Arc<_>>(EngineInner { 139 #[cfg(any(feature = "cranelift", feature = "winch"))] 140 compiler, 141 #[cfg(feature = "runtime")] 142 allocator: { 143 let allocator = config.build_allocator(&tunables)?; 144 #[cfg(feature = "gc")] 145 { 146 let mem_ty = tunables.gc_heap_memory_type(); 147 allocator.validate_memory(&mem_ty).context( 148 "instance allocator cannot support configured GC heap memory", 149 )?; 150 } 151 allocator 152 }, 153 #[cfg(feature = "runtime")] 154 gc_runtime: config.build_gc_runtime()?, 155 #[cfg(feature = "runtime")] 156 profiler: config.build_profiler()?, 157 #[cfg(feature = "runtime")] 158 signatures: TypeRegistry::new(), 159 #[cfg(all(feature = "runtime", target_has_atomic = "64"))] 160 epoch: AtomicU64::new(0), 161 compatible_with_native_host: Default::default(), 162 config, 163 tunables, 164 features, 165 #[cfg(feature = "runtime")] 166 empty_module_runtime_info, 167 })?, 168 }) 169 } 170 171 /// Returns the configuration settings that this engine is using. 172 #[inline] config(&self) -> &Config173 pub fn config(&self) -> &Config { 174 &self.inner.config 175 } 176 177 #[inline] features(&self) -> WasmFeatures178 pub(crate) fn features(&self) -> WasmFeatures { 179 self.inner.features 180 } 181 run_maybe_parallel< A: Send, B: Send, E: Send, F: Fn(A) -> Result<B, E> + Send + Sync, >( &self, input: Vec<A>, f: F, ) -> Result<Vec<B>, E>182 pub(crate) fn run_maybe_parallel< 183 A: Send, 184 B: Send, 185 E: Send, 186 F: Fn(A) -> Result<B, E> + Send + Sync, 187 >( 188 &self, 189 input: Vec<A>, 190 f: F, 191 ) -> Result<Vec<B>, E> { 192 if self.config().parallel_compilation { 193 #[cfg(feature = "parallel-compilation")] 194 { 195 use rayon::prelude::*; 196 // If we collect into Result<Vec<B>, E> directly, the returned error is not 197 // deterministic, because any error could be returned early. So we first materialize 198 // all results in order and then return the first error deterministically, or Ok(_). 199 return input 200 .into_par_iter() 201 .map(|a| f(a)) 202 .collect::<Vec<Result<B, E>>>() 203 .into_iter() 204 .collect::<Result<Vec<B>, E>>(); 205 } 206 } 207 208 // In case the parallel-compilation feature is disabled or the parallel_compilation config 209 // was turned off dynamically fallback to the non-parallel version. 210 input 211 .into_iter() 212 .map(|a| f(a)) 213 .collect::<Result<Vec<B>, E>>() 214 } 215 216 #[cfg(any(feature = "cranelift", feature = "winch"))] run_maybe_parallel_mut< T: Send, E: Send, F: Fn(&mut T) -> Result<(), E> + Send + Sync, >( &self, input: &mut [T], f: F, ) -> Result<(), E>217 pub(crate) fn run_maybe_parallel_mut< 218 T: Send, 219 E: Send, 220 F: Fn(&mut T) -> Result<(), E> + Send + Sync, 221 >( 222 &self, 223 input: &mut [T], 224 f: F, 225 ) -> Result<(), E> { 226 if self.config().parallel_compilation { 227 #[cfg(feature = "parallel-compilation")] 228 { 229 use rayon::prelude::*; 230 // If we collect into `Result<(), E>` directly, the returned 231 // error is not deterministic, because any error could be 232 // returned early. So we first materialize all results in order 233 // and then return the first error deterministically, or 234 // `Ok(_)`. 235 return input 236 .into_par_iter() 237 .map(|a| f(a)) 238 .collect::<Vec<Result<(), E>>>() 239 .into_iter() 240 .collect::<Result<(), E>>(); 241 } 242 } 243 244 // In case the parallel-compilation feature is disabled or the 245 // parallel_compilation config was turned off dynamically fallback to 246 // the non-parallel version. 247 input.into_iter().map(|a| f(a)).collect::<Result<(), E>>() 248 } 249 250 /// Take a weak reference to this engine. weak(&self) -> EngineWeak251 pub fn weak(&self) -> EngineWeak { 252 EngineWeak { 253 inner: Arc::downgrade(&self.inner), 254 } 255 } 256 257 #[inline] tunables(&self) -> &Tunables258 pub(crate) fn tunables(&self) -> &Tunables { 259 &self.inner.tunables 260 } 261 262 /// Returns whether the engine `a` and `b` refer to the same configuration. 263 #[inline] same(a: &Engine, b: &Engine) -> bool264 pub fn same(a: &Engine, b: &Engine) -> bool { 265 Arc::ptr_eq(&a.inner, &b.inner) 266 } 267 268 /// Returns whether the engine is configured to support execution recording 269 #[inline] is_recording(&self) -> bool270 pub fn is_recording(&self) -> bool { 271 match self.config().rr_config { 272 #[cfg(feature = "rr")] 273 RRConfig::Recording => true, 274 #[cfg(feature = "rr")] 275 RRConfig::Replaying => false, 276 RRConfig::None => false, 277 } 278 } 279 280 /// Returns whether the engine is configured to support execution replaying 281 #[inline] is_replaying(&self) -> bool282 pub fn is_replaying(&self) -> bool { 283 match self.config().rr_config { 284 #[cfg(feature = "rr")] 285 RRConfig::Replaying => true, 286 #[cfg(feature = "rr")] 287 RRConfig::Recording => false, 288 RRConfig::None => false, 289 } 290 } 291 292 /// Detects whether the bytes provided are a precompiled object produced by 293 /// Wasmtime. 294 /// 295 /// This function will inspect the header of `bytes` to determine if it 296 /// looks like a precompiled core wasm module or a precompiled component. 297 /// This does not validate the full structure or guarantee that 298 /// deserialization will succeed, instead it helps higher-levels of the 299 /// stack make a decision about what to do next when presented with the 300 /// `bytes` as an input module. 301 /// 302 /// If the `bytes` looks like a precompiled object previously produced by 303 /// [`Module::serialize`](crate::Module::serialize), 304 /// [`Component::serialize`](crate::component::Component::serialize), 305 /// [`Engine::precompile_module`], or [`Engine::precompile_component`], then 306 /// this will return `Some(...)` indicating so. Otherwise `None` is 307 /// returned. detect_precompiled(bytes: &[u8]) -> Option<Precompiled>308 pub fn detect_precompiled(bytes: &[u8]) -> Option<Precompiled> { 309 serialization::detect_precompiled_bytes(bytes) 310 } 311 312 /// Like [`Engine::detect_precompiled`], but performs the detection on a file. 313 #[cfg(feature = "std")] detect_precompiled_file(path: impl AsRef<Path>) -> Result<Option<Precompiled>>314 pub fn detect_precompiled_file(path: impl AsRef<Path>) -> Result<Option<Precompiled>> { 315 serialization::detect_precompiled_file(path) 316 } 317 318 /// Returns the target triple which this engine is compiling code for 319 /// and/or running code for. target(&self) -> target_lexicon::Triple320 pub(crate) fn target(&self) -> target_lexicon::Triple { 321 return self.config().compiler_target(); 322 } 323 324 /// Verify that this engine's configuration is compatible with loading 325 /// modules onto the native host platform. 326 /// 327 /// This method is used as part of `Module::new` to ensure that this 328 /// engine can indeed load modules for the configured compiler (if any). 329 /// Note that if cranelift is disabled this trivially returns `Ok` because 330 /// loaded serialized modules are checked separately. check_compatible_with_native_host(&self) -> Result<()>331 pub(crate) fn check_compatible_with_native_host(&self) -> Result<()> { 332 self.inner 333 .compatible_with_native_host 334 .get_or_init(|| self._check_compatible_with_native_host()) 335 .clone() 336 .map_err(crate::Error::msg) 337 } 338 _check_compatible_with_native_host(&self) -> Result<(), String>339 fn _check_compatible_with_native_host(&self) -> Result<(), String> { 340 use target_lexicon::Triple; 341 342 let host = Triple::host(); 343 let target = self.config().compiler_target(); 344 345 let target_matches_host = || { 346 // If the host target and target triple match, then it's valid 347 // to run results of compilation on this host. 348 if host == target { 349 return true; 350 } 351 352 // If there's a mismatch and the target is a compatible pulley 353 // target, then that's also ok to run. 354 if cfg!(feature = "pulley") 355 && target.is_pulley() 356 && target.pointer_width() == host.pointer_width() 357 && target.endianness() == host.endianness() 358 { 359 return true; 360 } 361 362 // ... otherwise everything else is considered not a match. 363 false 364 }; 365 366 if !target_matches_host() { 367 return Err(format!( 368 "target '{target}' specified in the configuration does not match the host" 369 )); 370 } 371 372 #[cfg(any(feature = "cranelift", feature = "winch"))] 373 { 374 if let Some(compiler) = self.compiler() { 375 // Also double-check all compiler settings 376 for (key, value) in compiler.flags().iter() { 377 self.check_compatible_with_shared_flag(key, value)?; 378 } 379 for (key, value) in compiler.isa_flags().iter() { 380 self.check_compatible_with_isa_flag(key, value)?; 381 } 382 } 383 } 384 385 // Double-check that this configuration isn't requesting capabilities 386 // that this build of Wasmtime doesn't support. 387 if !cfg!(has_native_signals) && self.tunables().signals_based_traps { 388 return Err("signals-based-traps disabled at compile time -- cannot be enabled".into()); 389 } 390 if !cfg!(has_virtual_memory) && self.tunables().memory_init_cow { 391 return Err("virtual memory disabled at compile time -- cannot enable CoW".into()); 392 } 393 if !cfg!(target_has_atomic = "64") && self.tunables().epoch_interruption { 394 return Err("epochs currently require 64-bit atomics".into()); 395 } 396 397 // Double-check that the host's float ABI matches Cranelift's float ABI. 398 // See `Config::x86_float_abi_ok` for some more 399 // information. 400 if target == target_lexicon::triple!("x86_64-unknown-none") 401 && self.config().x86_float_abi_ok != Some(true) 402 { 403 return Err("\ 404 the x86_64-unknown-none target by default uses a soft-float ABI that is \ 405 incompatible with Cranelift and Wasmtime -- use \ 406 `Config::x86_float_abi_ok` to disable this check and see more \ 407 information about this check\ 408 " 409 .into()); 410 } 411 412 Ok(()) 413 } 414 415 /// Checks to see whether the "shared flag", something enabled for 416 /// individual compilers, is compatible with the native host platform. 417 /// 418 /// This is used both when validating an engine's compilation settings are 419 /// compatible with the host as well as when deserializing modules from 420 /// disk to ensure they're compatible with the current host. 421 /// 422 /// Note that most of the settings here are not configured by users that 423 /// often. While theoretically possible via `Config` methods the more 424 /// interesting flags are the ISA ones below. Typically the values here 425 /// represent global configuration for wasm features. Settings here 426 /// currently rely on the compiler informing us of all settings, including 427 /// those disabled. Settings then fall in a few buckets: 428 /// 429 /// * Some settings must be enabled, such as `preserve_frame_pointers`. 430 /// * Some settings must have a particular value, such as 431 /// `libcall_call_conv`. 432 /// * Some settings do not matter as to their value, such as `opt_level`. check_compatible_with_shared_flag( &self, flag: &str, value: &FlagValue, ) -> Result<(), String>433 pub(crate) fn check_compatible_with_shared_flag( 434 &self, 435 flag: &str, 436 value: &FlagValue, 437 ) -> Result<(), String> { 438 let target = self.target(); 439 let ok = match flag { 440 // These settings must all have be enabled, since their value 441 // can affect the way the generated code performs or behaves at 442 // runtime. 443 "libcall_call_conv" => *value == FlagValue::Enum("isa_default"), 444 "preserve_frame_pointers" => *value == FlagValue::Bool(true), 445 "enable_probestack" => *value == FlagValue::Bool(true), 446 "probestack_strategy" => *value == FlagValue::Enum("inline"), 447 "enable_multi_ret_implicit_sret" => *value == FlagValue::Bool(true), 448 449 // Features wasmtime doesn't use should all be disabled, since 450 // otherwise if they are enabled it could change the behavior of 451 // generated code. 452 "enable_llvm_abi_extensions" => *value == FlagValue::Bool(false), 453 "enable_pinned_reg" => *value == FlagValue::Bool(false), 454 "use_colocated_libcalls" => *value == FlagValue::Bool(false), 455 "use_pinned_reg_as_heap_base" => *value == FlagValue::Bool(false), 456 457 // Windows requires unwind info as part of its ABI. 458 "unwind_info" => { 459 if target.operating_system == target_lexicon::OperatingSystem::Windows { 460 *value == FlagValue::Bool(true) 461 } else { 462 return Ok(()) 463 } 464 } 465 466 // stack switch model must match the current OS 467 "stack_switch_model" => { 468 if self.features().contains(WasmFeatures::STACK_SWITCHING) { 469 use target_lexicon::OperatingSystem; 470 let expected = 471 match target.operating_system { 472 OperatingSystem::Windows => "update_windows_tib", 473 OperatingSystem::Linux 474 | OperatingSystem::MacOSX(_) 475 | OperatingSystem::Darwin(_) => "basic", 476 _ => { return Err(String::from("stack-switching feature not supported on this platform")); } 477 }; 478 *value == FlagValue::Enum(expected) 479 } else { 480 return Ok(()) 481 } 482 } 483 484 // These settings don't affect the interface or functionality of 485 // the module itself, so their configuration values shouldn't 486 // matter. 487 "enable_heap_access_spectre_mitigation" 488 | "enable_table_access_spectre_mitigation" 489 | "enable_nan_canonicalization" 490 | "enable_float" 491 | "enable_verifier" 492 | "regalloc_checker" 493 | "regalloc_verbose_logs" 494 | "regalloc_algorithm" 495 | "is_pic" 496 | "bb_padding_log2_minus_one" 497 | "log2_min_function_alignment" 498 | "machine_code_cfg_info" 499 | "tls_model" // wasmtime doesn't use tls right now 500 | "opt_level" // opt level doesn't change semantics 501 | "enable_alias_analysis" // alias analysis-based opts don't change semantics 502 | "probestack_size_log2" // probestack above asserted disabled 503 | "regalloc" // shouldn't change semantics 504 | "enable_incremental_compilation_cache_checks" // shouldn't change semantics 505 | "enable_atomics" => return Ok(()), 506 507 // Everything else is unknown and needs to be added somewhere to 508 // this list if encountered. 509 _ => { 510 return Err(format!("unknown shared setting {flag:?} configured to {value:?}")) 511 } 512 }; 513 514 if !ok { 515 return Err(format!( 516 "setting {flag:?} is configured to {value:?} which is not supported", 517 )); 518 } 519 Ok(()) 520 } 521 522 /// Same as `check_compatible_with_native_host` except used for ISA-specific 523 /// flags. This is used to test whether a configured ISA flag is indeed 524 /// available on the host platform itself. check_compatible_with_isa_flag( &self, flag: &str, value: &FlagValue, ) -> Result<(), String>525 pub(crate) fn check_compatible_with_isa_flag( 526 &self, 527 flag: &str, 528 value: &FlagValue, 529 ) -> Result<(), String> { 530 match value { 531 // ISA flags are used for things like CPU features, so if they're 532 // disabled then it's compatible with the native host. 533 FlagValue::Bool(false) => return Ok(()), 534 535 // Fall through below where we test at runtime that features are 536 // available. 537 FlagValue::Bool(true) => {} 538 539 // Pulley's pointer_width must match the host. 540 FlagValue::Enum("pointer32") => { 541 return if cfg!(target_pointer_width = "32") { 542 Ok(()) 543 } else { 544 Err("wrong host pointer width".to_string()) 545 }; 546 } 547 FlagValue::Enum("pointer64") => { 548 return if cfg!(target_pointer_width = "64") { 549 Ok(()) 550 } else { 551 Err("wrong host pointer width".to_string()) 552 }; 553 } 554 555 // Only `bool` values are supported right now, other settings would 556 // need more support here. 557 _ => { 558 return Err(format!( 559 "isa-specific feature {flag:?} configured to unknown value {value:?}" 560 )); 561 } 562 } 563 564 let host_feature = match flag { 565 // aarch64 features to detect 566 "has_lse" => "lse", 567 "has_pauth" => "paca", 568 "has_fp16" => "fp16", 569 570 // aarch64 features which don't need detection 571 // No effect on its own. 572 "sign_return_address_all" => return Ok(()), 573 // The pointer authentication instructions act as a `NOP` when 574 // unsupported, so it is safe to enable them. 575 "sign_return_address" => return Ok(()), 576 // No effect on its own. 577 "sign_return_address_with_bkey" => return Ok(()), 578 // The `BTI` instruction acts as a `NOP` when unsupported, so it 579 // is safe to enable it regardless of whether the host supports it 580 // or not. 581 "use_bti" => return Ok(()), 582 583 // s390x features to detect 584 "has_vxrs_ext2" => "vxrs_ext2", 585 "has_vxrs_ext3" => "vxrs_ext3", 586 "has_mie3" => "mie3", 587 "has_mie4" => "mie4", 588 589 // x64 features to detect 590 "has_cmpxchg16b" => "cmpxchg16b", 591 "has_sse3" => "sse3", 592 "has_ssse3" => "ssse3", 593 "has_sse41" => "sse4.1", 594 "has_sse42" => "sse4.2", 595 "has_popcnt" => "popcnt", 596 "has_avx" => "avx", 597 "has_avx2" => "avx2", 598 "has_fma" => "fma", 599 "has_bmi1" => "bmi1", 600 "has_bmi2" => "bmi2", 601 "has_avx512bitalg" => "avx512bitalg", 602 "has_avx512dq" => "avx512dq", 603 "has_avx512f" => "avx512f", 604 "has_avx512vl" => "avx512vl", 605 "has_avx512vbmi" => "avx512vbmi", 606 "has_lzcnt" => "lzcnt", 607 608 // pulley features 609 "big_endian" if cfg!(target_endian = "big") => return Ok(()), 610 "big_endian" if cfg!(target_endian = "little") => { 611 return Err("wrong host endianness".to_string()); 612 } 613 614 _ => { 615 // FIXME: should enumerate risc-v features and plumb them 616 // through to the `detect_host_feature` function. 617 if cfg!(target_arch = "riscv64") && flag != "not_a_flag" { 618 return Ok(()); 619 } 620 return Err(format!( 621 "don't know how to test for target-specific flag {flag:?} at runtime" 622 )); 623 } 624 }; 625 626 let detect = match self.config().detect_host_feature { 627 Some(detect) => detect, 628 None => { 629 return Err(format!( 630 "cannot determine if host feature {host_feature:?} is \ 631 available at runtime, configure a probing function with \ 632 `Config::detect_host_feature`" 633 )); 634 } 635 }; 636 637 match detect(host_feature) { 638 Some(true) => Ok(()), 639 Some(false) => Err(format!( 640 "compilation setting {flag:?} is enabled, but not \ 641 available on the host", 642 )), 643 None => Err(format!( 644 "failed to detect if target-specific flag {host_feature:?} is \ 645 available at runtime (compile setting {flag:?})" 646 )), 647 } 648 } 649 650 /// Returns whether this [`Engine`] is configured to execute with Pulley, 651 /// Wasmtime's interpreter. 652 /// 653 /// Note that Pulley is the default for host platforms that do not have a 654 /// Cranelift backend to support them. For example at the time of this 655 /// writing 32-bit x86 is not supported in Cranelift so the 656 /// `i686-unknown-linux-gnu` target would by default return `true` here. is_pulley(&self) -> bool657 pub fn is_pulley(&self) -> bool { 658 self.target().is_pulley() 659 } 660 661 #[cfg(feature = "runtime")] empty_module_runtime_info(&self) -> &ModuleRuntimeInfo662 pub(crate) fn empty_module_runtime_info(&self) -> &ModuleRuntimeInfo { 663 &self.inner.empty_module_runtime_info 664 } 665 } 666 667 #[cfg(any(feature = "cranelift", feature = "winch"))] 668 impl Engine { compiler(&self) -> Option<&dyn wasmtime_environ::Compiler>669 pub(crate) fn compiler(&self) -> Option<&dyn wasmtime_environ::Compiler> { 670 self.inner.compiler.as_deref() 671 } 672 try_compiler(&self) -> Result<&dyn wasmtime_environ::Compiler>673 pub(crate) fn try_compiler(&self) -> Result<&dyn wasmtime_environ::Compiler> { 674 self.compiler() 675 .ok_or_else(|| format_err!("Engine was not configured with a compiler")) 676 } 677 678 /// Ahead-of-time (AOT) compiles a WebAssembly module. 679 /// 680 /// The `bytes` provided must be in one of two formats: 681 /// 682 /// * A [binary-encoded][binary] WebAssembly module. This is always supported. 683 /// * A [text-encoded][text] instance of the WebAssembly text format. 684 /// This is only supported when the `wat` feature of this crate is enabled. 685 /// If this is supplied then the text format will be parsed before validation. 686 /// Note that the `wat` feature is enabled by default. 687 /// 688 /// This method may be used to compile a module for use with a different target 689 /// host. The output of this method may be used with 690 /// [`Module::deserialize`](crate::Module::deserialize) on hosts compatible 691 /// with the [`Config`](crate::Config) associated with this [`Engine`]. 692 /// 693 /// The output of this method is safe to send to another host machine for later 694 /// execution. As the output is already a compiled module, translation and code 695 /// generation will be skipped and this will improve the performance of constructing 696 /// a [`Module`](crate::Module) from the output of this method. 697 /// 698 /// [binary]: https://webassembly.github.io/spec/core/binary/index.html 699 /// [text]: https://webassembly.github.io/spec/core/text/index.html precompile_module(&self, bytes: &[u8]) -> Result<Vec<u8>>700 pub fn precompile_module(&self, bytes: &[u8]) -> Result<Vec<u8>> { 701 crate::CodeBuilder::new(self) 702 .wasm_binary_or_text(bytes, None)? 703 .compile_module_serialized() 704 } 705 706 /// Same as [`Engine::precompile_module`] except for a 707 /// [`Component`](crate::component::Component) 708 #[cfg(feature = "component-model")] precompile_component(&self, bytes: &[u8]) -> Result<Vec<u8>>709 pub fn precompile_component(&self, bytes: &[u8]) -> Result<Vec<u8>> { 710 crate::CodeBuilder::new(self) 711 .wasm_binary_or_text(bytes, None)? 712 .compile_component_serialized() 713 } 714 715 /// Produces a blob of bytes by serializing the `engine`'s configuration data to 716 /// be checked, perhaps in a different process, with the `check_compatible` 717 /// method below. 718 /// 719 /// The blob of bytes is inserted into the object file specified to become part 720 /// of the final compiled artifact. append_compiler_info(&self, obj: &mut Object<'_>) -> Result<()>721 pub(crate) fn append_compiler_info(&self, obj: &mut Object<'_>) -> Result<()> { 722 serialization::append_compiler_info(self, obj, &serialization::Metadata::new(&self)?); 723 Ok(()) 724 } 725 726 #[cfg(any(feature = "cranelift", feature = "winch"))] append_bti(&self, obj: &mut Object<'_>)727 pub(crate) fn append_bti(&self, obj: &mut Object<'_>) { 728 let section = obj.add_section( 729 obj.segment_name(StandardSegment::Data).to_vec(), 730 wasmtime_environ::obj::ELF_WASM_BTI.as_bytes().to_vec(), 731 object::SectionKind::ReadOnlyData, 732 ); 733 let contents = if self 734 .compiler() 735 .is_some_and(|c| c.is_branch_protection_enabled()) 736 { 737 1 738 } else { 739 0 740 }; 741 obj.append_section_data(section, &[contents], 1); 742 } 743 } 744 745 /// Return value from the [`Engine::detect_precompiled`] API. 746 #[derive(PartialEq, Eq, Copy, Clone, Debug)] 747 pub enum Precompiled { 748 /// The input bytes look like a precompiled core wasm module. 749 Module, 750 /// The input bytes look like a precompiled wasm component. 751 Component, 752 } 753 754 #[cfg(feature = "runtime")] 755 impl Engine { 756 /// Eagerly initialize thread-local functionality shared by all [`Engine`]s. 757 /// 758 /// Wasmtime's implementation on some platforms may involve per-thread 759 /// setup that needs to happen whenever WebAssembly is invoked. This setup 760 /// can take on the order of a few hundred microseconds, whereas the 761 /// overhead of calling WebAssembly is otherwise on the order of a few 762 /// nanoseconds. This setup cost is paid once per-OS-thread. If your 763 /// application is sensitive to the latencies of WebAssembly function 764 /// calls, even those that happen first on a thread, then this function 765 /// can be used to improve the consistency of each call into WebAssembly 766 /// by explicitly frontloading the cost of the one-time setup per-thread. 767 /// 768 /// Note that this function is not required to be called in any embedding. 769 /// Wasmtime will automatically initialize thread-local-state as necessary 770 /// on calls into WebAssembly. This is provided for use cases where the 771 /// latency of WebAssembly calls are extra-important, which is not 772 /// necessarily true of all embeddings. tls_eager_initialize()773 pub fn tls_eager_initialize() { 774 crate::runtime::vm::tls_eager_initialize(); 775 } 776 777 /// Returns a [`PoolingAllocatorMetrics`](crate::PoolingAllocatorMetrics) if 778 /// this engine was configured with 779 /// [`InstanceAllocationStrategy::Pooling`](crate::InstanceAllocationStrategy::Pooling). 780 #[cfg(feature = "pooling-allocator")] pooling_allocator_metrics(&self) -> Option<crate::vm::PoolingAllocatorMetrics>781 pub fn pooling_allocator_metrics(&self) -> Option<crate::vm::PoolingAllocatorMetrics> { 782 crate::runtime::vm::PoolingAllocatorMetrics::new(self) 783 } 784 allocator(&self) -> &dyn crate::runtime::vm::InstanceAllocator785 pub(crate) fn allocator(&self) -> &dyn crate::runtime::vm::InstanceAllocator { 786 let r: &(dyn crate::runtime::vm::InstanceAllocator + Send + Sync) = 787 self.inner.allocator.as_ref(); 788 &*r 789 } 790 gc_runtime(&self) -> Option<&Arc<dyn GcRuntime>>791 pub(crate) fn gc_runtime(&self) -> Option<&Arc<dyn GcRuntime>> { 792 self.inner.gc_runtime.as_ref() 793 } 794 profiler(&self) -> &dyn crate::profiling_agent::ProfilingAgent795 pub(crate) fn profiler(&self) -> &dyn crate::profiling_agent::ProfilingAgent { 796 self.inner.profiler.as_ref() 797 } 798 799 #[cfg(all(feature = "cache", any(feature = "cranelift", feature = "winch")))] cache(&self) -> Option<&wasmtime_cache::Cache>800 pub(crate) fn cache(&self) -> Option<&wasmtime_cache::Cache> { 801 self.config().cache.as_ref() 802 } 803 signatures(&self) -> &TypeRegistry804 pub(crate) fn signatures(&self) -> &TypeRegistry { 805 &self.inner.signatures 806 } 807 808 #[cfg(feature = "runtime")] custom_code_memory(&self) -> Option<&Arc<dyn CustomCodeMemory>>809 pub(crate) fn custom_code_memory(&self) -> Option<&Arc<dyn CustomCodeMemory>> { 810 self.config().custom_code_memory.as_ref() 811 } 812 813 #[cfg(target_has_atomic = "64")] epoch_counter(&self) -> &AtomicU64814 pub(crate) fn epoch_counter(&self) -> &AtomicU64 { 815 &self.inner.epoch 816 } 817 818 #[cfg(target_has_atomic = "64")] current_epoch(&self) -> u64819 pub(crate) fn current_epoch(&self) -> u64 { 820 self.epoch_counter().load(Ordering::Relaxed) 821 } 822 823 /// Increments the epoch. 824 /// 825 /// When using epoch-based interruption, currently-executing Wasm 826 /// code within this engine will trap or yield "soon" when the 827 /// epoch deadline is reached or exceeded. (The configuration, and 828 /// the deadline, are set on the `Store`.) The intent of the 829 /// design is for this method to be called by the embedder at some 830 /// regular cadence, for example by a thread that wakes up at some 831 /// interval, or by a signal handler. 832 /// 833 /// See [`Config::epoch_interruption`](crate::Config::epoch_interruption) 834 /// for an introduction to epoch-based interruption and pointers 835 /// to the other relevant methods. 836 /// 837 /// When performing `increment_epoch` in a separate thread, consider using 838 /// [`Engine::weak`] to hold an [`EngineWeak`](crate::EngineWeak) and 839 /// performing [`EngineWeak::upgrade`](crate::EngineWeak::upgrade) on each 840 /// tick, so that the epoch ticking thread does not keep an [`Engine`] alive 841 /// longer than any of its consumers. 842 /// 843 /// ## Signal Safety 844 /// 845 /// This method is signal-safe: it does not make any syscalls, and 846 /// performs only an atomic increment to the epoch value in 847 /// memory. 848 #[cfg(target_has_atomic = "64")] increment_epoch(&self)849 pub fn increment_epoch(&self) { 850 self.inner.epoch.fetch_add(1, Ordering::Relaxed); 851 } 852 853 /// Returns a [`std::hash::Hash`] that can be used to check precompiled WebAssembly compatibility. 854 /// 855 /// The outputs of [`Engine::precompile_module`] and [`Engine::precompile_component`] 856 /// are compatible with a different [`Engine`] instance only if the two engines use 857 /// compatible [`Config`]s. If this Hash matches between two [`Engine`]s then binaries 858 /// from one are guaranteed to deserialize in the other. 859 #[cfg(any(feature = "cranelift", feature = "winch"))] precompile_compatibility_hash(&self) -> impl std::hash::Hash + '_860 pub fn precompile_compatibility_hash(&self) -> impl std::hash::Hash + '_ { 861 crate::compile::HashedEngineCompileEnv(self) 862 } 863 864 /// Returns the required alignment for a code image, if we 865 /// allocate in a way that is not a system `mmap()` that naturally 866 /// aligns it. required_code_alignment(&self) -> usize867 fn required_code_alignment(&self) -> usize { 868 self.custom_code_memory() 869 .map(|c| c.required_alignment()) 870 .unwrap_or(1) 871 } 872 873 /// Loads a `CodeMemory` from the specified in-memory slice, copying it to a 874 /// uniquely owned mmap. 875 /// 876 /// The `expected` marker here is whether the bytes are expected to be a 877 /// precompiled module or a component. load_code_bytes( &self, bytes: &[u8], expected: ObjectKind, ) -> Result<Arc<crate::CodeMemory>>878 pub(crate) fn load_code_bytes( 879 &self, 880 bytes: &[u8], 881 expected: ObjectKind, 882 ) -> Result<Arc<crate::CodeMemory>> { 883 self.load_code( 884 crate::runtime::vm::MmapVec::from_slice_with_alignment( 885 bytes, 886 self.required_code_alignment(), 887 )?, 888 expected, 889 ) 890 } 891 892 /// Loads a `CodeMemory` from the specified memory region without copying 893 /// 894 /// The `expected` marker here is whether the bytes are expected to be 895 /// a precompiled module or a component. The `memory` provided is expected 896 /// to be a serialized module (.cwasm) generated by `[Module::serialize]` 897 /// or [`Engine::precompile_module] or their `Component` counterparts 898 /// [`Component::serialize`] or `[Engine::precompile_component]`. 899 /// 900 /// The memory provided is guaranteed to only be immutably by the runtime. 901 /// 902 /// # Safety 903 /// 904 /// As there is no copy here, the runtime will be making direct readonly use 905 /// of the provided memory. As such, outside writes to this memory region 906 /// will result in undefined and likely very undesirable behavior. load_code_raw( &self, memory: NonNull<[u8]>, expected: ObjectKind, ) -> Result<Arc<crate::CodeMemory>>907 pub(crate) unsafe fn load_code_raw( 908 &self, 909 memory: NonNull<[u8]>, 910 expected: ObjectKind, 911 ) -> Result<Arc<crate::CodeMemory>> { 912 // SAFETY: the contract of this function is the same as that of 913 // `from_raw`. 914 unsafe { self.load_code(crate::runtime::vm::MmapVec::from_raw(memory)?, expected) } 915 } 916 917 /// Like `load_code_bytes`, but creates a mmap from a file on disk. 918 #[cfg(feature = "std")] load_code_file( &self, file: File, expected: ObjectKind, ) -> Result<Arc<crate::CodeMemory>>919 pub(crate) fn load_code_file( 920 &self, 921 file: File, 922 expected: ObjectKind, 923 ) -> Result<Arc<crate::CodeMemory>> { 924 self.load_code( 925 crate::runtime::vm::MmapVec::from_file(file) 926 .with_context(|| "Failed to create file mapping".to_string())?, 927 expected, 928 ) 929 } 930 load_code( &self, mmap: crate::runtime::vm::MmapVec, expected: ObjectKind, ) -> Result<Arc<crate::CodeMemory>>931 pub(crate) fn load_code( 932 &self, 933 mmap: crate::runtime::vm::MmapVec, 934 expected: ObjectKind, 935 ) -> Result<Arc<crate::CodeMemory>> { 936 self.check_compatible_with_native_host() 937 .context("compilation settings are not compatible with the native host")?; 938 939 serialization::check_compatible(self, &mmap, expected)?; 940 let mut code = crate::CodeMemory::new(self, mmap)?; 941 code.publish()?; 942 Ok(try_new(code)?) 943 } 944 945 /// Unload process-related trap/signal handlers and destroy this engine. 946 /// 947 /// This method is not safe and is not widely applicable. It is not required 948 /// to be called and is intended for use cases such as unloading a dynamic 949 /// library from a process. It is difficult to invoke this method correctly 950 /// and it requires careful coordination to do so. 951 /// 952 /// # Panics 953 /// 954 /// This method will panic if this `Engine` handle is not the last remaining 955 /// engine handle. 956 /// 957 /// # Aborts 958 /// 959 /// This method will abort the process on some platforms in some situations 960 /// where unloading the handler cannot be performed and an unrecoverable 961 /// state is reached. For example on Unix platforms with signal handling 962 /// the process will be aborted if the current signal handlers are not 963 /// Wasmtime's. 964 /// 965 /// # Unsafety 966 /// 967 /// This method is not generally safe to call and has a number of 968 /// preconditions that must be met to even possibly be safe. Even with these 969 /// known preconditions met there may be other unknown invariants to uphold 970 /// as well. 971 /// 972 /// * There must be no other instances of `Engine` elsewhere in the process. 973 /// Note that this isn't just copies of this `Engine` but it's any other 974 /// `Engine` at all. This unloads global state that is used by all 975 /// `Engine`s so this instance must be the last. 976 /// 977 /// * On Unix platforms no other signal handlers could have been installed 978 /// for signals that Wasmtime catches. In this situation Wasmtime won't 979 /// know how to restore signal handlers that Wasmtime possibly overwrote 980 /// when Wasmtime was initially loaded. If possible initialize other 981 /// libraries first and then initialize Wasmtime last (e.g. defer creating 982 /// an `Engine`). 983 /// 984 /// * All existing threads which have used this DLL or copy of Wasmtime may 985 /// no longer use this copy of Wasmtime. Per-thread state is not iterated 986 /// and destroyed. Only future threads may use future instances of this 987 /// Wasmtime itself. 988 /// 989 /// If other crashes are seen from using this method please feel free to 990 /// file an issue to update the documentation here with more preconditions 991 /// that must be met. 992 #[cfg(has_native_signals)] unload_process_handlers(self)993 pub unsafe fn unload_process_handlers(self) { 994 assert_eq!(Arc::weak_count(&self.inner), 0); 995 assert_eq!(Arc::strong_count(&self.inner), 1); 996 997 // SAFETY: the contract of this function is the same as `deinit_traps`. 998 #[cfg(not(miri))] 999 unsafe { 1000 crate::runtime::vm::deinit_traps(); 1001 } 1002 } 1003 } 1004 1005 /// A weak reference to an [`Engine`]. 1006 #[derive(Clone)] 1007 pub struct EngineWeak { 1008 inner: alloc::sync::Weak<EngineInner>, 1009 } 1010 1011 impl EngineWeak { 1012 /// Upgrade this weak reference into an [`Engine`]. Returns `None` if 1013 /// strong references (the [`Engine`] type itself) no longer exist. upgrade(&self) -> Option<Engine>1014 pub fn upgrade(&self) -> Option<Engine> { 1015 alloc::sync::Weak::upgrade(&self.inner).map(|inner| Engine { inner }) 1016 } 1017 } 1018