config.rs - source (original) (raw)
wasmtime/
config.rs
1use crate::prelude::*;
2use alloc::sync::Arc;
3use bitflags::Flags;
4use core::fmt;
5use core::str::FromStr;
6#[cfg(any(feature = "cache", feature = "cranelift", feature = "winch"))]
7use std::path::Path;
8use wasmparser::WasmFeatures;
9use wasmtime_environ::{ConfigTunables, TripleExt, Tunables};
10
11#[cfg(feature = "runtime")]
12use crate::memory::MemoryCreator;
13#[cfg(feature = "runtime")]
14use crate::profiling_agent::{self, ProfilingAgent};
15#[cfg(feature = "runtime")]
16use crate::runtime::vm::{
17 GcRuntime, InstanceAllocator, OnDemandInstanceAllocator, RuntimeMemoryCreator,
18};
19#[cfg(feature = "runtime")]
20use crate::trampoline::MemoryCreatorProxy;
21
22#[cfg(feature = "async")]
23use crate::stack::{StackCreator, StackCreatorProxy};
24#[cfg(feature = "async")]
25use wasmtime_fiber::RuntimeFiberStackCreator;
26
27#[cfg(feature = "runtime")]
28pub use crate::runtime::code_memory::CustomCodeMemory;
29#[cfg(feature = "cache")]
30pub use wasmtime_cache::{Cache, CacheConfig};
31#[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
32pub use wasmtime_environ::CacheStore;
33
34/// Represents the module instance allocation strategy to use.
35#[derive(Clone)]
36#[non_exhaustive]
37pub enum InstanceAllocationStrategy {
38 /// The on-demand instance allocation strategy.
39 ///
40 /// Resources related to a module instance are allocated at instantiation time and
41 /// immediately deallocated when the `Store` referencing the instance is dropped.
42 ///
43 /// This is the default allocation strategy for Wasmtime.
44 OnDemand,
45 /// The pooling instance allocation strategy.
46 ///
47 /// A pool of resources is created in advance and module instantiation reuses resources
48 /// from the pool. Resources are returned to the pool when the `Store` referencing the instance
49 /// is dropped.
50 #[cfg(feature = "pooling-allocator")]
51 Pooling(PoolingAllocationConfig),
52}
53
54impl InstanceAllocationStrategy {
55 /// The default pooling instance allocation strategy.
56 #[cfg(feature = "pooling-allocator")]
57 pub fn pooling() -> Self {
58 Self::Pooling(Default::default())
59 }
60}
61
62impl Default for InstanceAllocationStrategy {
63 fn default() -> Self {
64 Self::OnDemand
65 }
66}
67
68#[cfg(feature = "pooling-allocator")]
69impl From<PoolingAllocationConfig> for InstanceAllocationStrategy {
70 fn from(cfg: PoolingAllocationConfig) -> InstanceAllocationStrategy {
71 InstanceAllocationStrategy::Pooling(cfg)
72 }
73}
74
75#[derive(Clone)]
76/// Configure the strategy used for versioning in serializing and deserializing [`crate::Module`].
77pub enum ModuleVersionStrategy {
78 /// Use the wasmtime crate's Cargo package version.
79 WasmtimeVersion,
80 /// Use a custom version string. Must be at most 255 bytes.
81 Custom(String),
82 /// Emit no version string in serialization, and accept all version strings in deserialization.
83 None,
84}
85
86impl Default for ModuleVersionStrategy {
87 fn default() -> Self {
88 ModuleVersionStrategy::WasmtimeVersion
89 }
90}
91
92impl core::hash::Hash for ModuleVersionStrategy {
93 fn hash<H: core::hash::Hasher>(&self, hasher: &mut H) {
94 match self {
95 Self::WasmtimeVersion => env!("CARGO_PKG_VERSION").hash(hasher),
96 Self::Custom(s) => s.hash(hasher),
97 Self::None => {}
98 };
99 }
100}
101
102/// Global configuration options used to create an [`Engine`](crate::Engine)
103/// and customize its behavior.
104///
105/// This structure exposed a builder-like interface and is primarily consumed by
106/// [`Engine::new()`](crate::Engine::new).
107///
108/// The validation of `Config` is deferred until the engine is being built, thus
109/// a problematic config may cause `Engine::new` to fail.
110///
111/// # Defaults
112///
113/// The `Default` trait implementation and the return value from
114/// [`Config::new()`] are the same and represent the default set of
115/// configuration for an engine. The exact set of defaults will differ based on
116/// properties such as enabled Cargo features at compile time and the configured
117/// target (see [`Config::target`]). Configuration options document their
118/// default values and what the conditional value of the default is where
119/// applicable.
120#[derive(Clone)]
121pub struct Config {
122 #[cfg(any(feature = "cranelift", feature = "winch"))]
123 compiler_config: CompilerConfig,
124 target: Option<target_lexicon::Triple>,
125 #[cfg(feature = "gc")]
126 collector: Collector,
127 profiling_strategy: ProfilingStrategy,
128 tunables: ConfigTunables,
129
130 #[cfg(feature = "cache")]
131 pub(crate) cache: Option<Cache>,
132 #[cfg(feature = "runtime")]
133 pub(crate) mem_creator: Option<Arc<dyn RuntimeMemoryCreator>>,
134 #[cfg(feature = "runtime")]
135 pub(crate) custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
136 pub(crate) allocation_strategy: InstanceAllocationStrategy,
137 pub(crate) max_wasm_stack: usize,
138 /// Explicitly enabled features via `Config::wasm_*` methods. This is a
139 /// signal that the embedder specifically wants something turned on
140 /// regardless of the defaults that Wasmtime might otherwise have enabled.
141 ///
142 /// Note that this, and `disabled_features` below, start as the empty set of
143 /// features to only track explicit user requests.
144 pub(crate) enabled_features: WasmFeatures,
145 /// Same as `enabled_features`, but for those that are explicitly disabled.
146 pub(crate) disabled_features: WasmFeatures,
147 pub(crate) wasm_backtrace: bool,
148 pub(crate) wasm_backtrace_details_env_used: bool,
149 pub(crate) native_unwind_info: Option<bool>,
150 #[cfg(any(feature = "async", feature = "stack-switching"))]
151 pub(crate) async_stack_size: usize,
152 #[cfg(feature = "async")]
153 pub(crate) async_stack_zeroing: bool,
154 #[cfg(feature = "async")]
155 pub(crate) stack_creator: Option<Arc<dyn RuntimeFiberStackCreator>>,
156 pub(crate) async_support: bool,
157 pub(crate) module_version: ModuleVersionStrategy,
158 pub(crate) parallel_compilation: bool,
159 pub(crate) memory_guaranteed_dense_image_size: u64,
160 pub(crate) force_memory_init_memfd: bool,
161 pub(crate) wmemcheck: bool,
162 #[cfg(feature = "coredump")]
163 pub(crate) coredump_on_trap: bool,
164 pub(crate) macos_use_mach_ports: bool,
165 pub(crate) detect_host_feature: Option<fn(&str) -> Option<bool>>,
166}
167
168/// User-provided configuration for the compiler.
169#[cfg(any(feature = "cranelift", feature = "winch"))]
170#[derive(Debug, Clone)]
171struct CompilerConfig {
172 strategy: Option<Strategy>,
173 settings: crate::hash_map::HashMap<String, String>,
174 flags: crate::hash_set::HashSet<String>,
175 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
176 cache_store: Option<Arc<dyn CacheStore>>,
177 clif_dir: Option<std::path::PathBuf>,
178 wmemcheck: bool,
179}
180
181#[cfg(any(feature = "cranelift", feature = "winch"))]
182impl CompilerConfig {
183 fn new() -> Self {
184 Self {
185 strategy: Strategy::Auto.not_auto(),
186 settings: Default::default(),
187 flags: Default::default(),
188 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
189 cache_store: None,
190 clif_dir: None,
191 wmemcheck: false,
192 }
193 }
194
195 /// Ensures that the key is not set or equals to the given value.
196 /// If the key is not set, it will be set to the given value.
197 ///
198 /// # Returns
199 ///
200 /// Returns true if successfully set or already had the given setting
201 /// value, or false if the setting was explicitly set to something
202 /// else previously.
203 fn ensure_setting_unset_or_given(&mut self, k: &str, v: &str) -> bool {
204 if let Some(value) = self.settings.get(k) {
205 if value != v {
206 return false;
207 }
208 } else {
209 self.settings.insert(k.to_string(), v.to_string());
210 }
211 true
212 }
213}
214
215#[cfg(any(feature = "cranelift", feature = "winch"))]
216impl Default for CompilerConfig {
217 fn default() -> Self {
218 Self::new()
219 }
220}
221
222impl Config {
223 /// Creates a new configuration object with the default configuration
224 /// specified.
225 pub fn new() -> Self {
226 let mut ret = Self {
227 tunables: ConfigTunables::default(),
228 #[cfg(any(feature = "cranelift", feature = "winch"))]
229 compiler_config: CompilerConfig::default(),
230 target: None,
231 #[cfg(feature = "gc")]
232 collector: Collector::default(),
233 #[cfg(feature = "cache")]
234 cache: None,
235 profiling_strategy: ProfilingStrategy::None,
236 #[cfg(feature = "runtime")]
237 mem_creator: None,
238 #[cfg(feature = "runtime")]
239 custom_code_memory: None,
240 allocation_strategy: InstanceAllocationStrategy::OnDemand,
241 // 512k of stack -- note that this is chosen currently to not be too
242 // big, not be too small, and be a good default for most platforms.
243 // One platform of particular note is Windows where the stack size
244 // of the main thread seems to, by default, be smaller than that of
245 // Linux and macOS. This 512k value at least lets our current test
246 // suite pass on the main thread of Windows (using `--test-threads
247 // 1` forces this), or at least it passed when this change was
248 // committed.
249 max_wasm_stack: 512 * 1024,
250 wasm_backtrace: true,
251 wasm_backtrace_details_env_used: false,
252 native_unwind_info: None,
253 enabled_features: WasmFeatures::empty(),
254 disabled_features: WasmFeatures::empty(),
255 #[cfg(any(feature = "async", feature = "stack-switching"))]
256 async_stack_size: 2 << 20,
257 #[cfg(feature = "async")]
258 async_stack_zeroing: false,
259 #[cfg(feature = "async")]
260 stack_creator: None,
261 async_support: false,
262 module_version: ModuleVersionStrategy::default(),
263 parallel_compilation: !cfg!(miri),
264 memory_guaranteed_dense_image_size: 16 << 20,
265 force_memory_init_memfd: false,
266 wmemcheck: false,
267 #[cfg(feature = "coredump")]
268 coredump_on_trap: false,
269 macos_use_mach_ports: !cfg!(miri),
270 #[cfg(feature = "std")]
271 detect_host_feature: Some(detect_host_feature),
272 #[cfg(not(feature = "std"))]
273 detect_host_feature: None,
274 };
275 #[cfg(any(feature = "cranelift", feature = "winch"))]
276 {
277 ret.cranelift_debug_verifier(false);
278 ret.cranelift_opt_level(OptLevel::Speed);
279
280 // When running under MIRI try to optimize for compile time of wasm
281 // code itself as much as possible. Disable optimizations by
282 // default.
283 if cfg!(miri) {
284 ret.cranelift_opt_level(OptLevel::None);
285 }
286 }
287
288 ret.wasm_backtrace_details(WasmBacktraceDetails::Environment);
289
290 ret
291 }
292
293 /// Configures the target platform of this [`Config`].
294 ///
295 /// This method is used to configure the output of compilation in an
296 /// [`Engine`](crate::Engine). This can be used, for example, to
297 /// cross-compile from one platform to another. By default, the host target
298 /// triple is used meaning compiled code is suitable to run on the host.
299 ///
300 /// Note that the [`Module`](crate::Module) type can only be created if the
301 /// target configured here matches the host. Otherwise if a cross-compile is
302 /// being performed where the host doesn't match the target then
303 /// [`Engine::precompile_module`](crate::Engine::precompile_module) must be
304 /// used instead.
305 ///
306 /// Target-specific flags (such as CPU features) will not be inferred by
307 /// default for the target when one is provided here. This means that this
308 /// can also be used, for example, with the host architecture to disable all
309 /// host-inferred feature flags. Configuring target-specific flags can be
310 /// done with [`Config::cranelift_flag_set`] and
311 /// [`Config::cranelift_flag_enable`].
312 ///
313 /// # Errors
314 ///
315 /// This method will error if the given target triple is not supported.
316 pub fn target(&mut self, target: &str) -> Result<&mut Self> {
317 self.target =
318 Some(target_lexicon::Triple::from_str(target).map_err(|e| anyhow::anyhow!(e))?);
319
320 Ok(self)
321 }
322
323 /// Enables the incremental compilation cache in Cranelift, using the provided `CacheStore`
324 /// backend for storage.
325 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
326 pub fn enable_incremental_compilation(
327 &mut self,
328 cache_store: Arc<dyn CacheStore>,
329 ) -> Result<&mut Self> {
330 self.compiler_config.cache_store = Some(cache_store);
331 Ok(self)
332 }
333
334 /// Whether or not to enable support for asynchronous functions in Wasmtime.
335 ///
336 /// When enabled, the config can optionally define host functions with `async`.
337 /// Instances created and functions called with this `Config` *must* be called
338 /// through their asynchronous APIs, however. For example using
339 /// [`Func::call`](crate::Func::call) will panic when used with this config.
340 ///
341 /// # Asynchronous Wasm
342 ///
343 /// WebAssembly does not currently have a way to specify at the bytecode
344 /// level what is and isn't async. Host-defined functions, however, may be
345 /// defined as `async`. WebAssembly imports always appear synchronous, which
346 /// gives rise to a bit of an impedance mismatch here. To solve this
347 /// Wasmtime supports "asynchronous configs" which enables calling these
348 /// asynchronous functions in a way that looks synchronous to the executing
349 /// WebAssembly code.
350 ///
351 /// An asynchronous config must always invoke wasm code asynchronously,
352 /// meaning we'll always represent its computation as a
353 /// [`Future`](std::future::Future). The `poll` method of the futures
354 /// returned by Wasmtime will perform the actual work of calling the
355 /// WebAssembly. Wasmtime won't manage its own thread pools or similar,
356 /// that's left up to the embedder.
357 ///
358 /// To implement futures in a way that WebAssembly sees asynchronous host
359 /// functions as synchronous, all async Wasmtime futures will execute on a
360 /// separately allocated native stack from the thread otherwise executing
361 /// Wasmtime. This separate native stack can then be switched to and from.
362 /// Using this whenever an `async` host function returns a future that
363 /// resolves to `Pending` we switch away from the temporary stack back to
364 /// the main stack and propagate the `Pending` status.
365 ///
366 /// In general it's encouraged that the integration with `async` and
367 /// wasmtime is designed early on in your embedding of Wasmtime to ensure
368 /// that it's planned that WebAssembly executes in the right context of your
369 /// application.
370 ///
371 /// # Execution in `poll`
372 ///
373 /// The [`Future::poll`](std::future::Future::poll) method is the main
374 /// driving force behind Rust's futures. That method's own documentation
375 /// states "an implementation of `poll` should strive to return quickly, and
376 /// should not block". This, however, can be at odds with executing
377 /// WebAssembly code as part of the `poll` method itself. If your
378 /// WebAssembly is untrusted then this could allow the `poll` method to take
379 /// arbitrarily long in the worst case, likely blocking all other
380 /// asynchronous tasks.
381 ///
382 /// To remedy this situation you have a few possible ways to solve this:
383 ///
384 /// * The most efficient solution is to enable
385 /// [`Config::epoch_interruption`] in conjunction with
386 /// [`crate::Store::epoch_deadline_async_yield_and_update`]. Coupled with
387 /// periodic calls to [`crate::Engine::increment_epoch`] this will cause
388 /// executing WebAssembly to periodically yield back according to the
389 /// epoch configuration settings. This enables `Future::poll` to take at
390 /// most a certain amount of time according to epoch configuration
391 /// settings and when increments happen. The benefit of this approach is
392 /// that the instrumentation in compiled code is quite lightweight, but a
393 /// downside can be that the scheduling is somewhat nondeterministic since
394 /// increments are usually timer-based which are not always deterministic.
395 ///
396 /// Note that to prevent infinite execution of wasm it's recommended to
397 /// place a timeout on the entire future representing executing wasm code
398 /// and the periodic yields with epochs should ensure that when the
399 /// timeout is reached it's appropriately recognized.
400 ///
401 /// * Alternatively you can enable the
402 /// [`Config::consume_fuel`](crate::Config::consume_fuel) method as well
403 /// as [`crate::Store::fuel_async_yield_interval`] When doing so this will
404 /// configure Wasmtime futures to yield periodically while they're
405 /// executing WebAssembly code. After consuming the specified amount of
406 /// fuel wasm futures will return `Poll::Pending` from their `poll`
407 /// method, and will get automatically re-polled later. This enables the
408 /// `Future::poll` method to take roughly a fixed amount of time since
409 /// fuel is guaranteed to get consumed while wasm is executing. Unlike
410 /// epoch-based preemption this is deterministic since wasm always
411 /// consumes a fixed amount of fuel per-operation. The downside of this
412 /// approach, however, is that the compiled code instrumentation is
413 /// significantly more expensive than epoch checks.
414 ///
415 /// Note that to prevent infinite execution of wasm it's recommended to
416 /// place a timeout on the entire future representing executing wasm code
417 /// and the periodic yields with epochs should ensure that when the
418 /// timeout is reached it's appropriately recognized.
419 ///
420 /// In all cases special care needs to be taken when integrating
421 /// asynchronous wasm into your application. You should carefully plan where
422 /// WebAssembly will execute and what compute resources will be allotted to
423 /// it. If Wasmtime doesn't support exactly what you'd like just yet, please
424 /// feel free to open an issue!
425 #[cfg(feature = "async")]
426 pub fn async_support(&mut self, enable: bool) -> &mut Self {
427 self.async_support = enable;
428 self
429 }
430
431 /// Configures whether DWARF debug information will be emitted during
432 /// compilation.
433 ///
434 /// Note that the `debug-builtins` compile-time Cargo feature must also be
435 /// enabled for native debuggers such as GDB or LLDB to be able to debug
436 /// guest WebAssembly programs.
437 ///
438 /// By default this option is `false`.
439 /// **Note** Enabling this option is not compatible with the Winch compiler.
440 pub fn debug_info(&mut self, enable: bool) -> &mut Self {
441 self.tunables.generate_native_debuginfo = Some(enable);
442 self
443 }
444
445 /// Configures whether [`WasmBacktrace`] will be present in the context of
446 /// errors returned from Wasmtime.
447 ///
448 /// A backtrace may be collected whenever an error is returned from a host
449 /// function call through to WebAssembly or when WebAssembly itself hits a
450 /// trap condition, such as an out-of-bounds memory access. This flag
451 /// indicates, in these conditions, whether the backtrace is collected or
452 /// not.
453 ///
454 /// Currently wasm backtraces are implemented through frame pointer walking.
455 /// This means that collecting a backtrace is expected to be a fast and
456 /// relatively cheap operation. Additionally backtrace collection is
457 /// suitable in concurrent environments since one thread capturing a
458 /// backtrace won't block other threads.
459 ///
460 /// Collected backtraces are attached via [`anyhow::Error::context`] to
461 /// errors returned from host functions. The [`WasmBacktrace`] type can be
462 /// acquired via [`anyhow::Error::downcast_ref`] to inspect the backtrace.
463 /// When this option is disabled then this context is never applied to
464 /// errors coming out of wasm.
465 ///
466 /// This option is `true` by default.
467 ///
468 /// [`WasmBacktrace`]: crate::WasmBacktrace
469 pub fn wasm_backtrace(&mut self, enable: bool) -> &mut Self {
470 self.wasm_backtrace = enable;
471 self
472 }
473
474 /// Configures whether backtraces in `Trap` will parse debug info in the wasm file to
475 /// have filename/line number information.
476 ///
477 /// When enabled this will causes modules to retain debugging information
478 /// found in wasm binaries. This debug information will be used when a trap
479 /// happens to symbolicate each stack frame and attempt to print a
480 /// filename/line number for each wasm frame in the stack trace.
481 ///
482 /// By default this option is `WasmBacktraceDetails::Environment`, meaning
483 /// that wasm will read `WASMTIME_BACKTRACE_DETAILS` to indicate whether
484 /// details should be parsed. Note that the `std` feature of this crate must
485 /// be active to read environment variables, otherwise this is disabled by
486 /// default.
487 pub fn wasm_backtrace_details(&mut self, enable: WasmBacktraceDetails) -> &mut Self {
488 self.wasm_backtrace_details_env_used = false;
489 self.tunables.parse_wasm_debuginfo = match enable {
490 WasmBacktraceDetails::Enable => Some(true),
491 WasmBacktraceDetails::Disable => Some(false),
492 WasmBacktraceDetails::Environment => {
493 #[cfg(feature = "std")]
494 {
495 self.wasm_backtrace_details_env_used = true;
496 std::env::var("WASMTIME_BACKTRACE_DETAILS")
497 .map(|s| Some(s == "1"))
498 .unwrap_or(Some(false))
499 }
500 #[cfg(not(feature = "std"))]
501 {
502 Some(false)
503 }
504 }
505 };
506 self
507 }
508
509 /// Configures whether to generate native unwind information
510 /// (e.g. `.eh_frame` on Linux).
511 ///
512 /// This configuration option only exists to help third-party stack
513 /// capturing mechanisms, such as the system's unwinder or the `backtrace`
514 /// crate, determine how to unwind through Wasm frames. It does not affect
515 /// whether Wasmtime can capture Wasm backtraces or not. The presence of
516 /// [`WasmBacktrace`] is controlled by the [`Config::wasm_backtrace`]
517 /// option.
518 ///
519 /// Native unwind information is included:
520 /// - When targeting Windows, since the Windows ABI requires it.
521 /// - By default.
522 ///
523 /// Note that systems loading many modules may wish to disable this
524 /// configuration option instead of leaving it on-by-default. Some platforms
525 /// exhibit quadratic behavior when registering/unregistering unwinding
526 /// information which can greatly slow down the module loading/unloading
527 /// process.
528 ///
529 /// [`WasmBacktrace`]: crate::WasmBacktrace
530 pub fn native_unwind_info(&mut self, enable: bool) -> &mut Self {
531 self.native_unwind_info = Some(enable);
532 self
533 }
534
535 /// Configures whether execution of WebAssembly will "consume fuel" to
536 /// either halt or yield execution as desired.
537 ///
538 /// This can be used to deterministically prevent infinitely-executing
539 /// WebAssembly code by instrumenting generated code to consume fuel as it
540 /// executes. When fuel runs out a trap is raised, however [`Store`] can be
541 /// configured to yield execution periodically via
542 /// [`crate::Store::fuel_async_yield_interval`].
543 ///
544 /// Note that a [`Store`] starts with no fuel, so if you enable this option
545 /// you'll have to be sure to pour some fuel into [`Store`] before
546 /// executing some code.
547 ///
548 /// By default this option is `false`.
549 ///
550 /// **Note** Enabling this option is not compatible with the Winch compiler.
551 ///
552 /// [`Store`]: crate::Store
553 pub fn consume_fuel(&mut self, enable: bool) -> &mut Self {
554 self.tunables.consume_fuel = Some(enable);
555 self
556 }
557
558 /// Enables epoch-based interruption.
559 ///
560 /// When executing code in async mode, we sometimes want to
561 /// implement a form of cooperative timeslicing: long-running Wasm
562 /// guest code should periodically yield to the executor
563 /// loop. This yielding could be implemented by using "fuel" (see
564 /// [`consume_fuel`](Config::consume_fuel)). However, fuel
565 /// instrumentation is somewhat expensive: it modifies the
566 /// compiled form of the Wasm code so that it maintains a precise
567 /// instruction count, frequently checking this count against the
568 /// remaining fuel. If one does not need this precise count or
569 /// deterministic interruptions, and only needs a periodic
570 /// interrupt of some form, then It would be better to have a more
571 /// lightweight mechanism.
572 ///
573 /// Epoch-based interruption is that mechanism. There is a global
574 /// "epoch", which is a counter that divides time into arbitrary
575 /// periods (or epochs). This counter lives on the
576 /// [`Engine`](crate::Engine) and can be incremented by calling
577 /// [`Engine::increment_epoch`](crate::Engine::increment_epoch).
578 /// Epoch-based instrumentation works by setting a "deadline
579 /// epoch". The compiled code knows the deadline, and at certain
580 /// points, checks the current epoch against that deadline. It
581 /// will yield if the deadline has been reached.
582 ///
583 /// The idea is that checking an infrequently-changing counter is
584 /// cheaper than counting and frequently storing a precise metric
585 /// (instructions executed) locally. The interruptions are not
586 /// deterministic, but if the embedder increments the epoch in a
587 /// periodic way (say, every regular timer tick by a thread or
588 /// signal handler), then we can ensure that all async code will
589 /// yield to the executor within a bounded time.
590 ///
591 /// The deadline check cannot be avoided by malicious wasm code. It is safe
592 /// to use epoch deadlines to limit the execution time of untrusted
593 /// code.
594 ///
595 /// The [`Store`](crate::Store) tracks the deadline, and controls
596 /// what happens when the deadline is reached during
597 /// execution. Several behaviors are possible:
598 ///
599 /// - Trap if code is executing when the epoch deadline is
600 /// met. See
601 /// [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap).
602 ///
603 /// - Call an arbitrary function. This function may chose to trap or
604 /// increment the epoch. See
605 /// [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback).
606 ///
607 /// - Yield to the executor loop, then resume when the future is
608 /// next polled. See
609 /// [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update).
610 ///
611 /// Trapping is the default. The yielding behaviour may be used for
612 /// the timeslicing behavior described above.
613 ///
614 /// This feature is available with or without async support.
615 /// However, without async support, the timeslicing behaviour is
616 /// not available. This means epoch-based interruption can only
617 /// serve as a simple external-interruption mechanism.
618 ///
619 /// An initial deadline must be set before executing code by calling
620 /// [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline). If this
621 /// deadline is not configured then wasm will immediately trap.
622 ///
623 /// ## Interaction with blocking host calls
624 ///
625 /// Epochs (and fuel) do not assist in handling WebAssembly code blocked in
626 /// a call to the host. For example if the WebAssembly function calls
627 /// `wasi:io/poll/poll` to sleep epochs will not assist in waking this up or
628 /// timing it out. Epochs intentionally only affect running WebAssembly code
629 /// itself and it's left to the embedder to determine how best to wake up
630 /// indefinitely blocking code in the host.
631 ///
632 /// The typical solution for this, however, is to use
633 /// [`Config::async_support(true)`](Config::async_support) and the `async`
634 /// variant of WASI host functions. This models computation as a Rust
635 /// `Future` which means that when blocking happens the future is only
636 /// suspended and control yields back to the main event loop. This gives the
637 /// embedder the opportunity to use `tokio::time::timeout` for example on a
638 /// wasm computation and have the desired effect of cancelling a blocking
639 /// operation when a timeout expires.
640 ///
641 /// ## When to use fuel vs. epochs
642 ///
643 /// In general, epoch-based interruption results in faster
644 /// execution. This difference is sometimes significant: in some
645 /// measurements, up to 2-3x. This is because epoch-based
646 /// interruption does less work: it only watches for a global
647 /// rarely-changing counter to increment, rather than keeping a
648 /// local frequently-changing counter and comparing it to a
649 /// deadline.
650 ///
651 /// Fuel, in contrast, should be used when *deterministic*
652 /// yielding or trapping is needed. For example, if it is required
653 /// that the same function call with the same starting state will
654 /// always either complete or trap with an out-of-fuel error,
655 /// deterministically, then fuel with a fixed bound should be
656 /// used.
657 ///
658 /// **Note** Enabling this option is not compatible with the Winch compiler.
659 ///
660 /// # See Also
661 ///
662 /// - [`Engine::increment_epoch`](crate::Engine::increment_epoch)
663 /// - [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline)
664 /// - [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap)
665 /// - [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback)
666 /// - [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update)
667 pub fn epoch_interruption(&mut self, enable: bool) -> &mut Self {
668 self.tunables.epoch_interruption = Some(enable);
669 self
670 }
671
672 /// Configures the maximum amount of stack space available for
673 /// executing WebAssembly code.
674 ///
675 /// WebAssembly has well-defined semantics on stack overflow. This is
676 /// intended to be a knob which can help configure how much stack space
677 /// wasm execution is allowed to consume. Note that the number here is not
678 /// super-precise, but rather wasm will take at most "pretty close to this
679 /// much" stack space.
680 ///
681 /// If a wasm call (or series of nested wasm calls) take more stack space
682 /// than the `size` specified then a stack overflow trap will be raised.
683 ///
684 /// Caveat: this knob only limits the stack space consumed by wasm code.
685 /// More importantly, it does not ensure that this much stack space is
686 /// available on the calling thread stack. Exhausting the thread stack
687 /// typically leads to an **abort** of the process.
688 ///
689 /// Here are some examples of how that could happen:
690 ///
691 /// - Let's assume this option is set to 2 MiB and then a thread that has
692 /// a stack with 512 KiB left.
693 ///
694 /// If wasm code consumes more than 512 KiB then the process will be aborted.
695 ///
696 /// - Assuming the same conditions, but this time wasm code does not consume
697 /// any stack but calls into a host function. The host function consumes
698 /// more than 512 KiB of stack space. The process will be aborted.
699 ///
700 /// There's another gotcha related to recursive calling into wasm: the stack
701 /// space consumed by a host function is counted towards this limit. The
702 /// host functions are not prevented from consuming more than this limit.
703 /// However, if the host function that used more than this limit and called
704 /// back into wasm, then the execution will trap immediately because of
705 /// stack overflow.
706 ///
707 /// When the `async` feature is enabled, this value cannot exceed the
708 /// `async_stack_size` option. Be careful not to set this value too close
709 /// to `async_stack_size` as doing so may limit how much stack space
710 /// is available for host functions.
711 ///
712 /// By default this option is 512 KiB.
713 ///
714 /// # Errors
715 ///
716 /// The `Engine::new` method will fail if the `size` specified here is
717 /// either 0 or larger than the [`Config::async_stack_size`] configuration.
718 pub fn max_wasm_stack(&mut self, size: usize) -> &mut Self {
719 self.max_wasm_stack = size;
720 self
721 }
722
723 /// Configures the size of the stacks used for asynchronous execution.
724 ///
725 /// This setting configures the size of the stacks that are allocated for
726 /// asynchronous execution. The value cannot be less than `max_wasm_stack`.
727 ///
728 /// The amount of stack space guaranteed for host functions is
729 /// `async_stack_size - max_wasm_stack`, so take care not to set these two values
730 /// close to one another; doing so may cause host functions to overflow the
731 /// stack and abort the process.
732 ///
733 /// By default this option is 2 MiB.
734 ///
735 /// # Errors
736 ///
737 /// The `Engine::new` method will fail if the value for this option is
738 /// smaller than the [`Config::max_wasm_stack`] option.
739 #[cfg(any(feature = "async", feature = "stack-switching"))]
740 pub fn async_stack_size(&mut self, size: usize) -> &mut Self {
741 self.async_stack_size = size;
742 self
743 }
744
745 /// Configures whether or not stacks used for async futures are zeroed
746 /// before (re)use.
747 ///
748 /// When the [`async_support`](Config::async_support) method is enabled for
749 /// Wasmtime and the [`call_async`] variant of calling WebAssembly is used
750 /// then Wasmtime will create a separate runtime execution stack for each
751 /// future produced by [`call_async`]. By default upon allocation, depending
752 /// on the platform, these stacks might be filled with uninitialized
753 /// memory. This is safe and correct because, modulo bugs in Wasmtime,
754 /// compiled Wasm code will never read from a stack slot before it
755 /// initializes the stack slot.
756 ///
757 /// However, as a defense-in-depth mechanism, you may configure Wasmtime to
758 /// ensure that these stacks are zeroed before they are used. Notably, if
759 /// you are using the pooling allocator, stacks can be pooled and reused
760 /// across different Wasm guests; ensuring that stacks are zeroed can
761 /// prevent data leakage between Wasm guests even in the face of potential
762 /// read-of-stack-slot-before-initialization bugs in Wasmtime's compiler.
763 ///
764 /// Stack zeroing can be a costly operation in highly concurrent
765 /// environments due to modifications of the virtual address space requiring
766 /// process-wide synchronization. It can also be costly in `no-std`
767 /// environments that must manually zero memory, and cannot rely on an OS
768 /// and virtual memory to provide zeroed pages.
769 ///
770 /// This option defaults to `false`.
771 ///
772 /// [`call_async`]: crate::TypedFunc::call_async
773 #[cfg(feature = "async")]
774 pub fn async_stack_zeroing(&mut self, enable: bool) -> &mut Self {
775 self.async_stack_zeroing = enable;
776 self
777 }
778
779 fn wasm_feature(&mut self, flag: WasmFeatures, enable: bool) -> &mut Self {
780 self.enabled_features.set(flag, enable);
781 self.disabled_features.set(flag, !enable);
782 self
783 }
784
785 /// Configures whether the WebAssembly tail calls proposal will be enabled
786 /// for compilation or not.
787 ///
788 /// The [WebAssembly tail calls proposal] introduces the `return_call` and
789 /// `return_call_indirect` instructions. These instructions allow for Wasm
790 /// programs to implement some recursive algorithms with *O(1)* stack space
791 /// usage.
792 ///
793 /// This is `true` by default except when the Winch compiler is enabled.
794 ///
795 /// [WebAssembly tail calls proposal]: https://github.com/WebAssembly/tail-call
796 pub fn wasm_tail_call(&mut self, enable: bool) -> &mut Self {
797 self.wasm_feature(WasmFeatures::TAIL_CALL, enable);
798 self
799 }
800
801 /// Configures whether the WebAssembly custom-page-sizes proposal will be
802 /// enabled for compilation or not.
803 ///
804 /// The [WebAssembly custom-page-sizes proposal] allows a memory to
805 /// customize its page sizes. By default, Wasm page sizes are 64KiB
806 /// large. This proposal allows the memory to opt into smaller page sizes
807 /// instead, allowing Wasm to run in environments with less than 64KiB RAM
808 /// available, for example.
809 ///
810 /// Note that the page size is part of the memory's type, and because
811 /// different memories may have different types, they may also have
812 /// different page sizes.
813 ///
814 /// Currently the only valid page sizes are 64KiB (the default) and 1
815 /// byte. Future extensions may relax this constraint and allow all powers
816 /// of two.
817 ///
818 /// Support for this proposal is disabled by default.
819 ///
820 /// [WebAssembly custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
821 pub fn wasm_custom_page_sizes(&mut self, enable: bool) -> &mut Self {
822 self.wasm_feature(WasmFeatures::CUSTOM_PAGE_SIZES, enable);
823 self
824 }
825
826 /// Configures whether the WebAssembly [threads] proposal will be enabled
827 /// for compilation.
828 ///
829 /// This feature gates items such as shared memories and atomic
830 /// instructions. Note that the threads feature depends on the bulk memory
831 /// feature, which is enabled by default. Additionally note that while the
832 /// wasm feature is called "threads" it does not actually include the
833 /// ability to spawn threads. Spawning threads is part of the [wasi-threads]
834 /// proposal which is a separately gated feature in Wasmtime.
835 ///
836 /// Embeddings of Wasmtime are able to build their own custom threading
837 /// scheme on top of the core wasm threads proposal, however.
838 ///
839 /// The default value for this option is whether the `threads`
840 /// crate feature of Wasmtime is enabled or not. By default this crate
841 /// feature is enabled.
842 ///
843 /// [threads]: https://github.com/webassembly/threads
844 /// [wasi-threads]: https://github.com/webassembly/wasi-threads
845 #[cfg(feature = "threads")]
846 pub fn wasm_threads(&mut self, enable: bool) -> &mut Self {
847 self.wasm_feature(WasmFeatures::THREADS, enable);
848 self
849 }
850
851 /// Configures whether the WebAssembly [shared-everything-threads] proposal
852 /// will be enabled for compilation.
853 ///
854 /// This feature gates extended use of the `shared` attribute on items other
855 /// than memories, extra atomic instructions, and new component model
856 /// intrinsics for spawning threads. It depends on the
857 /// [`wasm_threads`][Self::wasm_threads] being enabled.
858 ///
859 /// [shared-everything-threads]:
860 /// https://github.com/webassembly/shared-everything-threads
861 pub fn wasm_shared_everything_threads(&mut self, enable: bool) -> &mut Self {
862 self.wasm_feature(WasmFeatures::SHARED_EVERYTHING_THREADS, enable);
863 self
864 }
865
866 /// Configures whether the [WebAssembly reference types proposal][proposal]
867 /// will be enabled for compilation.
868 ///
869 /// This feature gates items such as the `externref` and `funcref` types as
870 /// well as allowing a module to define multiple tables.
871 ///
872 /// Note that the reference types proposal depends on the bulk memory proposal.
873 ///
874 /// This feature is `true` by default.
875 ///
876 /// # Errors
877 ///
878 /// The validation of this feature are deferred until the engine is being built,
879 /// and thus may cause `Engine::new` fail if the `bulk_memory` feature is disabled.
880 ///
881 /// [proposal]: https://github.com/webassembly/reference-types
882 #[cfg(feature = "gc")]
883 pub fn wasm_reference_types(&mut self, enable: bool) -> &mut Self {
884 self.wasm_feature(WasmFeatures::REFERENCE_TYPES, enable);
885 self
886 }
887
888 /// Configures whether the [WebAssembly function references
889 /// proposal][proposal] will be enabled for compilation.
890 ///
891 /// This feature gates non-nullable reference types, function reference
892 /// types, `call_ref`, `ref.func`, and non-nullable reference related
893 /// instructions.
894 ///
895 /// Note that the function references proposal depends on the reference
896 /// types proposal.
897 ///
898 /// This feature is `false` by default.
899 ///
900 /// [proposal]: https://github.com/WebAssembly/function-references
901 #[cfg(feature = "gc")]
902 pub fn wasm_function_references(&mut self, enable: bool) -> &mut Self {
903 self.wasm_feature(WasmFeatures::FUNCTION_REFERENCES, enable);
904 self
905 }
906
907 /// Configures whether the [WebAssembly wide-arithmetic][proposal] will be
908 /// enabled for compilation.
909 ///
910 /// This feature is `false` by default.
911 ///
912 /// [proposal]: https://github.com/WebAssembly/wide-arithmetic
913 pub fn wasm_wide_arithmetic(&mut self, enable: bool) -> &mut Self {
914 self.wasm_feature(WasmFeatures::WIDE_ARITHMETIC, enable);
915 self
916 }
917
918 /// Configures whether the [WebAssembly Garbage Collection
919 /// proposal][proposal] will be enabled for compilation.
920 ///
921 /// This feature gates `struct` and `array` type definitions and references,
922 /// the `i31ref` type, and all related instructions.
923 ///
924 /// Note that the function references proposal depends on the typed function
925 /// references proposal.
926 ///
927 /// This feature is `false` by default.
928 ///
929 /// **Warning: Wasmtime's implementation of the GC proposal is still in
930 /// progress and generally not ready for primetime.**
931 ///
932 /// [proposal]: https://github.com/WebAssembly/gc
933 #[cfg(feature = "gc")]
934 pub fn wasm_gc(&mut self, enable: bool) -> &mut Self {
935 self.wasm_feature(WasmFeatures::GC, enable);
936 self
937 }
938
939 /// Configures whether the WebAssembly SIMD proposal will be
940 /// enabled for compilation.
941 ///
942 /// The [WebAssembly SIMD proposal][proposal]. This feature gates items such
943 /// as the `v128` type and all of its operators being in a module. Note that
944 /// this does not enable the [relaxed simd proposal].
945 ///
946 /// **Note**
947 ///
948 /// On x86_64 platforms the base CPU feature requirement for SIMD
949 /// is SSE2 for the Cranelift compiler and AVX for the Winch compiler.
950 ///
951 /// This is `true` by default.
952 ///
953 /// [proposal]: https://github.com/webassembly/simd
954 /// [relaxed simd proposal]: https://github.com/WebAssembly/relaxed-simd
955 pub fn wasm_simd(&mut self, enable: bool) -> &mut Self {
956 self.wasm_feature(WasmFeatures::SIMD, enable);
957 self
958 }
959
960 /// Configures whether the WebAssembly Relaxed SIMD proposal will be
961 /// enabled for compilation.
962 ///
963 /// The relaxed SIMD proposal adds new instructions to WebAssembly which,
964 /// for some specific inputs, are allowed to produce different results on
965 /// different hosts. More-or-less this proposal enables exposing
966 /// platform-specific semantics of SIMD instructions in a controlled
967 /// fashion to a WebAssembly program. From an embedder's perspective this
968 /// means that WebAssembly programs may execute differently depending on
969 /// whether the host is x86_64 or AArch64, for example.
970 ///
971 /// By default Wasmtime lowers relaxed SIMD instructions to the fastest
972 /// lowering for the platform it's running on. This means that, by default,
973 /// some relaxed SIMD instructions may have different results for the same
974 /// inputs across x86_64 and AArch64. This behavior can be disabled through
975 /// the [`Config::relaxed_simd_deterministic`] option which will force
976 /// deterministic behavior across all platforms, as classified by the
977 /// specification, at the cost of performance.
978 ///
979 /// This is `true` by default.
980 ///
981 /// [proposal]: https://github.com/webassembly/relaxed-simd
982 pub fn wasm_relaxed_simd(&mut self, enable: bool) -> &mut Self {
983 self.wasm_feature(WasmFeatures::RELAXED_SIMD, enable);
984 self
985 }
986
987 /// This option can be used to control the behavior of the [relaxed SIMD
988 /// proposal's][proposal] instructions.
989 ///
990 /// The relaxed SIMD proposal introduces instructions that are allowed to
991 /// have different behavior on different architectures, primarily to afford
992 /// an efficient implementation on all architectures. This means, however,
993 /// that the same module may execute differently on one host than another,
994 /// which typically is not otherwise the case. This option is provided to
995 /// force Wasmtime to generate deterministic code for all relaxed simd
996 /// instructions, at the cost of performance, for all architectures. When
997 /// this option is enabled then the deterministic behavior of all
998 /// instructions in the relaxed SIMD proposal is selected.
999 ///
1000 /// This is `false` by default.
1001 ///
1002 /// [proposal]: https://github.com/webassembly/relaxed-simd
1003 pub fn relaxed_simd_deterministic(&mut self, enable: bool) -> &mut Self {
1004 self.tunables.relaxed_simd_deterministic = Some(enable);
1005 self
1006 }
1007
1008 /// Configures whether the [WebAssembly bulk memory operations
1009 /// proposal][proposal] will be enabled for compilation.
1010 ///
1011 /// This feature gates items such as the `memory.copy` instruction, passive
1012 /// data/table segments, etc, being in a module.
1013 ///
1014 /// This is `true` by default.
1015 ///
1016 /// Feature `reference_types`, which is also `true` by default, requires
1017 /// this feature to be enabled. Thus disabling this feature must also disable
1018 /// `reference_types` as well using [`wasm_reference_types`](crate::Config::wasm_reference_types).
1019 ///
1020 /// # Errors
1021 ///
1022 /// Disabling this feature without disabling `reference_types` will cause
1023 /// `Engine::new` to fail.
1024 ///
1025 /// [proposal]: https://github.com/webassembly/bulk-memory-operations
1026 pub fn wasm_bulk_memory(&mut self, enable: bool) -> &mut Self {
1027 self.wasm_feature(WasmFeatures::BULK_MEMORY, enable);
1028 self
1029 }
1030
1031 /// Configures whether the WebAssembly multi-value [proposal] will
1032 /// be enabled for compilation.
1033 ///
1034 /// This feature gates functions and blocks returning multiple values in a
1035 /// module, for example.
1036 ///
1037 /// This is `true` by default.
1038 ///
1039 /// [proposal]: https://github.com/webassembly/multi-value
1040 pub fn wasm_multi_value(&mut self, enable: bool) -> &mut Self {
1041 self.wasm_feature(WasmFeatures::MULTI_VALUE, enable);
1042 self
1043 }
1044
1045 /// Configures whether the WebAssembly multi-memory [proposal] will
1046 /// be enabled for compilation.
1047 ///
1048 /// This feature gates modules having more than one linear memory
1049 /// declaration or import.
1050 ///
1051 /// This is `true` by default.
1052 ///
1053 /// [proposal]: https://github.com/webassembly/multi-memory
1054 pub fn wasm_multi_memory(&mut self, enable: bool) -> &mut Self {
1055 self.wasm_feature(WasmFeatures::MULTI_MEMORY, enable);
1056 self
1057 }
1058
1059 /// Configures whether the WebAssembly memory64 [proposal] will
1060 /// be enabled for compilation.
1061 ///
1062 /// Note that this the upstream specification is not finalized and Wasmtime
1063 /// may also have bugs for this feature since it hasn't been exercised
1064 /// much.
1065 ///
1066 /// This is `false` by default.
1067 ///
1068 /// [proposal]: https://github.com/webassembly/memory64
1069 pub fn wasm_memory64(&mut self, enable: bool) -> &mut Self {
1070 self.wasm_feature(WasmFeatures::MEMORY64, enable);
1071 self
1072 }
1073
1074 /// Configures whether the WebAssembly extended-const [proposal] will
1075 /// be enabled for compilation.
1076 ///
1077 /// This is `true` by default.
1078 ///
1079 /// [proposal]: https://github.com/webassembly/extended-const
1080 pub fn wasm_extended_const(&mut self, enable: bool) -> &mut Self {
1081 self.wasm_feature(WasmFeatures::EXTENDED_CONST, enable);
1082 self
1083 }
1084
1085 /// Configures whether the [WebAssembly stack switching
1086 /// proposal][proposal] will be enabled for compilation.
1087 ///
1088 /// This feature gates the use of control tags.
1089 ///
1090 /// This feature depends on the `function_reference_types` and
1091 /// `exceptions` features.
1092 ///
1093 /// This feature is `false` by default.
1094 ///
1095 /// # Errors
1096 ///
1097 /// [proposal]: https://github.com/webassembly/stack-switching
1098 pub fn wasm_stack_switching(&mut self, enable: bool) -> &mut Self {
1099 self.wasm_feature(WasmFeatures::STACK_SWITCHING, enable);
1100 self
1101 }
1102
1103 /// Configures whether the WebAssembly component-model [proposal] will
1104 /// be enabled for compilation.
1105 ///
1106 /// This flag can be used to blanket disable all components within Wasmtime.
1107 /// Otherwise usage of components requires statically using
1108 /// [`Component`](crate::component::Component) instead of
1109 /// [`Module`](crate::Module) for example anyway.
1110 ///
1111 /// The default value for this option is whether the `component-model`
1112 /// crate feature of Wasmtime is enabled or not. By default this crate
1113 /// feature is enabled.
1114 ///
1115 /// [proposal]: https://github.com/webassembly/component-model
1116 #[cfg(feature = "component-model")]
1117 pub fn wasm_component_model(&mut self, enable: bool) -> &mut Self {
1118 self.wasm_feature(WasmFeatures::COMPONENT_MODEL, enable);
1119 self
1120 }
1121
1122 /// Configures whether components support the async ABI [proposal] for
1123 /// lifting and lowering functions, as well as `stream`, `future`, and
1124 /// `error-context` types.
1125 ///
1126 /// Please note that Wasmtime's support for this feature is _very_
1127 /// incomplete.
1128 ///
1129 /// [proposal]:
1130 /// https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1131 #[cfg(feature = "component-model-async")]
1132 pub fn wasm_component_model_async(&mut self, enable: bool) -> &mut Self {
1133 self.wasm_feature(WasmFeatures::CM_ASYNC, enable);
1134 self
1135 }
1136
1137 /// This corresponds to the 🚝 emoji in the component model specification.
1138 ///
1139 /// Please note that Wasmtime's support for this feature is _very_
1140 /// incomplete.
1141 ///
1142 /// [proposal]:
1143 /// https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1144 #[cfg(feature = "component-model-async")]
1145 pub fn wasm_component_model_async_builtins(&mut self, enable: bool) -> &mut Self {
1146 self.wasm_feature(WasmFeatures::CM_ASYNC_BUILTINS, enable);
1147 self
1148 }
1149
1150 /// This corresponds to the 🚟 emoji in the component model specification.
1151 ///
1152 /// Please note that Wasmtime's support for this feature is _very_
1153 /// incomplete.
1154 ///
1155 /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1156 #[cfg(feature = "component-model-async")]
1157 pub fn wasm_component_model_async_stackful(&mut self, enable: bool) -> &mut Self {
1158 self.wasm_feature(WasmFeatures::CM_ASYNC_STACKFUL, enable);
1159 self
1160 }
1161
1162 /// This corresponds to the 📝 emoji in the component model specification.
1163 ///
1164 /// Please note that Wasmtime's support for this feature is _very_
1165 /// incomplete.
1166 ///
1167 /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1168 #[cfg(feature = "component-model")]
1169 pub fn wasm_component_model_error_context(&mut self, enable: bool) -> &mut Self {
1170 self.wasm_feature(WasmFeatures::CM_ERROR_CONTEXT, enable);
1171 self
1172 }
1173
1174 /// Configures whether the [GC extension to the component-model
1175 /// proposal][proposal] is enabled or not.
1176 ///
1177 /// This corresponds to the 🛸 emoji in the component model specification.
1178 ///
1179 /// Please note that Wasmtime's support for this feature is _very_
1180 /// incomplete.
1181 ///
1182 /// [proposal]: https://github.com/WebAssembly/component-model/issues/525
1183 #[cfg(feature = "component-model")]
1184 pub fn wasm_component_model_gc(&mut self, enable: bool) -> &mut Self {
1185 self.wasm_feature(WasmFeatures::CM_GC, enable);
1186 self
1187 }
1188
1189 #[doc(hidden)] // FIXME(#3427) - if/when implemented then un-hide this
1190 pub fn wasm_exceptions(&mut self, enable: bool) -> &mut Self {
1191 self.wasm_feature(WasmFeatures::EXCEPTIONS, enable);
1192 self
1193 }
1194
1195 #[doc(hidden)] // FIXME(#3427) - if/when implemented then un-hide this
1196 #[deprecated = "This configuration option only exists for internal \
1197 usage with the spec testsuite. It may be removed at \
1198 any time and without warning. Do not rely on it!"]
1199 pub fn wasm_legacy_exceptions(&mut self, enable: bool) -> &mut Self {
1200 self.wasm_feature(WasmFeatures::LEGACY_EXCEPTIONS, enable);
1201 self
1202 }
1203
1204 /// Configures which compilation strategy will be used for wasm modules.
1205 ///
1206 /// This method can be used to configure which compiler is used for wasm
1207 /// modules, and for more documentation consult the [`Strategy`] enumeration
1208 /// and its documentation.
1209 ///
1210 /// The default value for this is `Strategy::Auto`.
1211 #[cfg(any(feature = "cranelift", feature = "winch"))]
1212 pub fn strategy(&mut self, strategy: Strategy) -> &mut Self {
1213 self.compiler_config.strategy = strategy.not_auto();
1214 self
1215 }
1216
1217 /// Configures which garbage collector will be used for Wasm modules.
1218 ///
1219 /// This method can be used to configure which garbage collector
1220 /// implementation is used for Wasm modules. For more documentation, consult
1221 /// the [`Collector`] enumeration and its documentation.
1222 ///
1223 /// The default value for this is `Collector::Auto`.
1224 #[cfg(feature = "gc")]
1225 pub fn collector(&mut self, collector: Collector) -> &mut Self {
1226 self.collector = collector;
1227 self
1228 }
1229
1230 /// Creates a default profiler based on the profiling strategy chosen.
1231 ///
1232 /// Profiler creation calls the type's default initializer where the purpose is
1233 /// really just to put in place the type used for profiling.
1234 ///
1235 /// Some [`ProfilingStrategy`] require specific platforms or particular feature
1236 /// to be enabled, such as `ProfilingStrategy::JitDump` requires the `jitdump`
1237 /// feature.
1238 ///
1239 /// # Errors
1240 ///
1241 /// The validation of this field is deferred until the engine is being built, and thus may
1242 /// cause `Engine::new` fail if the required feature is disabled, or the platform is not
1243 /// supported.
1244 pub fn profiler(&mut self, profile: ProfilingStrategy) -> &mut Self {
1245 self.profiling_strategy = profile;
1246 self
1247 }
1248
1249 /// Configures whether the debug verifier of Cranelift is enabled or not.
1250 ///
1251 /// When Cranelift is used as a code generation backend this will configure
1252 /// it to have the `enable_verifier` flag which will enable a number of debug
1253 /// checks inside of Cranelift. This is largely only useful for the
1254 /// developers of wasmtime itself.
1255 ///
1256 /// The default value for this is `false`
1257 #[cfg(any(feature = "cranelift", feature = "winch"))]
1258 pub fn cranelift_debug_verifier(&mut self, enable: bool) -> &mut Self {
1259 let val = if enable { "true" } else { "false" };
1260 self.compiler_config
1261 .settings
1262 .insert("enable_verifier".to_string(), val.to_string());
1263 self
1264 }
1265
1266 /// Configures the Cranelift code generator optimization level.
1267 ///
1268 /// When the Cranelift code generator is used you can configure the
1269 /// optimization level used for generated code in a few various ways. For
1270 /// more information see the documentation of [`OptLevel`].
1271 ///
1272 /// The default value for this is `OptLevel::Speed`.
1273 #[cfg(any(feature = "cranelift", feature = "winch"))]
1274 pub fn cranelift_opt_level(&mut self, level: OptLevel) -> &mut Self {
1275 let val = match level {
1276 OptLevel::None => "none",
1277 OptLevel::Speed => "speed",
1278 OptLevel::SpeedAndSize => "speed_and_size",
1279 };
1280 self.compiler_config
1281 .settings
1282 .insert("opt_level".to_string(), val.to_string());
1283 self
1284 }
1285
1286 /// Configures the regalloc algorithm used by the Cranelift code generator.
1287 ///
1288 /// Cranelift can select any of several register allocator algorithms. Each
1289 /// of these algorithms generates correct code, but they represent different
1290 /// tradeoffs between compile speed (how expensive the compilation process
1291 /// is) and run-time speed (how fast the generated code runs).
1292 /// For more information see the documentation of [`RegallocAlgorithm`].
1293 ///
1294 /// The default value for this is `RegallocAlgorithm::Backtracking`.
1295 #[cfg(any(feature = "cranelift", feature = "winch"))]
1296 pub fn cranelift_regalloc_algorithm(&mut self, algo: RegallocAlgorithm) -> &mut Self {
1297 let val = match algo {
1298 RegallocAlgorithm::Backtracking => "backtracking",
1299 };
1300 self.compiler_config
1301 .settings
1302 .insert("regalloc_algorithm".to_string(), val.to_string());
1303 self
1304 }
1305
1306 /// Configures whether Cranelift should perform a NaN-canonicalization pass.
1307 ///
1308 /// When Cranelift is used as a code generation backend this will configure
1309 /// it to replace NaNs with a single canonical value. This is useful for
1310 /// users requiring entirely deterministic WebAssembly computation. This is
1311 /// not required by the WebAssembly spec, so it is not enabled by default.
1312 ///
1313 /// Note that this option affects not only WebAssembly's `f32` and `f64`
1314 /// types but additionally the `v128` type. This option will cause
1315 /// operations using any of these types to have extra checks placed after
1316 /// them to normalize NaN values as needed.
1317 ///
1318 /// The default value for this is `false`
1319 #[cfg(any(feature = "cranelift", feature = "winch"))]
1320 pub fn cranelift_nan_canonicalization(&mut self, enable: bool) -> &mut Self {
1321 let val = if enable { "true" } else { "false" };
1322 self.compiler_config
1323 .settings
1324 .insert("enable_nan_canonicalization".to_string(), val.to_string());
1325 self
1326 }
1327
1328 /// Controls whether proof-carrying code (PCC) is used to validate
1329 /// lowering of Wasm sandbox checks.
1330 ///
1331 /// Proof-carrying code carries "facts" about program values from
1332 /// the IR all the way to machine code, and checks those facts
1333 /// against known machine-instruction semantics. This guards
1334 /// against bugs in instruction lowering that might create holes
1335 /// in the Wasm sandbox.
1336 ///
1337 /// PCC is designed to be fast: it does not require complex
1338 /// solvers or logic engines to verify, but only a linear pass
1339 /// over a trail of "breadcrumbs" or facts at each intermediate
1340 /// value. Thus, it is appropriate to enable in production.
1341 #[cfg(any(feature = "cranelift", feature = "winch"))]
1342 pub fn cranelift_pcc(&mut self, enable: bool) -> &mut Self {
1343 let val = if enable { "true" } else { "false" };
1344 self.compiler_config
1345 .settings
1346 .insert("enable_pcc".to_string(), val.to_string());
1347 self
1348 }
1349
1350 /// Allows setting a Cranelift boolean flag or preset. This allows
1351 /// fine-tuning of Cranelift settings.
1352 ///
1353 /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1354 /// either; other `Config` functions should be preferred for stability.
1355 ///
1356 /// # Safety
1357 ///
1358 /// This is marked as unsafe, because setting the wrong flag might break invariants,
1359 /// resulting in execution hazards.
1360 ///
1361 /// # Errors
1362 ///
1363 /// The validation of the flags are deferred until the engine is being built, and thus may
1364 /// cause `Engine::new` fail if the flag's name does not exist, or the value is not appropriate
1365 /// for the flag type.
1366 #[cfg(any(feature = "cranelift", feature = "winch"))]
1367 pub unsafe fn cranelift_flag_enable(&mut self, flag: &str) -> &mut Self {
1368 self.compiler_config.flags.insert(flag.to_string());
1369 self
1370 }
1371
1372 /// Allows settings another Cranelift flag defined by a flag name and value. This allows
1373 /// fine-tuning of Cranelift settings.
1374 ///
1375 /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1376 /// either; other `Config` functions should be preferred for stability.
1377 ///
1378 /// # Safety
1379 ///
1380 /// This is marked as unsafe, because setting the wrong flag might break invariants,
1381 /// resulting in execution hazards.
1382 ///
1383 /// # Errors
1384 ///
1385 /// The validation of the flags are deferred until the engine is being built, and thus may
1386 /// cause `Engine::new` fail if the flag's name does not exist, or incompatible with other
1387 /// settings.
1388 ///
1389 /// For example, feature `wasm_backtrace` will set `unwind_info` to `true`, but if it's
1390 /// manually set to false then it will fail.
1391 #[cfg(any(feature = "cranelift", feature = "winch"))]
1392 pub unsafe fn cranelift_flag_set(&mut self, name: &str, value: &str) -> &mut Self {
1393 self.compiler_config
1394 .settings
1395 .insert(name.to_string(), value.to_string());
1396 self
1397 }
1398
1399 /// Set a custom [`Cache`].
1400 ///
1401 /// To load a cache from a file, use [`Cache::from_file`]. Otherwise, you can create a new
1402 /// cache config using [`CacheConfig::new`] and passing that to [`Cache::new`].
1403 ///
1404 /// If you want to disable the cache, you can call this method with `None`.
1405 ///
1406 /// By default, new configs do not have caching enabled.
1407 /// Every call to [`Module::new(my_wasm)`][crate::Module::new] will recompile `my_wasm`,
1408 /// even when it is unchanged, unless an enabled `CacheConfig` is provided.
1409 ///
1410 /// This method is only available when the `cache` feature of this crate is
1411 /// enabled.
1412 ///
1413 /// [docs]: https://bytecodealliance.github.io/wasmtime/cli-cache.html
1414 #[cfg(feature = "cache")]
1415 pub fn cache(&mut self, cache: Option<Cache>) -> &mut Self {
1416 self.cache = cache;
1417 self
1418 }
1419
1420 /// Sets a custom memory creator.
1421 ///
1422 /// Custom memory creators are used when creating host `Memory` objects or when
1423 /// creating instance linear memories for the on-demand instance allocation strategy.
1424 #[cfg(feature = "runtime")]
1425 pub fn with_host_memory(&mut self, mem_creator: Arc<dyn MemoryCreator>) -> &mut Self {
1426 self.mem_creator = Some(Arc::new(MemoryCreatorProxy(mem_creator)));
1427 self
1428 }
1429
1430 /// Sets a custom stack creator.
1431 ///
1432 /// Custom memory creators are used when creating creating async instance stacks for
1433 /// the on-demand instance allocation strategy.
1434 #[cfg(feature = "async")]
1435 pub fn with_host_stack(&mut self, stack_creator: Arc<dyn StackCreator>) -> &mut Self {
1436 self.stack_creator = Some(Arc::new(StackCreatorProxy(stack_creator)));
1437 self
1438 }
1439
1440 /// Sets a custom executable-memory publisher.
1441 ///
1442 /// Custom executable-memory publishers are hooks that allow
1443 /// Wasmtime to make certain regions of memory executable when
1444 /// loading precompiled modules or compiling new modules
1445 /// in-process. In most modern operating systems, memory allocated
1446 /// for heap usage is readable and writable by default but not
1447 /// executable. To jump to machine code stored in that memory, we
1448 /// need to make it executable. For security reasons, we usually
1449 /// also make it read-only at the same time, so the executing code
1450 /// can't be modified later.
1451 ///
1452 /// By default, Wasmtime will use the appropriate system calls on
1453 /// the host platform for this work. However, it also allows
1454 /// plugging in a custom implementation via this configuration
1455 /// option. This may be useful on custom or `no_std` platforms,
1456 /// for example, especially where virtual memory is not otherwise
1457 /// used by Wasmtime (no `signals-and-traps` feature).
1458 #[cfg(feature = "runtime")]
1459 pub fn with_custom_code_memory(
1460 &mut self,
1461 custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
1462 ) -> &mut Self {
1463 self.custom_code_memory = custom_code_memory;
1464 self
1465 }
1466
1467 /// Sets the instance allocation strategy to use.
1468 ///
1469 /// This is notably used in conjunction with
1470 /// [`InstanceAllocationStrategy::Pooling`] and [`PoolingAllocationConfig`].
1471 pub fn allocation_strategy(
1472 &mut self,
1473 strategy: impl Into<InstanceAllocationStrategy>,
1474 ) -> &mut Self {
1475 self.allocation_strategy = strategy.into();
1476 self
1477 }
1478
1479 /// Specifies the capacity of linear memories, in bytes, in their initial
1480 /// allocation.
1481 ///
1482 /// > Note: this value has important performance ramifications, be sure to
1483 /// > benchmark when setting this to a non-default value and read over this
1484 /// > documentation.
1485 ///
1486 /// This function will change the size of the initial memory allocation made
1487 /// for linear memories. This setting is only applicable when the initial
1488 /// size of a linear memory is below this threshold. Linear memories are
1489 /// allocated in the virtual address space of the host process with OS APIs
1490 /// such as `mmap` and this setting affects how large the allocation will
1491 /// be.
1492 ///
1493 /// ## Background: WebAssembly Linear Memories
1494 ///
1495 /// WebAssembly linear memories always start with a minimum size and can
1496 /// possibly grow up to a maximum size. The minimum size is always specified
1497 /// in a WebAssembly module itself and the maximum size can either be
1498 /// optionally specified in the module or inherently limited by the index
1499 /// type. For example for this module:
1500 ///
1501 /// ```wasm
1502 /// (module
1503 /// (memory $a 4)
1504 /// (memory $b 4096 4096 (pagesize 1))
1505 /// (memory $c i64 10)
1506 /// )
1507 /// ```
1508 ///
1509 /// * Memory `$a` initially allocates 4 WebAssembly pages (256KiB) and can
1510 /// grow up to 4GiB, the limit of the 32-bit index space.
1511 /// * Memory `$b` initially allocates 4096 WebAssembly pages, but in this
1512 /// case its page size is 1, so it's 4096 bytes. Memory can also grow no
1513 /// further meaning that it will always be 4096 bytes.
1514 /// * Memory `$c` is a 64-bit linear memory which starts with 640KiB of
1515 /// memory and can theoretically grow up to 2^64 bytes, although most
1516 /// hosts will run out of memory long before that.
1517 ///
1518 /// All operations on linear memories done by wasm are required to be
1519 /// in-bounds. Any access beyond the end of a linear memory is considered a
1520 /// trap.
1521 ///
1522 /// ## What this setting affects: Virtual Memory
1523 ///
1524 /// This setting is used to configure the behavior of the size of the linear
1525 /// memory allocation performed for each of these memories. For example the
1526 /// initial linear memory allocation looks like this:
1527 ///
1528 /// ```text
1529 /// memory_reservation
1530 /// |
1531 /// ◄─────────┴────────────────►
1532 /// ┌───────┬─────────┬──────────────────┬───────┐
1533 /// │ guard │ initial │ ... capacity ... │ guard │
1534 /// └───────┴─────────┴──────────────────┴───────┘
1535 /// ◄──┬──► ◄──┬──►
1536 /// │ │
1537 /// │ memory_guard_size
1538 /// │
1539 /// │
1540 /// memory_guard_size (if guard_before_linear_memory)
1541 /// ```
1542 ///
1543 /// Memory in the `initial` range is accessible to the instance and can be
1544 /// read/written by wasm code. Memory in the `guard` regions is never
1545 /// accessible to wasm code and memory in `capacity` is initially
1546 /// inaccessible but may become accessible through `memory.grow` instructions
1547 /// for example.
1548 ///
1549 /// This means that this setting is the size of the initial chunk of virtual
1550 /// memory that a linear memory may grow into.
1551 ///
1552 /// ## What this setting affects: Runtime Speed
1553 ///
1554 /// This is a performance-sensitive setting which is taken into account
1555 /// during the compilation process of a WebAssembly module. For example if a
1556 /// 32-bit WebAssembly linear memory has a `memory_reservation` size of 4GiB
1557 /// then bounds checks can be elided because `capacity` will be guaranteed
1558 /// to be unmapped for all addressable bytes that wasm can access (modulo a
1559 /// few details).
1560 ///
1561 /// If `memory_reservation` was something smaller like 256KiB then that
1562 /// would have a much smaller impact on virtual memory but the compile code
1563 /// would then need to have explicit bounds checks to ensure that
1564 /// loads/stores are in-bounds.
1565 ///
1566 /// The goal of this setting is to enable skipping bounds checks in most
1567 /// modules by default. Some situations which require explicit bounds checks
1568 /// though are:
1569 ///
1570 /// * When `memory_reservation` is smaller than the addressable size of the
1571 /// linear memory. For example if 64-bit linear memories always need
1572 /// bounds checks as they can address the entire virtual address spacce.
1573 /// For 32-bit linear memories a `memory_reservation` minimum size of 4GiB
1574 /// is required to elide bounds checks.
1575 ///
1576 /// * When linear memories have a page size of 1 then bounds checks are
1577 /// required. In this situation virtual memory can't be relied upon
1578 /// because that operates at the host page size granularity where wasm
1579 /// requires a per-byte level granularity.
1580 ///
1581 /// * Configuration settings such as [`Config::signals_based_traps`] can be
1582 /// used to disable the use of signal handlers and virtual memory so
1583 /// explicit bounds checks are required.
1584 ///
1585 /// * When [`Config::memory_guard_size`] is too small a bounds check may be
1586 /// required. For 32-bit wasm addresses are actually 33-bit effective
1587 /// addresses because loads/stores have a 32-bit static offset to add to
1588 /// the dynamic 32-bit address. If the static offset is larger than the
1589 /// size of the guard region then an explicit bounds check is required.
1590 ///
1591 /// ## What this setting affects: Memory Growth Behavior
1592 ///
1593 /// In addition to affecting bounds checks emitted in compiled code this
1594 /// setting also affects how WebAssembly linear memories are grown. The
1595 /// `memory.grow` instruction can be used to make a linear memory larger and
1596 /// this is also affected by APIs such as
1597 /// [`Memory::grow`](crate::Memory::grow).
1598 ///
1599 /// In these situations when the amount being grown is small enough to fit
1600 /// within the remaining capacity then the linear memory doesn't have to be
1601 /// moved at runtime. If the capacity runs out though then a new linear
1602 /// memory allocation must be made and the contents of linear memory is
1603 /// copied over.
1604 ///
1605 /// For example here's a situation where a copy happens:
1606 ///
1607 /// * The `memory_reservation` setting is configured to 128KiB.
1608 /// * A WebAssembly linear memory starts with a single 64KiB page.
1609 /// * This memory can be grown by one page to contain the full 128KiB of
1610 /// memory.
1611 /// * If grown by one more page, though, then a 192KiB allocation must be
1612 /// made and the previous 128KiB of contents are copied into the new
1613 /// allocation.
1614 ///
1615 /// This growth behavior can have a significant performance impact if lots
1616 /// of data needs to be copied on growth. Conversely if memory growth never
1617 /// needs to happen because the capacity will always be large enough then
1618 /// optimizations can be applied to cache the base pointer of linear memory.
1619 ///
1620 /// When memory is grown then the
1621 /// [`Config::memory_reservation_for_growth`] is used for the new
1622 /// memory allocation to have memory to grow into.
1623 ///
1624 /// When using the pooling allocator via [`PoolingAllocationConfig`] then
1625 /// memories are never allowed to move so requests for growth are instead
1626 /// rejected with an error.
1627 ///
1628 /// ## When this setting is not used
1629 ///
1630 /// This setting is ignored and unused when the initial size of linear
1631 /// memory is larger than this threshold. For example if this setting is set
1632 /// to 1MiB but a wasm module requires a 2MiB minimum allocation then this
1633 /// setting is ignored. In this situation the minimum size of memory will be
1634 /// allocated along with [`Config::memory_reservation_for_growth`]
1635 /// after it to grow into.
1636 ///
1637 /// That means that this value can be set to zero. That can be useful in
1638 /// benchmarking to see the overhead of bounds checks for example.
1639 /// Additionally it can be used to minimize the virtual memory allocated by
1640 /// Wasmtime.
1641 ///
1642 /// ## Default Value
1643 ///
1644 /// The default value for this property depends on the host platform. For
1645 /// 64-bit platforms there's lots of address space available, so the default
1646 /// configured here is 4GiB. When coupled with the default size of
1647 /// [`Config::memory_guard_size`] this means that 32-bit WebAssembly linear
1648 /// memories with 64KiB page sizes will skip almost all bounds checks by
1649 /// default.
1650 ///
1651 /// For 32-bit platforms this value defaults to 10MiB. This means that
1652 /// bounds checks will be required on 32-bit platforms.
1653 pub fn memory_reservation(&mut self, bytes: u64) -> &mut Self {
1654 self.tunables.memory_reservation = Some(bytes);
1655 self
1656 }
1657
1658 /// Indicates whether linear memories may relocate their base pointer at
1659 /// runtime.
1660 ///
1661 /// WebAssembly linear memories either have a maximum size that's explicitly
1662 /// listed in the type of a memory or inherently limited by the index type
1663 /// of the memory (e.g. 4GiB for 32-bit linear memories). Depending on how
1664 /// the linear memory is allocated (see [`Config::memory_reservation`]) it
1665 /// may be necessary to move the memory in the host's virtual address space
1666 /// during growth. This option controls whether this movement is allowed or
1667 /// not.
1668 ///
1669 /// An example of a linear memory needing to move is when
1670 /// [`Config::memory_reservation`] is 0 then a linear memory will be
1671 /// allocated as the minimum size of the memory plus
1672 /// [`Config::memory_reservation_for_growth`]. When memory grows beyond the
1673 /// reservation for growth then the memory needs to be relocated.
1674 ///
1675 /// When this option is set to `false` then it can have a number of impacts
1676 /// on how memories work at runtime:
1677 ///
1678 /// * Modules can be compiled with static knowledge the base pointer of
1679 /// linear memory never changes to enable optimizations such as
1680 /// loop invariant code motion (hoisting the base pointer out of a loop).
1681 ///
1682 /// * Memories cannot grow in excess of their original allocation. This
1683 /// means that [`Config::memory_reservation`] and
1684 /// [`Config::memory_reservation_for_growth`] may need tuning to ensure
1685 /// the memory configuration works at runtime.
1686 ///
1687 /// The default value for this option is `true`.
1688 pub fn memory_may_move(&mut self, enable: bool) -> &mut Self {
1689 self.tunables.memory_may_move = Some(enable);
1690 self
1691 }
1692
1693 /// Configures the size, in bytes, of the guard region used at the end of a
1694 /// linear memory's address space reservation.
1695 ///
1696 /// > Note: this value has important performance ramifications, be sure to
1697 /// > understand what this value does before tweaking it and benchmarking.
1698 ///
1699 /// This setting controls how many bytes are guaranteed to be unmapped after
1700 /// the virtual memory allocation of a linear memory. When
1701 /// combined with sufficiently large values of
1702 /// [`Config::memory_reservation`] (e.g. 4GiB for 32-bit linear memories)
1703 /// then a guard region can be used to eliminate bounds checks in generated
1704 /// code.
1705 ///
1706 /// This setting additionally can be used to help deduplicate bounds checks
1707 /// in code that otherwise requires bounds checks. For example with a 4KiB
1708 /// guard region then a 64-bit linear memory which accesses addresses `x+8`
1709 /// and `x+16` only needs to perform a single bounds check on `x`. If that
1710 /// bounds check passes then the offset is guaranteed to either reside in
1711 /// linear memory or the guard region, resulting in deterministic behavior
1712 /// either way.
1713 ///
1714 /// ## How big should the guard be?
1715 ///
1716 /// In general, like with configuring [`Config::memory_reservation`], you
1717 /// probably don't want to change this value from the defaults. Removing
1718 /// bounds checks is dependent on a number of factors where the size of the
1719 /// guard region is only one piece of the equation. Other factors include:
1720 ///
1721 /// * [`Config::memory_reservation`]
1722 /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
1723 /// * The page size of the linear memory
1724 /// * Other settings such as [`Config::signals_based_traps`]
1725 ///
1726 /// Embeddings using virtual memory almost always want at least some guard
1727 /// region, but otherwise changes from the default should be profiled
1728 /// locally to see the performance impact.
1729 ///
1730 /// ## Default
1731 ///
1732 /// The default value for this property is 32MiB on 64-bit platforms. This
1733 /// allows eliminating almost all bounds checks on loads/stores with an
1734 /// immediate offset of less than 32MiB. On 32-bit platforms this defaults
1735 /// to 64KiB.
1736 pub fn memory_guard_size(&mut self, bytes: u64) -> &mut Self {
1737 self.tunables.memory_guard_size = Some(bytes);
1738 self
1739 }
1740
1741 /// Configures the size, in bytes, of the extra virtual memory space
1742 /// reserved after a linear memory is relocated.
1743 ///
1744 /// This setting is used in conjunction with [`Config::memory_reservation`]
1745 /// to configure what happens after a linear memory is relocated in the host
1746 /// address space. If the initial size of a linear memory exceeds
1747 /// [`Config::memory_reservation`] or if it grows beyond that size
1748 /// throughout its lifetime then this setting will be used.
1749 ///
1750 /// When a linear memory is relocated it will initially look like this:
1751 ///
1752 /// ```text
1753 /// memory.size
1754 /// │
1755 /// ◄──────┴─────►
1756 /// ┌───────┬──────────────┬───────┐
1757 /// │ guard │ accessible │ guard │
1758 /// └───────┴──────────────┴───────┘
1759 /// ◄──┬──►
1760 /// │
1761 /// memory_guard_size
1762 /// ```
1763 ///
1764 /// where `accessible` needs to be grown but there's no more memory to grow
1765 /// into. A new region of the virtual address space will be allocated that
1766 /// looks like this:
1767 ///
1768 /// ```text
1769 /// memory_reservation_for_growth
1770 /// │
1771 /// memory.size │
1772 /// │ │
1773 /// ◄──────┴─────► ◄─────────────┴───────────►
1774 /// ┌───────┬──────────────┬───────────────────────────┬───────┐
1775 /// │ guard │ accessible │ .. reserved for growth .. │ guard │
1776 /// └───────┴──────────────┴───────────────────────────┴───────┘
1777 /// ◄──┬──►
1778 /// │
1779 /// memory_guard_size
1780 /// ```
1781 ///
1782 /// This means that up to `memory_reservation_for_growth` bytes can be
1783 /// allocated again before the entire linear memory needs to be moved again
1784 /// when another `memory_reservation_for_growth` bytes will be appended to
1785 /// the size of the allocation.
1786 ///
1787 /// Note that this is a currently simple heuristic for optimizing the growth
1788 /// of dynamic memories, primarily implemented for the memory64 proposal
1789 /// where the maximum size of memory is larger than 4GiB. This setting is
1790 /// unlikely to be a one-size-fits-all style approach and if you're an
1791 /// embedder running into issues with growth and are interested in having
1792 /// other growth strategies available here please feel free to [open an
1793 /// issue on the Wasmtime repository][issue]!
1794 ///
1795 /// [issue]: https://github.com/bytecodealliance/wasmtime/issues/new
1796 ///
1797 /// ## Default
1798 ///
1799 /// For 64-bit platforms this defaults to 2GiB, and for 32-bit platforms
1800 /// this defaults to 1MiB.
1801 pub fn memory_reservation_for_growth(&mut self, bytes: u64) -> &mut Self {
1802 self.tunables.memory_reservation_for_growth = Some(bytes);
1803 self
1804 }
1805
1806 /// Indicates whether a guard region is present before allocations of
1807 /// linear memory.
1808 ///
1809 /// Guard regions before linear memories are never used during normal
1810 /// operation of WebAssembly modules, even if they have out-of-bounds
1811 /// loads. The only purpose for a preceding guard region in linear memory
1812 /// is extra protection against possible bugs in code generators like
1813 /// Cranelift. This setting does not affect performance in any way, but will
1814 /// result in larger virtual memory reservations for linear memories (it
1815 /// won't actually ever use more memory, just use more of the address
1816 /// space).
1817 ///
1818 /// The size of the guard region before linear memory is the same as the
1819 /// guard size that comes after linear memory, which is configured by
1820 /// [`Config::memory_guard_size`].
1821 ///
1822 /// ## Default
1823 ///
1824 /// This value defaults to `true`.
1825 pub fn guard_before_linear_memory(&mut self, enable: bool) -> &mut Self {
1826 self.tunables.guard_before_linear_memory = Some(enable);
1827 self
1828 }
1829
1830 /// Indicates whether to initialize tables lazily, so that instantiation
1831 /// is fast but indirect calls are a little slower. If false, tables
1832 /// are initialized eagerly during instantiation from any active element
1833 /// segments that apply to them.
1834 ///
1835 /// **Note** Disabling this option is not compatible with the Winch compiler.
1836 ///
1837 /// ## Default
1838 ///
1839 /// This value defaults to `true`.
1840 pub fn table_lazy_init(&mut self, table_lazy_init: bool) -> &mut Self {
1841 self.tunables.table_lazy_init = Some(table_lazy_init);
1842 self
1843 }
1844
1845 /// Configure the version information used in serialized and deserialized [`crate::Module`]s.
1846 /// This effects the behavior of [`crate::Module::serialize()`], as well as
1847 /// [`crate::Module::deserialize()`] and related functions.
1848 ///
1849 /// The default strategy is to use the wasmtime crate's Cargo package version.
1850 pub fn module_version(&mut self, strategy: ModuleVersionStrategy) -> Result<&mut Self> {
1851 match strategy {
1852 // This case requires special precondition for assertion in SerializedModule::to_bytes
1853 ModuleVersionStrategy::Custom(ref v) => {
1854 if v.as_bytes().len() > 255 {
1855 bail!("custom module version cannot be more than 255 bytes: {}", v);
1856 }
1857 }
1858 _ => {}
1859 }
1860 self.module_version = strategy;
1861 Ok(self)
1862 }
1863
1864 /// Configure whether wasmtime should compile a module using multiple
1865 /// threads.
1866 ///
1867 /// Disabling this will result in a single thread being used to compile
1868 /// the wasm bytecode.
1869 ///
1870 /// By default parallel compilation is enabled.
1871 #[cfg(feature = "parallel-compilation")]
1872 pub fn parallel_compilation(&mut self, parallel: bool) -> &mut Self {
1873 self.parallel_compilation = parallel;
1874 self
1875 }
1876
1877 /// Configures whether compiled artifacts will contain information to map
1878 /// native program addresses back to the original wasm module.
1879 ///
1880 /// This configuration option is `true` by default and, if enabled,
1881 /// generates the appropriate tables in compiled modules to map from native
1882 /// address back to wasm source addresses. This is used for displaying wasm
1883 /// program counters in backtraces as well as generating filenames/line
1884 /// numbers if so configured as well (and the original wasm module has DWARF
1885 /// debugging information present).
1886 pub fn generate_address_map(&mut self, generate: bool) -> &mut Self {
1887 self.tunables.generate_address_map = Some(generate);
1888 self
1889 }
1890
1891 /// Configures whether copy-on-write memory-mapped data is used to
1892 /// initialize a linear memory.
1893 ///
1894 /// Initializing linear memory via a copy-on-write mapping can drastically
1895 /// improve instantiation costs of a WebAssembly module because copying
1896 /// memory is deferred. Additionally if a page of memory is only ever read
1897 /// from WebAssembly and never written too then the same underlying page of
1898 /// data will be reused between all instantiations of a module meaning that
1899 /// if a module is instantiated many times this can lower the overall memory
1900 /// required needed to run that module.
1901 ///
1902 /// The main disadvantage of copy-on-write initialization, however, is that
1903 /// it may be possible for highly-parallel scenarios to be less scalable. If
1904 /// a page is read initially by a WebAssembly module then that page will be
1905 /// mapped to a read-only copy shared between all WebAssembly instances. If
1906 /// the same page is then written, however, then a private copy is created
1907 /// and swapped out from the read-only version. This also requires an [IPI],
1908 /// however, which can be a significant bottleneck in high-parallelism
1909 /// situations.
1910 ///
1911 /// This feature is only applicable when a WebAssembly module meets specific
1912 /// criteria to be initialized in this fashion, such as:
1913 ///
1914 /// * Only memories defined in the module can be initialized this way.
1915 /// * Data segments for memory must use statically known offsets.
1916 /// * Data segments for memory must all be in-bounds.
1917 ///
1918 /// Modules which do not meet these criteria will fall back to
1919 /// initialization of linear memory based on copying memory.
1920 ///
1921 /// This feature of Wasmtime is also platform-specific:
1922 ///
1923 /// * Linux - this feature is supported for all instances of [`Module`].
1924 /// Modules backed by an existing mmap (such as those created by
1925 /// [`Module::deserialize_file`]) will reuse that mmap to cow-initialize
1926 /// memory. Other instance of [`Module`] may use the `memfd_create`
1927 /// syscall to create an initialization image to `mmap`.
1928 /// * Unix (not Linux) - this feature is only supported when loading modules
1929 /// from a precompiled file via [`Module::deserialize_file`] where there
1930 /// is a file descriptor to use to map data into the process. Note that
1931 /// the module must have been compiled with this setting enabled as well.
1932 /// * Windows - there is no support for this feature at this time. Memory
1933 /// initialization will always copy bytes.
1934 ///
1935 /// By default this option is enabled.
1936 ///
1937 /// [`Module::deserialize_file`]: crate::Module::deserialize_file
1938 /// [`Module`]: crate::Module
1939 /// [IPI]: https://en.wikipedia.org/wiki/Inter-processor_interrupt
1940 pub fn memory_init_cow(&mut self, enable: bool) -> &mut Self {
1941 self.tunables.memory_init_cow = Some(enable);
1942 self
1943 }
1944
1945 /// A configuration option to force the usage of `memfd_create` on Linux to
1946 /// be used as the backing source for a module's initial memory image.
1947 ///
1948 /// When [`Config::memory_init_cow`] is enabled, which is enabled by
1949 /// default, module memory initialization images are taken from a module's
1950 /// original mmap if possible. If a precompiled module was loaded from disk
1951 /// this means that the disk's file is used as an mmap source for the
1952 /// initial linear memory contents. This option can be used to force, on
1953 /// Linux, that instead of using the original file on disk a new in-memory
1954 /// file is created with `memfd_create` to hold the contents of the initial
1955 /// image.
1956 ///
1957 /// This option can be used to avoid possibly loading the contents of memory
1958 /// from disk through a page fault. Instead with `memfd_create` the contents
1959 /// of memory are always in RAM, meaning that even page faults which
1960 /// initially populate a wasm linear memory will only work with RAM instead
1961 /// of ever hitting the disk that the original precompiled module is stored
1962 /// on.
1963 ///
1964 /// This option is disabled by default.
1965 pub fn force_memory_init_memfd(&mut self, enable: bool) -> &mut Self {
1966 self.force_memory_init_memfd = enable;
1967 self
1968 }
1969
1970 /// Configures whether or not a coredump should be generated and attached to
1971 /// the anyhow::Error when a trap is raised.
1972 ///
1973 /// This option is disabled by default.
1974 #[cfg(feature = "coredump")]
1975 pub fn coredump_on_trap(&mut self, enable: bool) -> &mut Self {
1976 self.coredump_on_trap = enable;
1977 self
1978 }
1979
1980 /// Enables memory error checking for wasm programs.
1981 ///
1982 /// This option is disabled by default.
1983 #[cfg(any(feature = "cranelift", feature = "winch"))]
1984 pub fn wmemcheck(&mut self, enable: bool) -> &mut Self {
1985 self.wmemcheck = enable;
1986 self.compiler_config.wmemcheck = enable;
1987 self
1988 }
1989
1990 /// Configures the "guaranteed dense image size" for copy-on-write
1991 /// initialized memories.
1992 ///
1993 /// When using the [`Config::memory_init_cow`] feature to initialize memory
1994 /// efficiently (which is enabled by default), compiled modules contain an
1995 /// image of the module's initial heap. If the module has a fairly sparse
1996 /// initial heap, with just a few data segments at very different offsets,
1997 /// this could result in a large region of zero bytes in the image. In
1998 /// other words, it's not very memory-efficient.
1999 ///
2000 /// We normally use a heuristic to avoid this: if less than half
2001 /// of the initialized range (first non-zero to last non-zero
2002 /// byte) of any memory in the module has pages with nonzero
2003 /// bytes, then we avoid creating a memory image for the entire module.
2004 ///
2005 /// However, if the embedder always needs the instantiation-time efficiency
2006 /// of copy-on-write initialization, and is otherwise carefully controlling
2007 /// parameters of the modules (for example, by limiting the maximum heap
2008 /// size of the modules), then it may be desirable to ensure a memory image
2009 /// is created even if this could go against the heuristic above. Thus, we
2010 /// add another condition: there is a size of initialized data region up to
2011 /// which we *always* allow a memory image. The embedder can set this to a
2012 /// known maximum heap size if they desire to always get the benefits of
2013 /// copy-on-write images.
2014 ///
2015 /// In the future we may implement a "best of both worlds"
2016 /// solution where we have a dense image up to some limit, and
2017 /// then support a sparse list of initializers beyond that; this
2018 /// would get most of the benefit of copy-on-write and pay the incremental
2019 /// cost of eager initialization only for those bits of memory
2020 /// that are out-of-bounds. However, for now, an embedder desiring
2021 /// fast instantiation should ensure that this setting is as large
2022 /// as the maximum module initial memory content size.
2023 ///
2024 /// By default this value is 16 MiB.
2025 pub fn memory_guaranteed_dense_image_size(&mut self, size_in_bytes: u64) -> &mut Self {
2026 self.memory_guaranteed_dense_image_size = size_in_bytes;
2027 self
2028 }
2029
2030 /// Returns the set of features that the currently selected compiler backend
2031 /// does not support at all and may panic on.
2032 ///
2033 /// Wasmtime strives to reject unknown modules or unsupported modules with
2034 /// first-class errors instead of panics. Not all compiler backends have the
2035 /// same level of feature support on all platforms as well. This method
2036 /// returns a set of features that the currently selected compiler
2037 /// configuration is known to not support and may panic on. This acts as a
2038 /// first-level filter on incoming wasm modules/configuration to fail-fast
2039 /// instead of panicking later on.
2040 ///
2041 /// Note that if a feature is not listed here it does not mean that the
2042 /// backend fully supports the proposal. Instead that means that the backend
2043 /// doesn't ever panic on the proposal, but errors during compilation may
2044 /// still be returned. This means that features listed here are definitely
2045 /// not supported at all, but features not listed here may still be
2046 /// partially supported. For example at the time of this writing the Winch
2047 /// backend partially supports simd so it's not listed here. Winch doesn't
2048 /// fully support simd but unimplemented instructions just return errors.
2049 fn compiler_panicking_wasm_features(&self) -> WasmFeatures {
2050 #[cfg(any(feature = "cranelift", feature = "winch"))]
2051 match self.compiler_config.strategy {
2052 None | Some(Strategy::Cranelift) => {
2053 let mut unsupported = WasmFeatures::empty();
2054
2055 // Pulley at this time fundamentally doesn't support the
2056 // `threads` proposal, notably shared memory, because Rust can't
2057 // safely implement loads/stores in the face of shared memory.
2058 // Stack switching is not implemented, either.
2059 if self.compiler_target().is_pulley() {
2060 unsupported |= WasmFeatures::THREADS;
2061 unsupported |= WasmFeatures::STACK_SWITCHING;
2062 }
2063
2064 use target_lexicon::*;
2065 match self.compiler_target() {
2066 Triple {
2067 architecture: Architecture::X86_64 | Architecture::X86_64h,
2068 operating_system:
2069 OperatingSystem::Linux
2070 | OperatingSystem::MacOSX(_)
2071 | OperatingSystem::Darwin(_),
2072 ..
2073 } => {
2074 // Stack switching supported on (non-Pulley) Cranelift.
2075 }
2076
2077 _ => {
2078 // On platforms other than x64 Unix-like, we don't
2079 // support stack switching.
2080 unsupported |= WasmFeatures::STACK_SWITCHING;
2081 }
2082 }
2083 unsupported
2084 }
2085 Some(Strategy::Winch) => {
2086 let mut unsupported = WasmFeatures::GC
2087 | WasmFeatures::FUNCTION_REFERENCES
2088 | WasmFeatures::RELAXED_SIMD
2089 | WasmFeatures::TAIL_CALL
2090 | WasmFeatures::GC_TYPES
2091 | WasmFeatures::EXCEPTIONS
2092 | WasmFeatures::LEGACY_EXCEPTIONS
2093 | WasmFeatures::STACK_SWITCHING;
2094 match self.compiler_target().architecture {
2095 target_lexicon::Architecture::Aarch64(_) => {
2096 unsupported |= WasmFeatures::THREADS;
2097 unsupported |= WasmFeatures::WIDE_ARITHMETIC;
2098 }
2099
2100 // Winch doesn't support other non-x64 architectures at this
2101 // time either but will return an first-class error for
2102 // them.
2103 _ => {}
2104 }
2105 unsupported
2106 }
2107 Some(Strategy::Auto) => unreachable!(),
2108 }
2109 #[cfg(not(any(feature = "cranelift", feature = "winch")))]
2110 return WasmFeatures::empty();
2111 }
2112
2113 /// Calculates the set of features that are enabled for this `Config`.
2114 ///
2115 /// This method internally will start with the an empty set of features to
2116 /// avoid being tied to wasmparser's defaults. Next Wasmtime's set of
2117 /// default features are added to this set, some of which are conditional
2118 /// depending on crate features. Finally explicitly requested features via
2119 /// `wasm_*` methods on `Config` are applied. Everything is then validated
2120 /// later in `Config::validate`.
2121 fn features(&self) -> WasmFeatures {
2122 // Wasmtime by default supports all of the wasm 2.0 version of the
2123 // specification.
2124 let mut features = WasmFeatures::WASM2;
2125
2126 // On-by-default features that wasmtime has. Note that these are all
2127 // subject to the criteria at
2128 // https://docs.wasmtime.dev/contributing-implementing-wasm-proposals.html
2129 // and
2130 // https://docs.wasmtime.dev/stability-wasm-proposals.html
2131 features |= WasmFeatures::MULTI_MEMORY;
2132 features |= WasmFeatures::RELAXED_SIMD;
2133 features |= WasmFeatures::TAIL_CALL;
2134 features |= WasmFeatures::EXTENDED_CONST;
2135 features |= WasmFeatures::MEMORY64;
2136 // NB: if you add a feature above this line please double-check
2137 // https://docs.wasmtime.dev/stability-wasm-proposals.html
2138 // to ensure all requirements are met and/or update the documentation
2139 // there too.
2140
2141 // Set some features to their conditionally-enabled defaults depending
2142 // on crate compile-time features.
2143 features.set(WasmFeatures::GC_TYPES, cfg!(feature = "gc"));
2144 features.set(WasmFeatures::THREADS, cfg!(feature = "threads"));
2145 features.set(
2146 WasmFeatures::COMPONENT_MODEL,
2147 cfg!(feature = "component-model"),
2148 );
2149
2150 // From the default set of proposals remove any that the current
2151 // compiler backend may panic on if the module contains them.
2152 features = features & !self.compiler_panicking_wasm_features();
2153
2154 // After wasmtime's defaults are configured then factor in user requests
2155 // and disable/enable features. Note that the enable/disable sets should
2156 // be disjoint.
2157 debug_assert!((self.enabled_features & self.disabled_features).is_empty());
2158 features &= !self.disabled_features;
2159 features |= self.enabled_features;
2160
2161 features
2162 }
2163
2164 /// Returns the configured compiler target for this `Config`.
2165 pub(crate) fn compiler_target(&self) -> target_lexicon::Triple {
2166 // If a target is explicitly configured, always use that.
2167 if let Some(target) = self.target.clone() {
2168 return target;
2169 }
2170
2171 // If the `build.rs` script determined that this platform uses pulley by
2172 // default, then use Pulley.
2173 if cfg!(default_target_pulley) {
2174 return target_lexicon::Triple::pulley_host();
2175 }
2176
2177 // And at this point the target is for sure the host.
2178 target_lexicon::Triple::host()
2179 }
2180
2181 pub(crate) fn validate(&self) -> Result<(Tunables, WasmFeatures)> {
2182 let features = self.features();
2183
2184 // First validate that the selected compiler backend and configuration
2185 // supports the set of `features` that are enabled. This will help
2186 // provide more first class errors instead of panics about unsupported
2187 // features and configurations.
2188 let unsupported = features & self.compiler_panicking_wasm_features();
2189 if !unsupported.is_empty() {
2190 for flag in WasmFeatures::FLAGS.iter() {
2191 if !unsupported.contains(*flag.value()) {
2192 continue;
2193 }
2194 bail!(
2195 "the wasm_{} feature is not supported on this compiler configuration",
2196 flag.name().to_lowercase()
2197 );
2198 }
2199
2200 panic!("should have returned an error by now")
2201 }
2202
2203 #[cfg(any(feature = "async", feature = "stack-switching"))]
2204 if self.async_support && self.max_wasm_stack > self.async_stack_size {
2205 bail!("max_wasm_stack size cannot exceed the async_stack_size");
2206 }
2207 if self.max_wasm_stack == 0 {
2208 bail!("max_wasm_stack size cannot be zero");
2209 }
2210 #[cfg(not(feature = "wmemcheck"))]
2211 if self.wmemcheck {
2212 bail!("wmemcheck (memory checker) was requested but is not enabled in this build");
2213 }
2214
2215 let mut tunables = Tunables::default_for_target(&self.compiler_target())?;
2216
2217 // If no target is explicitly specified then further refine `tunables`
2218 // for the configuration of this host depending on what platform
2219 // features were found available at compile time. This means that anyone
2220 // cross-compiling for a customized host will need to further refine
2221 // compilation options.
2222 if self.target.is_none() {
2223 // If this platform doesn't have native signals then change some
2224 // defaults to account for that. Note that VM guards are turned off
2225 // here because that's primarily a feature of eliding
2226 // bounds-checks.
2227 if !cfg!(has_native_signals) {
2228 tunables.signals_based_traps = cfg!(has_native_signals);
2229 tunables.memory_guard_size = 0;
2230 }
2231
2232 // When virtual memory is not available use slightly different
2233 // defaults for tunables to be more amenable to `MallocMemory`.
2234 // Note that these can still be overridden by config options.
2235 if !cfg!(has_virtual_memory) {
2236 tunables.memory_reservation = 0;
2237 tunables.memory_reservation_for_growth = 1 << 20; // 1MB
2238 tunables.memory_init_cow = false;
2239 }
2240 }
2241
2242 self.tunables.configure(&mut tunables);
2243
2244 // If we're going to compile with winch, we must use the winch calling convention.
2245 #[cfg(any(feature = "cranelift", feature = "winch"))]
2246 {
2247 tunables.winch_callable = self.compiler_config.strategy == Some(Strategy::Winch);
2248 }
2249
2250 tunables.collector = if features.gc_types() {
2251 #[cfg(feature = "gc")]
2252 {
2253 use wasmtime_environ::Collector as EnvCollector;
2254 Some(match self.collector.try_not_auto()? {
2255 Collector::DeferredReferenceCounting => EnvCollector::DeferredReferenceCounting,
2256 Collector::Null => EnvCollector::Null,
2257 Collector::Auto => unreachable!(),
2258 })
2259 }
2260 #[cfg(not(feature = "gc"))]
2261 bail!("cannot use GC types: the `gc` feature was disabled at compile time")
2262 } else {
2263 None
2264 };
2265
2266 Ok((tunables, features))
2267 }
2268
2269 #[cfg(feature = "runtime")]
2270 pub(crate) fn build_allocator(
2271 &self,
2272 tunables: &Tunables,
2273 ) -> Result<Box<dyn InstanceAllocator + Send + Sync>> {
2274 #[cfg(feature = "async")]
2275 let (stack_size, stack_zeroing) = (self.async_stack_size, self.async_stack_zeroing);
2276
2277 #[cfg(not(feature = "async"))]
2278 let (stack_size, stack_zeroing) = (0, false);
2279
2280 let _ = tunables;
2281
2282 match &self.allocation_strategy {
2283 InstanceAllocationStrategy::OnDemand => {
2284 #[allow(unused_mut)]
2285 let mut allocator = Box::new(OnDemandInstanceAllocator::new(
2286 self.mem_creator.clone(),
2287 stack_size,
2288 stack_zeroing,
2289 ));
2290 #[cfg(feature = "async")]
2291 if let Some(stack_creator) = &self.stack_creator {
2292 allocator.set_stack_creator(stack_creator.clone());
2293 }
2294 Ok(allocator)
2295 }
2296 #[cfg(feature = "pooling-allocator")]
2297 InstanceAllocationStrategy::Pooling(config) => {
2298 let mut config = config.config;
2299 config.stack_size = stack_size;
2300 config.async_stack_zeroing = stack_zeroing;
2301 Ok(Box::new(crate::runtime::vm::PoolingInstanceAllocator::new(
2302 &config, tunables,
2303 )?))
2304 }
2305 }
2306 }
2307
2308 #[cfg(feature = "runtime")]
2309 pub(crate) fn build_gc_runtime(&self) -> Result<Option<Arc<dyn GcRuntime>>> {
2310 if !self.features().gc_types() {
2311 return Ok(None);
2312 }
2313
2314 #[cfg(not(feature = "gc"))]
2315 bail!("cannot create a GC runtime: the `gc` feature was disabled at compile time");
2316
2317 #[cfg(feature = "gc")]
2318 #[cfg_attr(
2319 not(any(feature = "gc-null", feature = "gc-drc")),
2320 allow(unused_variables, unreachable_code)
2321 )]
2322 {
2323 Ok(Some(match self.collector.try_not_auto()? {
2324 #[cfg(feature = "gc-drc")]
2325 Collector::DeferredReferenceCounting => {
2326 Arc::new(crate::runtime::vm::DrcCollector::default()) as Arc<dyn GcRuntime>
2327 }
2328 #[cfg(not(feature = "gc-drc"))]
2329 Collector::DeferredReferenceCounting => unreachable!(),
2330
2331 #[cfg(feature = "gc-null")]
2332 Collector::Null => {
2333 Arc::new(crate::runtime::vm::NullCollector::default()) as Arc<dyn GcRuntime>
2334 }
2335 #[cfg(not(feature = "gc-null"))]
2336 Collector::Null => unreachable!(),
2337
2338 Collector::Auto => unreachable!(),
2339 }))
2340 }
2341 }
2342
2343 #[cfg(feature = "runtime")]
2344 pub(crate) fn build_profiler(&self) -> Result<Box<dyn ProfilingAgent>> {
2345 Ok(match self.profiling_strategy {
2346 ProfilingStrategy::PerfMap => profiling_agent::new_perfmap()?,
2347 ProfilingStrategy::JitDump => profiling_agent::new_jitdump()?,
2348 ProfilingStrategy::VTune => profiling_agent::new_vtune()?,
2349 ProfilingStrategy::None => profiling_agent::new_null(),
2350 ProfilingStrategy::Pulley => profiling_agent::new_pulley()?,
2351 })
2352 }
2353
2354 #[cfg(any(feature = "cranelift", feature = "winch"))]
2355 pub(crate) fn build_compiler(
2356 mut self,
2357 tunables: &Tunables,
2358 features: WasmFeatures,
2359 ) -> Result<(Self, Box<dyn wasmtime_environ::Compiler>)> {
2360 let target = self.compiler_target();
2361
2362 // The target passed to the builders below is an `Option<Triple>` where
2363 // `None` represents the current host with CPU features inferred from
2364 // the host's CPU itself. The `target` above is not an `Option`, so
2365 // switch it to `None` in the case that a target wasn't explicitly
2366 // specified (which indicates no feature inference) and the target
2367 // matches the host.
2368 let target_for_builder =
2369 if self.target.is_none() && target == target_lexicon::Triple::host() {
2370 None
2371 } else {
2372 Some(target.clone())
2373 };
2374
2375 let mut compiler = match self.compiler_config.strategy {
2376 #[cfg(feature = "cranelift")]
2377 Some(Strategy::Cranelift) => wasmtime_cranelift::builder(target_for_builder)?,
2378 #[cfg(not(feature = "cranelift"))]
2379 Some(Strategy::Cranelift) => bail!("cranelift support not compiled in"),
2380 #[cfg(feature = "winch")]
2381 Some(Strategy::Winch) => wasmtime_winch::builder(target_for_builder)?,
2382 #[cfg(not(feature = "winch"))]
2383 Some(Strategy::Winch) => bail!("winch support not compiled in"),
2384
2385 None | Some(Strategy::Auto) => unreachable!(),
2386 };
2387
2388 if let Some(path) = &self.compiler_config.clif_dir {
2389 compiler.clif_dir(path)?;
2390 }
2391
2392 // If probestack is enabled for a target, Wasmtime will always use the
2393 // inline strategy which doesn't require us to define a `__probestack`
2394 // function or similar.
2395 self.compiler_config
2396 .settings
2397 .insert("probestack_strategy".into(), "inline".into());
2398
2399 // We enable stack probing by default on all targets.
2400 // This is required on Windows because of the way Windows
2401 // commits its stacks, but it's also a good idea on other
2402 // platforms to ensure guard pages are hit for large frame
2403 // sizes.
2404 self.compiler_config
2405 .flags
2406 .insert("enable_probestack".into());
2407
2408 // The current wasm multivalue implementation depends on this.
2409 // FIXME(#9510) handle this in wasmtime-cranelift instead.
2410 self.compiler_config
2411 .flags
2412 .insert("enable_multi_ret_implicit_sret".into());
2413
2414 if let Some(unwind_requested) = self.native_unwind_info {
2415 if !self
2416 .compiler_config
2417 .ensure_setting_unset_or_given("unwind_info", &unwind_requested.to_string())
2418 {
2419 bail!(
2420 "incompatible settings requested for Cranelift and Wasmtime `unwind-info` settings"
2421 );
2422 }
2423 }
2424
2425 if target.operating_system == target_lexicon::OperatingSystem::Windows {
2426 if !self
2427 .compiler_config
2428 .ensure_setting_unset_or_given("unwind_info", "true")
2429 {
2430 bail!("`native_unwind_info` cannot be disabled on Windows");
2431 }
2432 }
2433
2434 // We require frame pointers for correct stack walking, which is safety
2435 // critical in the presence of reference types, and otherwise it is just
2436 // really bad developer experience to get wrong.
2437 self.compiler_config
2438 .settings
2439 .insert("preserve_frame_pointers".into(), "true".into());
2440
2441 if !tunables.signals_based_traps {
2442 let mut ok = self
2443 .compiler_config
2444 .ensure_setting_unset_or_given("enable_table_access_spectre_mitigation", "false");
2445 ok = ok
2446 && self.compiler_config.ensure_setting_unset_or_given(
2447 "enable_heap_access_spectre_mitigation",
2448 "false",
2449 );
2450
2451 // Right now spectre-mitigated bounds checks will load from zero so
2452 // if host-based signal handlers are disabled then that's a mismatch
2453 // and doesn't work right now. Fixing this will require more thought
2454 // of how to implement the bounds check in spectre-only mode.
2455 if !ok {
2456 bail!(
2457 "when signals-based traps are disabled then spectre \
2458 mitigations must also be disabled"
2459 );
2460 }
2461 }
2462
2463 // check for incompatible compiler options and set required values
2464 if features.contains(WasmFeatures::REFERENCE_TYPES) {
2465 if !self
2466 .compiler_config
2467 .ensure_setting_unset_or_given("enable_safepoints", "true")
2468 {
2469 bail!(
2470 "compiler option 'enable_safepoints' must be enabled when 'reference types' is enabled"
2471 );
2472 }
2473 }
2474
2475 if features.contains(WasmFeatures::RELAXED_SIMD) && !features.contains(WasmFeatures::SIMD) {
2476 bail!("cannot disable the simd proposal but enable the relaxed simd proposal");
2477 }
2478
2479 if features.contains(WasmFeatures::STACK_SWITCHING) {
2480 use target_lexicon::OperatingSystem;
2481 let model = match target.operating_system {
2482 OperatingSystem::Windows => "update_windows_tib",
2483 OperatingSystem::Linux
2484 | OperatingSystem::MacOSX(_)
2485 | OperatingSystem::Darwin(_) => "basic",
2486 _ => bail!("stack-switching feature not supported on this platform "),
2487 };
2488
2489 if !self
2490 .compiler_config
2491 .ensure_setting_unset_or_given("stack_switch_model", model)
2492 {
2493 bail!(
2494 "compiler option 'stack_switch_model' must be set to '{}' on this platform",
2495 model
2496 );
2497 }
2498 }
2499
2500 // Apply compiler settings and flags
2501 for (k, v) in self.compiler_config.settings.iter() {
2502 compiler.set(k, v)?;
2503 }
2504 for flag in self.compiler_config.flags.iter() {
2505 compiler.enable(flag)?;
2506 }
2507
2508 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
2509 if let Some(cache_store) = &self.compiler_config.cache_store {
2510 compiler.enable_incremental_compilation(cache_store.clone())?;
2511 }
2512
2513 compiler.set_tunables(tunables.clone())?;
2514 compiler.wmemcheck(self.compiler_config.wmemcheck);
2515
2516 Ok((self, compiler.build()?))
2517 }
2518
2519 /// Internal setting for whether adapter modules for components will have
2520 /// extra WebAssembly instructions inserted performing more debug checks
2521 /// then are necessary.
2522 #[cfg(feature = "component-model")]
2523 pub fn debug_adapter_modules(&mut self, debug: bool) -> &mut Self {
2524 self.tunables.debug_adapter_modules = Some(debug);
2525 self
2526 }
2527
2528 /// Enables clif output when compiling a WebAssembly module.
2529 #[cfg(any(feature = "cranelift", feature = "winch"))]
2530 pub fn emit_clif(&mut self, path: &Path) -> &mut Self {
2531 self.compiler_config.clif_dir = Some(path.to_path_buf());
2532 self
2533 }
2534
2535 /// Configures whether, when on macOS, Mach ports are used for exception
2536 /// handling instead of traditional Unix-based signal handling.
2537 ///
2538 /// WebAssembly traps in Wasmtime are implemented with native faults, for
2539 /// example a `SIGSEGV` will occur when a WebAssembly guest accesses
2540 /// out-of-bounds memory. Handling this can be configured to either use Unix
2541 /// signals or Mach ports on macOS. By default Mach ports are used.
2542 ///
2543 /// Mach ports enable Wasmtime to work by default with foreign
2544 /// error-handling systems such as breakpad which also use Mach ports to
2545 /// handle signals. In this situation Wasmtime will continue to handle guest
2546 /// faults gracefully while any non-guest faults will get forwarded to
2547 /// process-level handlers such as breakpad. Some more background on this
2548 /// can be found in #2456.
2549 ///
2550 /// A downside of using mach ports, however, is that they don't interact
2551 /// well with `fork()`. Forking a Wasmtime process on macOS will produce a
2552 /// child process that cannot successfully run WebAssembly. In this
2553 /// situation traditional Unix signal handling should be used as that's
2554 /// inherited and works across forks.
2555 ///
2556 /// If your embedding wants to use a custom error handler which leverages
2557 /// Mach ports and you additionally wish to `fork()` the process and use
2558 /// Wasmtime in the child process that's not currently possible. Please
2559 /// reach out to us if you're in this bucket!
2560 ///
2561 /// This option defaults to `true`, using Mach ports by default.
2562 pub fn macos_use_mach_ports(&mut self, mach_ports: bool) -> &mut Self {
2563 self.macos_use_mach_ports = mach_ports;
2564 self
2565 }
2566
2567 /// Configures an embedder-provided function, `detect`, which is used to
2568 /// determine if an ISA-specific feature is available on the current host.
2569 ///
2570 /// This function is used to verify that any features enabled for a compiler
2571 /// backend, such as AVX support on x86\_64, are also available on the host.
2572 /// It is undefined behavior to execute an AVX instruction on a host that
2573 /// doesn't support AVX instructions, for example.
2574 ///
2575 /// When the `std` feature is active on this crate then this function is
2576 /// configured to a default implementation that uses the standard library's
2577 /// feature detection. When the `std` feature is disabled then there is no
2578 /// default available and this method must be called to configure a feature
2579 /// probing function.
2580 ///
2581 /// The `detect` function provided is given a string name of an ISA feature.
2582 /// The function should then return:
2583 ///
2584 /// * `Some(true)` - indicates that the feature was found on the host and it
2585 /// is supported.
2586 /// * `Some(false)` - the feature name was recognized but it was not
2587 /// detected on the host, for example the CPU is too old.
2588 /// * `None` - the feature name was not recognized and it's not known
2589 /// whether it's on the host or not.
2590 ///
2591 /// Feature names passed to `detect` match the same feature name used in the
2592 /// Rust standard library. For example `"sse4.2"` is used on x86\_64.
2593 ///
2594 /// # Unsafety
2595 ///
2596 /// This function is `unsafe` because it is undefined behavior to execute
2597 /// instructions that a host does not support. This means that the result of
2598 /// `detect` must be correct for memory safe execution at runtime.
2599 pub unsafe fn detect_host_feature(&mut self, detect: fn(&str) -> Option<bool>) -> &mut Self {
2600 self.detect_host_feature = Some(detect);
2601 self
2602 }
2603
2604 /// Configures Wasmtime to not use signals-based trap handlers, for example
2605 /// disables `SIGILL` and `SIGSEGV` handler registration on Unix platforms.
2606 ///
2607 /// Wasmtime will by default leverage signals-based trap handlers (or the
2608 /// platform equivalent, for example "vectored exception handlers" on
2609 /// Windows) to make generated code more efficient. For example an
2610 /// out-of-bounds load in WebAssembly will result in a `SIGSEGV` on Unix
2611 /// that is caught by a signal handler in Wasmtime by default. Another
2612 /// example is divide-by-zero is reported by hardware rather than
2613 /// explicitly checked and Wasmtime turns that into a trap.
2614 ///
2615 /// Some environments however may not have easy access to signal handlers.
2616 /// For example embedded scenarios may not support virtual memory. Other
2617 /// environments where Wasmtime is embedded within the surrounding
2618 /// environment may require that new signal handlers aren't registered due
2619 /// to the global nature of signal handlers. This option exists to disable
2620 /// the signal handler registration when required.
2621 ///
2622 /// When signals-based trap handlers are disabled then generated code will
2623 /// never rely on segfaults or other signals. Generated code will be slower
2624 /// because bounds checks must be explicit along with other operations like
2625 /// integer division which must check for zero.
2626 ///
2627 /// When this option is disable it additionally requires that the
2628 /// `enable_heap_access_spectre_mitigation` and
2629 /// `enable_table_access_spectre_mitigation` Cranelift settings are
2630 /// disabled. This means that generated code must have spectre mitigations
2631 /// disabled. This is because spectre mitigations rely on faults from
2632 /// loading from the null address to implement bounds checks.
2633 ///
2634 /// This option defaults to `true` meaning that signals-based trap handlers
2635 /// are enabled by default.
2636 ///
2637 /// **Note** Disabling this option is not compatible with the Winch compiler.
2638 pub fn signals_based_traps(&mut self, enable: bool) -> &mut Self {
2639 self.tunables.signals_based_traps = Some(enable);
2640 self
2641 }
2642}
2643
2644impl Default for Config {
2645 fn default() -> Config {
2646 Config::new()
2647 }
2648}
2649
2650impl fmt::Debug for Config {
2651 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2652 let mut f = f.debug_struct("Config");
2653
2654 // Not every flag in WasmFeatures can be enabled as part of creating
2655 // a Config. This impl gives a complete picture of all WasmFeatures
2656 // enabled, and doesn't require maintenance by hand (which has become out
2657 // of date in the past), at the cost of possible confusion for why
2658 // a flag in this set doesn't have a Config setter.
2659 let features = self.features();
2660 for flag in WasmFeatures::FLAGS.iter() {
2661 f.field(
2662 &format!("wasm_{}", flag.name().to_lowercase()),
2663 &features.contains(*flag.value()),
2664 );
2665 }
2666
2667 f.field("parallel_compilation", &self.parallel_compilation);
2668 #[cfg(any(feature = "cranelift", feature = "winch"))]
2669 {
2670 f.field("compiler_config", &self.compiler_config);
2671 }
2672
2673 self.tunables.format(&mut f);
2674 f.finish()
2675 }
2676}
2677
2678/// Possible Compilation strategies for a wasm module.
2679///
2680/// This is used as an argument to the [`Config::strategy`] method.
2681#[non_exhaustive]
2682#[derive(PartialEq, Eq, Clone, Debug, Copy)]
2683pub enum Strategy {
2684 /// An indicator that the compilation strategy should be automatically
2685 /// selected.
2686 ///
2687 /// This is generally what you want for most projects and indicates that the
2688 /// `wasmtime` crate itself should make the decision about what the best
2689 /// code generator for a wasm module is.
2690 ///
2691 /// Currently this always defaults to Cranelift, but the default value may
2692 /// change over time.
2693 Auto,
2694
2695 /// Currently the default backend, Cranelift aims to be a reasonably fast
2696 /// code generator which generates high quality machine code.
2697 Cranelift,
2698
2699 /// A baseline compiler for WebAssembly, currently under active development and not ready for
2700 /// production applications.
2701 Winch,
2702}
2703
2704#[cfg(any(feature = "winch", feature = "cranelift"))]
2705impl Strategy {
2706 fn not_auto(&self) -> Option<Strategy> {
2707 match self {
2708 Strategy::Auto => {
2709 if cfg!(feature = "cranelift") {
2710 Some(Strategy::Cranelift)
2711 } else if cfg!(feature = "winch") {
2712 Some(Strategy::Winch)
2713 } else {
2714 None
2715 }
2716 }
2717 other => Some(*other),
2718 }
2719 }
2720}
2721
2722/// Possible garbage collector implementations for Wasm.
2723///
2724/// This is used as an argument to the [`Config::collector`] method.
2725///
2726/// The properties of Wasmtime's available collectors are summarized in the
2727/// following table:
2728///
2729/// | Collector | Collects Garbage[^1] | Latency[^2] | Throughput[^3] | Allocation Speed[^4] | Heap Utilization[^5] |
2730/// |-----------------------------|----------------------|-------------|----------------|----------------------|----------------------|
2731/// | `DeferredReferenceCounting` | Yes, but not cycles | 🙂 | 🙁 | 😐 | 😐 |
2732/// | `Null` | No | 🙂 | 🙂 | 🙂 | 🙂 |
2733///
2734/// [^1]: Whether or not the collector is capable of collecting garbage and cyclic garbage.
2735///
2736/// [^2]: How long the Wasm program is paused during garbage
2737/// collections. Shorter is better. In general, better latency implies
2738/// worse throughput and vice versa.
2739///
2740/// [^3]: How fast the Wasm program runs when using this collector. Roughly
2741/// equivalent to the number of Wasm instructions executed per
2742/// second. Faster is better. In general, better throughput implies worse
2743/// latency and vice versa.
2744///
2745/// [^4]: How fast can individual objects be allocated?
2746///
2747/// [^5]: How many objects can the collector fit into N bytes of memory? That
2748/// is, how much space for bookkeeping and metadata does this collector
2749/// require? Less space taken up by metadata means more space for
2750/// additional objects. Reference counts are larger than mark bits and
2751/// free lists are larger than bump pointers, for example.
2752#[non_exhaustive]
2753#[derive(PartialEq, Eq, Clone, Debug, Copy)]
2754pub enum Collector {
2755 /// An indicator that the garbage collector should be automatically
2756 /// selected.
2757 ///
2758 /// This is generally what you want for most projects and indicates that the
2759 /// `wasmtime` crate itself should make the decision about what the best
2760 /// collector for a wasm module is.
2761 ///
2762 /// Currently this always defaults to the deferred reference-counting
2763 /// collector, but the default value may change over time.
2764 Auto,
2765
2766 /// The deferred reference-counting collector.
2767 ///
2768 /// A reference-counting collector, generally trading improved latency for
2769 /// worsened throughput. However, to avoid the largest overheads of
2770 /// reference counting, it avoids manipulating reference counts for Wasm
2771 /// objects on the stack. Instead, it will hold a reference count for an
2772 /// over-approximation of all objects that are currently on the stack, trace
2773 /// the stack during collection to find the precise set of on-stack roots,
2774 /// and decrement the reference count of any object that was in the
2775 /// over-approximation but not the precise set. This improves throughput,
2776 /// compared to "pure" reference counting, by performing many fewer
2777 /// refcount-increment and -decrement operations. The cost is the increased
2778 /// latency associated with tracing the stack.
2779 ///
2780 /// This collector cannot currently collect cycles; they will leak until the
2781 /// GC heap's store is dropped.
2782 DeferredReferenceCounting,
2783
2784 /// The null collector.
2785 ///
2786 /// This collector does not actually collect any garbage. It simply
2787 /// allocates objects until it runs out of memory, at which point further
2788 /// objects allocation attempts will trap.
2789 ///
2790 /// This collector is useful for incredibly short-running Wasm instances
2791 /// where additionally you would rather halt an over-allocating Wasm program
2792 /// than spend time collecting its garbage to allow it to keep running. It
2793 /// is also useful for measuring the overheads associated with other
2794 /// collectors, as this collector imposes as close to zero throughput and
2795 /// latency overhead as possible.
2796 Null,
2797}
2798
2799impl Default for Collector {
2800 fn default() -> Collector {
2801 Collector::Auto
2802 }
2803}
2804
2805#[cfg(feature = "gc")]
2806impl Collector {
2807 fn not_auto(&self) -> Option<Collector> {
2808 match self {
2809 Collector::Auto => {
2810 if cfg!(feature = "gc-drc") {
2811 Some(Collector::DeferredReferenceCounting)
2812 } else if cfg!(feature = "gc-null") {
2813 Some(Collector::Null)
2814 } else {
2815 None
2816 }
2817 }
2818 other => Some(*other),
2819 }
2820 }
2821
2822 fn try_not_auto(&self) -> Result<Self> {
2823 match self.not_auto() {
2824 #[cfg(feature = "gc-drc")]
2825 Some(c @ Collector::DeferredReferenceCounting) => Ok(c),
2826 #[cfg(not(feature = "gc-drc"))]
2827 Some(Collector::DeferredReferenceCounting) => bail!(
2828 "cannot create an engine using the deferred reference-counting \
2829 collector because the `gc-drc` feature was not enabled at \
2830 compile time",
2831 ),
2832
2833 #[cfg(feature = "gc-null")]
2834 Some(c @ Collector::Null) => Ok(c),
2835 #[cfg(not(feature = "gc-null"))]
2836 Some(Collector::Null) => bail!(
2837 "cannot create an engine using the null collector because \
2838 the `gc-null` feature was not enabled at compile time",
2839 ),
2840
2841 Some(Collector::Auto) => unreachable!(),
2842
2843 None => bail!(
2844 "cannot create an engine with GC support when none of the \
2845 collectors are available; enable one of the following \
2846 features: `gc-drc`, `gc-null`",
2847 ),
2848 }
2849 }
2850}
2851
2852/// Possible optimization levels for the Cranelift codegen backend.
2853#[non_exhaustive]
2854#[derive(Copy, Clone, Debug, Eq, PartialEq)]
2855pub enum OptLevel {
2856 /// No optimizations performed, minimizes compilation time by disabling most
2857 /// optimizations.
2858 None,
2859 /// Generates the fastest possible code, but may take longer.
2860 Speed,
2861 /// Similar to `speed`, but also performs transformations aimed at reducing
2862 /// code size.
2863 SpeedAndSize,
2864}
2865
2866/// Possible register allocator algorithms for the Cranelift codegen backend.
2867#[non_exhaustive]
2868#[derive(Copy, Clone, Debug, Eq, PartialEq)]
2869pub enum RegallocAlgorithm {
2870 /// Generates the fastest possible code, but may take longer.
2871 ///
2872 /// This algorithm performs "backtracking", which means that it may
2873 /// undo its earlier work and retry as it discovers conflicts. This
2874 /// results in better register utilization, producing fewer spills
2875 /// and moves, but can cause super-linear compile runtime.
2876 Backtracking,
2877}
2878
2879/// Select which profiling technique to support.
2880#[derive(Debug, Clone, Copy, PartialEq)]
2881pub enum ProfilingStrategy {
2882 /// No profiler support.
2883 None,
2884
2885 /// Collect function name information as the "perf map" file format, used with `perf` on Linux.
2886 PerfMap,
2887
2888 /// Collect profiling info for "jitdump" file format, used with `perf` on
2889 /// Linux.
2890 JitDump,
2891
2892 /// Collect profiling info using the "ittapi", used with `VTune` on Linux.
2893 VTune,
2894
2895 /// Support for profiling Pulley, Wasmtime's interpreter. Note that enabling
2896 /// this at runtime requires enabling the `profile-pulley` Cargo feature at
2897 /// compile time.
2898 Pulley,
2899}
2900
2901/// Select how wasm backtrace detailed information is handled.
2902#[derive(Debug, Clone, Copy)]
2903pub enum WasmBacktraceDetails {
2904 /// Support is unconditionally enabled and wasmtime will parse and read
2905 /// debug information.
2906 Enable,
2907
2908 /// Support is disabled, and wasmtime will not parse debug information for
2909 /// backtrace details.
2910 Disable,
2911
2912 /// Support for backtrace details is conditional on the
2913 /// `WASMTIME_BACKTRACE_DETAILS` environment variable.
2914 Environment,
2915}
2916
2917/// Describe the tri-state configuration of memory protection keys (MPK).
2918#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
2919pub enum MpkEnabled {
2920 /// Use MPK if supported by the current system; fall back to guard regions
2921 /// otherwise.
2922 Auto,
2923 /// Use MPK or fail if not supported.
2924 Enable,
2925 /// Do not use MPK.
2926 Disable,
2927}
2928
2929/// Configuration options used with [`InstanceAllocationStrategy::Pooling`] to
2930/// change the behavior of the pooling instance allocator.
2931///
2932/// This structure has a builder-style API in the same manner as [`Config`] and
2933/// is configured with [`Config::allocation_strategy`].
2934///
2935/// Note that usage of the pooling allocator does not affect compiled
2936/// WebAssembly code. Compiled `*.cwasm` files, for example, are usable both
2937/// with and without the pooling allocator.
2938///
2939/// ## Advantages of Pooled Allocation
2940///
2941/// The main benefit of the pooling allocator is to make WebAssembly
2942/// instantiation both faster and more scalable in terms of parallelism.
2943/// Allocation is faster because virtual memory is already configured and ready
2944/// to go within the pool, there's no need to [`mmap`] (for example on Unix) a
2945/// new region and configure it with guard pages. By avoiding [`mmap`] this
2946/// avoids whole-process virtual memory locks which can improve scalability and
2947/// performance through avoiding this.
2948///
2949/// Additionally with pooled allocation it's possible to create "affine slots"
2950/// to a particular WebAssembly module or component over time. For example if
2951/// the same module is multiple times over time the pooling allocator will, by
2952/// default, attempt to reuse the same slot. This mean that the slot has been
2953/// pre-configured and can retain virtual memory mappings for a copy-on-write
2954/// image, for example (see [`Config::memory_init_cow`] for more information.
2955/// This means that in a steady state instance deallocation is a single
2956/// [`madvise`] to reset linear memory to its original contents followed by a
2957/// single (optional) [`mprotect`] during the next instantiation to shrink
2958/// memory back to its original size. Compared to non-pooled allocation this
2959/// avoids the need to [`mmap`] a new region of memory, [`munmap`] it, and
2960/// [`mprotect`] regions too.
2961///
2962/// Another benefit of pooled allocation is that it's possible to configure
2963/// things such that no virtual memory management is required at all in a steady
2964/// state. For example a pooling allocator can be configured with:
2965///
2966/// * [`Config::memory_init_cow`] disabled
2967/// * [`Config::memory_guard_size`] disabled
2968/// * [`Config::memory_reservation`] shrunk to minimal size
2969/// * [`PoolingAllocationConfig::table_keep_resident`] sufficiently large
2970/// * [`PoolingAllocationConfig::linear_memory_keep_resident`] sufficiently large
2971///
2972/// With all these options in place no virtual memory tricks are used at all and
2973/// everything is manually managed by Wasmtime (for example resetting memory is
2974/// a `memset(0)`). This is not as fast in a single-threaded scenario but can
2975/// provide benefits in high-parallelism situations as no virtual memory locks
2976/// or IPIs need happen.
2977///
2978/// ## Disadvantages of Pooled Allocation
2979///
2980/// Despite the above advantages to instantiation performance the pooling
2981/// allocator is not enabled by default in Wasmtime. One reason is that the
2982/// performance advantages are not necessarily portable, for example while the
2983/// pooling allocator works on Windows it has not been tuned for performance on
2984/// Windows in the same way it has on Linux.
2985///
2986/// Additionally the main cost of the pooling allocator is that it requires a
2987/// very large reservation of virtual memory (on the order of most of the
2988/// addressable virtual address space). WebAssembly 32-bit linear memories in
2989/// Wasmtime are, by default 4G address space reservations with a small guard
2990/// region both before and after the linear memory. Memories in the pooling
2991/// allocator are contiguous which means that we only need a guard after linear
2992/// memory because the previous linear memory's slot post-guard is our own
2993/// pre-guard. This means that, by default, the pooling allocator uses roughly
2994/// 4G of virtual memory per WebAssembly linear memory slot. 4G of virtual
2995/// memory is 32 bits of a 64-bit address. Many 64-bit systems can only
2996/// actually use 48-bit addresses by default (although this can be extended on
2997/// architectures nowadays too), and of those 48 bits one of them is reserved
2998/// to indicate kernel-vs-userspace. This leaves 47-32=15 bits left,
2999/// meaning you can only have at most 32k slots of linear memories on many
3000/// systems by default. This is a relatively small number and shows how the
3001/// pooling allocator can quickly exhaust all of virtual memory.
3002///
3003/// Another disadvantage of the pooling allocator is that it may keep memory
3004/// alive when nothing is using it. A previously used slot for an instance might
3005/// have paged-in memory that will not get paged out until the
3006/// [`Engine`](crate::Engine) owning the pooling allocator is dropped. While
3007/// suitable for some applications this behavior may not be suitable for all
3008/// applications.
3009///
3010/// Finally the last disadvantage of the pooling allocator is that the
3011/// configuration values for the maximum number of instances, memories, tables,
3012/// etc, must all be fixed up-front. There's not always a clear answer as to
3013/// what these values should be so not all applications may be able to work
3014/// with this constraint.
3015///
3016/// [`madvise`]: https://man7.org/linux/man-pages/man2/madvise.2.html
3017/// [`mprotect`]: https://man7.org/linux/man-pages/man2/mprotect.2.html
3018/// [`mmap`]: https://man7.org/linux/man-pages/man2/mmap.2.html
3019/// [`munmap`]: https://man7.org/linux/man-pages/man2/munmap.2.html
3020#[cfg(feature = "pooling-allocator")]
3021#[derive(Debug, Clone, Default)]
3022pub struct PoolingAllocationConfig {
3023 config: crate::runtime::vm::PoolingInstanceAllocatorConfig,
3024}
3025
3026#[cfg(feature = "pooling-allocator")]
3027impl PoolingAllocationConfig {
3028 /// Returns a new configuration builder with all default settings
3029 /// configured.
3030 pub fn new() -> PoolingAllocationConfig {
3031 PoolingAllocationConfig::default()
3032 }
3033
3034 /// Configures the maximum number of "unused warm slots" to retain in the
3035 /// pooling allocator.
3036 ///
3037 /// The pooling allocator operates over slots to allocate from, and each
3038 /// slot is considered "cold" if it's never been used before or "warm" if
3039 /// it's been used by some module in the past. Slots in the pooling
3040 /// allocator additionally track an "affinity" flag to a particular core
3041 /// wasm module. When a module is instantiated into a slot then the slot is
3042 /// considered affine to that module, even after the instance has been
3043 /// deallocated.
3044 ///
3045 /// When a new instance is created then a slot must be chosen, and the
3046 /// current algorithm for selecting a slot is:
3047 ///
3048 /// * If there are slots that are affine to the module being instantiated,
3049 /// then the most recently used slot is selected to be allocated from.
3050 /// This is done to improve reuse of resources such as memory mappings and
3051 /// additionally try to benefit from temporal locality for things like
3052 /// caches.
3053 ///
3054 /// * Otherwise if there are more than N affine slots to other modules, then
3055 /// one of those affine slots is chosen to be allocated. The slot chosen
3056 /// is picked on a least-recently-used basis.
3057 ///
3058 /// * Finally, if there are less than N affine slots to other modules, then
3059 /// the non-affine slots are allocated from.
3060 ///
3061 /// This setting, `max_unused_warm_slots`, is the value for N in the above
3062 /// algorithm. The purpose of this setting is to have a knob over the RSS
3063 /// impact of "unused slots" for a long-running wasm server.
3064 ///
3065 /// If this setting is set to 0, for example, then affine slots are
3066 /// aggressively reused on a least-recently-used basis. A "cold" slot is
3067 /// only used if there are no affine slots available to allocate from. This
3068 /// means that the set of slots used over the lifetime of a program is the
3069 /// same as the maximum concurrent number of wasm instances.
3070 ///
3071 /// If this setting is set to infinity, however, then cold slots are
3072 /// prioritized to be allocated from. This means that the set of slots used
3073 /// over the lifetime of a program will approach
3074 /// [`PoolingAllocationConfig::total_memories`], or the maximum number of
3075 /// slots in the pooling allocator.
3076 ///
3077 /// Wasmtime does not aggressively decommit all resources associated with a
3078 /// slot when the slot is not in use. For example the
3079 /// [`PoolingAllocationConfig::linear_memory_keep_resident`] option can be
3080 /// used to keep memory associated with a slot, even when it's not in use.
3081 /// This means that the total set of used slots in the pooling instance
3082 /// allocator can impact the overall RSS usage of a program.
3083 ///
3084 /// The default value for this option is `100`.
3085 pub fn max_unused_warm_slots(&mut self, max: u32) -> &mut Self {
3086 self.config.max_unused_warm_slots = max;
3087 self
3088 }
3089
3090 /// The target number of decommits to do per batch.
3091 ///
3092 /// This is not precise, as we can queue up decommits at times when we
3093 /// aren't prepared to immediately flush them, and so we may go over this
3094 /// target size occasionally.
3095 ///
3096 /// A batch size of one effectively disables batching.
3097 ///
3098 /// Defaults to `1`.
3099 pub fn decommit_batch_size(&mut self, batch_size: usize) -> &mut Self {
3100 self.config.decommit_batch_size = batch_size;
3101 self
3102 }
3103
3104 /// How much memory, in bytes, to keep resident for async stacks allocated
3105 /// with the pooling allocator.
3106 ///
3107 /// When [`PoolingAllocationConfig::async_stack_zeroing`] is enabled then
3108 /// Wasmtime will reset the contents of async stacks back to zero upon
3109 /// deallocation. This option can be used to perform the zeroing operation
3110 /// with `memset` up to a certain threshold of bytes instead of using system
3111 /// calls to reset the stack to zero.
3112 ///
3113 /// Note that when using this option the memory with async stacks will
3114 /// never be decommitted.
3115 #[cfg(feature = "async")]
3116 pub fn async_stack_keep_resident(&mut self, size: usize) -> &mut Self {
3117 self.config.async_stack_keep_resident = size;
3118 self
3119 }
3120
3121 /// How much memory, in bytes, to keep resident for each linear memory
3122 /// after deallocation.
3123 ///
3124 /// This option is only applicable on Linux and has no effect on other
3125 /// platforms.
3126 ///
3127 /// By default Wasmtime will use `madvise` to reset the entire contents of
3128 /// linear memory back to zero when a linear memory is deallocated. This
3129 /// option can be used to use `memset` instead to set memory back to zero
3130 /// which can, in some configurations, reduce the number of page faults
3131 /// taken when a slot is reused.
3132 pub fn linear_memory_keep_resident(&mut self, size: usize) -> &mut Self {
3133 self.config.linear_memory_keep_resident = size;
3134 self
3135 }
3136
3137 /// How much memory, in bytes, to keep resident for each table after
3138 /// deallocation.
3139 ///
3140 /// This option is only applicable on Linux and has no effect on other
3141 /// platforms.
3142 ///
3143 /// This option is the same as
3144 /// [`PoolingAllocationConfig::linear_memory_keep_resident`] except that it
3145 /// is applicable to tables instead.
3146 pub fn table_keep_resident(&mut self, size: usize) -> &mut Self {
3147 self.config.table_keep_resident = size;
3148 self
3149 }
3150
3151 /// The maximum number of concurrent component instances supported (default
3152 /// is `1000`).
3153 ///
3154 /// This provides an upper-bound on the total size of component
3155 /// metadata-related allocations, along with
3156 /// [`PoolingAllocationConfig::max_component_instance_size`]. The upper bound is
3157 ///
3158 /// ```text
3159 /// total_component_instances * max_component_instance_size
3160 /// ```
3161 ///
3162 /// where `max_component_instance_size` is rounded up to the size and alignment
3163 /// of the internal representation of the metadata.
3164 pub fn total_component_instances(&mut self, count: u32) -> &mut Self {
3165 self.config.limits.total_component_instances = count;
3166 self
3167 }
3168
3169 /// The maximum size, in bytes, allocated for a component instance's
3170 /// `VMComponentContext` metadata.
3171 ///
3172 /// The [`wasmtime::component::Instance`][crate::component::Instance] type
3173 /// has a static size but its internal `VMComponentContext` is dynamically
3174 /// sized depending on the component being instantiated. This size limit
3175 /// loosely correlates to the size of the component, taking into account
3176 /// factors such as:
3177 ///
3178 /// * number of lifted and lowered functions,
3179 /// * number of memories
3180 /// * number of inner instances
3181 /// * number of resources
3182 ///
3183 /// If the allocated size per instance is too small then instantiation of a
3184 /// module will fail at runtime with an error indicating how many bytes were
3185 /// needed.
3186 ///
3187 /// The default value for this is 1MiB.
3188 ///
3189 /// This provides an upper-bound on the total size of component
3190 /// metadata-related allocations, along with
3191 /// [`PoolingAllocationConfig::total_component_instances`]. The upper bound is
3192 ///
3193 /// ```text
3194 /// total_component_instances * max_component_instance_size
3195 /// ```
3196 ///
3197 /// where `max_component_instance_size` is rounded up to the size and alignment
3198 /// of the internal representation of the metadata.
3199 pub fn max_component_instance_size(&mut self, size: usize) -> &mut Self {
3200 self.config.limits.component_instance_size = size;
3201 self
3202 }
3203
3204 /// The maximum number of core instances a single component may contain
3205 /// (default is unlimited).
3206 ///
3207 /// This method (along with
3208 /// [`PoolingAllocationConfig::max_memories_per_component`],
3209 /// [`PoolingAllocationConfig::max_tables_per_component`], and
3210 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3211 /// the amount of resources a single component allocation consumes.
3212 ///
3213 /// If a component will instantiate more core instances than `count`, then
3214 /// the component will fail to instantiate.
3215 pub fn max_core_instances_per_component(&mut self, count: u32) -> &mut Self {
3216 self.config.limits.max_core_instances_per_component = count;
3217 self
3218 }
3219
3220 /// The maximum number of Wasm linear memories that a single component may
3221 /// transitively contain (default is unlimited).
3222 ///
3223 /// This method (along with
3224 /// [`PoolingAllocationConfig::max_core_instances_per_component`],
3225 /// [`PoolingAllocationConfig::max_tables_per_component`], and
3226 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3227 /// the amount of resources a single component allocation consumes.
3228 ///
3229 /// If a component transitively contains more linear memories than `count`,
3230 /// then the component will fail to instantiate.
3231 pub fn max_memories_per_component(&mut self, count: u32) -> &mut Self {
3232 self.config.limits.max_memories_per_component = count;
3233 self
3234 }
3235
3236 /// The maximum number of tables that a single component may transitively
3237 /// contain (default is unlimited).
3238 ///
3239 /// This method (along with
3240 /// [`PoolingAllocationConfig::max_core_instances_per_component`],
3241 /// [`PoolingAllocationConfig::max_memories_per_component`],
3242 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3243 /// the amount of resources a single component allocation consumes.
3244 ///
3245 /// If a component will transitively contains more tables than `count`, then
3246 /// the component will fail to instantiate.
3247 pub fn max_tables_per_component(&mut self, count: u32) -> &mut Self {
3248 self.config.limits.max_tables_per_component = count;
3249 self
3250 }
3251
3252 /// The maximum number of concurrent Wasm linear memories supported (default
3253 /// is `1000`).
3254 ///
3255 /// This value has a direct impact on the amount of memory allocated by the pooling
3256 /// instance allocator.
3257 ///
3258 /// The pooling instance allocator allocates a memory pool, where each entry
3259 /// in the pool contains the reserved address space for each linear memory
3260 /// supported by an instance.
3261 ///
3262 /// The memory pool will reserve a large quantity of host process address
3263 /// space to elide the bounds checks required for correct WebAssembly memory
3264 /// semantics. Even with 64-bit address spaces, the address space is limited
3265 /// when dealing with a large number of linear memories.
3266 ///
3267 /// For example, on Linux x86_64, the userland address space limit is 128
3268 /// TiB. That might seem like a lot, but each linear memory will *reserve* 6
3269 /// GiB of space by default.
3270 pub fn total_memories(&mut self, count: u32) -> &mut Self {
3271 self.config.limits.total_memories = count;
3272 self
3273 }
3274
3275 /// The maximum number of concurrent tables supported (default is `1000`).
3276 ///
3277 /// This value has a direct impact on the amount of memory allocated by the
3278 /// pooling instance allocator.
3279 ///
3280 /// The pooling instance allocator allocates a table pool, where each entry
3281 /// in the pool contains the space needed for each WebAssembly table
3282 /// supported by an instance (see `table_elements` to control the size of
3283 /// each table).
3284 pub fn total_tables(&mut self, count: u32) -> &mut Self {
3285 self.config.limits.total_tables = count;
3286 self
3287 }
3288
3289 /// The maximum number of execution stacks allowed for asynchronous
3290 /// execution, when enabled (default is `1000`).
3291 ///
3292 /// This value has a direct impact on the amount of memory allocated by the
3293 /// pooling instance allocator.
3294 #[cfg(feature = "async")]
3295 pub fn total_stacks(&mut self, count: u32) -> &mut Self {
3296 self.config.limits.total_stacks = count;
3297 self
3298 }
3299
3300 /// The maximum number of concurrent core instances supported (default is
3301 /// `1000`).
3302 ///
3303 /// This provides an upper-bound on the total size of core instance
3304 /// metadata-related allocations, along with
3305 /// [`PoolingAllocationConfig::max_core_instance_size`]. The upper bound is
3306 ///
3307 /// ```text
3308 /// total_core_instances * max_core_instance_size
3309 /// ```
3310 ///
3311 /// where `max_core_instance_size` is rounded up to the size and alignment of
3312 /// the internal representation of the metadata.
3313 pub fn total_core_instances(&mut self, count: u32) -> &mut Self {
3314 self.config.limits.total_core_instances = count;
3315 self
3316 }
3317
3318 /// The maximum size, in bytes, allocated for a core instance's `VMContext`
3319 /// metadata.
3320 ///
3321 /// The [`Instance`][crate::Instance] type has a static size but its
3322 /// `VMContext` metadata is dynamically sized depending on the module being
3323 /// instantiated. This size limit loosely correlates to the size of the Wasm
3324 /// module, taking into account factors such as:
3325 ///
3326 /// * number of functions
3327 /// * number of globals
3328 /// * number of memories
3329 /// * number of tables
3330 /// * number of function types
3331 ///
3332 /// If the allocated size per instance is too small then instantiation of a
3333 /// module will fail at runtime with an error indicating how many bytes were
3334 /// needed.
3335 ///
3336 /// The default value for this is 1MiB.
3337 ///
3338 /// This provides an upper-bound on the total size of core instance
3339 /// metadata-related allocations, along with
3340 /// [`PoolingAllocationConfig::total_core_instances`]. The upper bound is
3341 ///
3342 /// ```text
3343 /// total_core_instances * max_core_instance_size
3344 /// ```
3345 ///
3346 /// where `max_core_instance_size` is rounded up to the size and alignment of
3347 /// the internal representation of the metadata.
3348 pub fn max_core_instance_size(&mut self, size: usize) -> &mut Self {
3349 self.config.limits.core_instance_size = size;
3350 self
3351 }
3352
3353 /// The maximum number of defined tables for a core module (default is `1`).
3354 ///
3355 /// This value controls the capacity of the `VMTableDefinition` table in
3356 /// each instance's `VMContext` structure.
3357 ///
3358 /// The allocated size of the table will be `tables *
3359 /// sizeof(VMTableDefinition)` for each instance regardless of how many
3360 /// tables are defined by an instance's module.
3361 pub fn max_tables_per_module(&mut self, tables: u32) -> &mut Self {
3362 self.config.limits.max_tables_per_module = tables;
3363 self
3364 }
3365
3366 /// The maximum table elements for any table defined in a module (default is
3367 /// `20000`).
3368 ///
3369 /// If a table's minimum element limit is greater than this value, the
3370 /// module will fail to instantiate.
3371 ///
3372 /// If a table's maximum element limit is unbounded or greater than this
3373 /// value, the maximum will be `table_elements` for the purpose of any
3374 /// `table.grow` instruction.
3375 ///
3376 /// This value is used to reserve the maximum space for each supported
3377 /// table; table elements are pointer-sized in the Wasmtime runtime.
3378 /// Therefore, the space reserved for each instance is `tables *
3379 /// table_elements * sizeof::<*const ()>`.
3380 pub fn table_elements(&mut self, elements: usize) -> &mut Self {
3381 self.config.limits.table_elements = elements;
3382 self
3383 }
3384
3385 /// The maximum number of defined linear memories for a module (default is
3386 /// `1`).
3387 ///
3388 /// This value controls the capacity of the `VMMemoryDefinition` table in
3389 /// each core instance's `VMContext` structure.
3390 ///
3391 /// The allocated size of the table will be `memories *
3392 /// sizeof(VMMemoryDefinition)` for each core instance regardless of how
3393 /// many memories are defined by the core instance's module.
3394 pub fn max_memories_per_module(&mut self, memories: u32) -> &mut Self {
3395 self.config.limits.max_memories_per_module = memories;
3396 self
3397 }
3398
3399 /// The maximum byte size that any WebAssembly linear memory may grow to.
3400 ///
3401 /// This option defaults to 4 GiB meaning that for 32-bit linear memories
3402 /// there is no restrictions. 64-bit linear memories will not be allowed to
3403 /// grow beyond 4 GiB by default.
3404 ///
3405 /// If a memory's minimum size is greater than this value, the module will
3406 /// fail to instantiate.
3407 ///
3408 /// If a memory's maximum size is unbounded or greater than this value, the
3409 /// maximum will be `max_memory_size` for the purpose of any `memory.grow`
3410 /// instruction.
3411 ///
3412 /// This value is used to control the maximum accessible space for each
3413 /// linear memory of a core instance. This can be thought of as a simple
3414 /// mechanism like [`Store::limiter`](crate::Store::limiter) to limit memory
3415 /// at runtime. This value can also affect striping/coloring behavior when
3416 /// used in conjunction with
3417 /// [`memory_protection_keys`](PoolingAllocationConfig::memory_protection_keys).
3418 ///
3419 /// The virtual memory reservation size of each linear memory is controlled
3420 /// by the [`Config::memory_reservation`] setting and this method's
3421 /// configuration cannot exceed [`Config::memory_reservation`].
3422 pub fn max_memory_size(&mut self, bytes: usize) -> &mut Self {
3423 self.config.limits.max_memory_size = bytes;
3424 self
3425 }
3426
3427 /// Configures whether memory protection keys (MPK) should be used for more
3428 /// efficient layout of pool-allocated memories.
3429 ///
3430 /// When using the pooling allocator (see [`Config::allocation_strategy`],
3431 /// [`InstanceAllocationStrategy::Pooling`]), memory protection keys can
3432 /// reduce the total amount of allocated virtual memory by eliminating guard
3433 /// regions between WebAssembly memories in the pool. It does so by
3434 /// "coloring" memory regions with different memory keys and setting which
3435 /// regions are accessible each time executions switches from host to guest
3436 /// (or vice versa).
3437 ///
3438 /// Leveraging MPK requires configuring a smaller-than-default
3439 /// [`max_memory_size`](PoolingAllocationConfig::max_memory_size) to enable
3440 /// this coloring/striping behavior. For example embeddings might want to
3441 /// reduce the default 4G allowance to 128M.
3442 ///
3443 /// MPK is only available on Linux (called `pku` there) and recent x86
3444 /// systems; we check for MPK support at runtime by examining the `CPUID`
3445 /// register. This configuration setting can be in three states:
3446 ///
3447 /// - `auto`: if MPK support is available the guard regions are removed; if
3448 /// not, the guard regions remain
3449 /// - `enable`: use MPK to eliminate guard regions; fail if MPK is not
3450 /// supported
3451 /// - `disable`: never use MPK
3452 ///
3453 /// By default this value is `disabled`, but may become `auto` in future
3454 /// releases.
3455 ///
3456 /// __WARNING__: this configuration options is still experimental--use at
3457 /// your own risk! MPK uses kernel and CPU features to protect memory
3458 /// regions; you may observe segmentation faults if anything is
3459 /// misconfigured.
3460 #[cfg(feature = "memory-protection-keys")]
3461 pub fn memory_protection_keys(&mut self, enable: MpkEnabled) -> &mut Self {
3462 self.config.memory_protection_keys = enable;
3463 self
3464 }
3465
3466 /// Sets an upper limit on how many memory protection keys (MPK) Wasmtime
3467 /// will use.
3468 ///
3469 /// This setting is only applicable when
3470 /// [`PoolingAllocationConfig::memory_protection_keys`] is set to `enable`
3471 /// or `auto`. Configuring this above the HW and OS limits (typically 15)
3472 /// has no effect.
3473 ///
3474 /// If multiple Wasmtime engines are used in the same process, note that all
3475 /// engines will share the same set of allocated keys; this setting will
3476 /// limit how many keys are allocated initially and thus available to all
3477 /// other engines.
3478 #[cfg(feature = "memory-protection-keys")]
3479 pub fn max_memory_protection_keys(&mut self, max: usize) -> &mut Self {
3480 self.config.max_memory_protection_keys = max;
3481 self
3482 }
3483
3484 /// Check if memory protection keys (MPK) are available on the current host.
3485 ///
3486 /// This is a convenience method for determining MPK availability using the
3487 /// same method that [`MpkEnabled::Auto`] does. See
3488 /// [`PoolingAllocationConfig::memory_protection_keys`] for more
3489 /// information.
3490 #[cfg(feature = "memory-protection-keys")]
3491 pub fn are_memory_protection_keys_available() -> bool {
3492 crate::runtime::vm::mpk::is_supported()
3493 }
3494
3495 /// The maximum number of concurrent GC heaps supported (default is `1000`).
3496 ///
3497 /// This value has a direct impact on the amount of memory allocated by the
3498 /// pooling instance allocator.
3499 ///
3500 /// The pooling instance allocator allocates a GC heap pool, where each
3501 /// entry in the pool contains the space needed for each GC heap used by a
3502 /// store.
3503 #[cfg(feature = "gc")]
3504 pub fn total_gc_heaps(&mut self, count: u32) -> &mut Self {
3505 self.config.limits.total_gc_heaps = count;
3506 self
3507 }
3508}
3509
3510#[cfg(feature = "std")]
3511fn detect_host_feature(feature: &str) -> Option<bool> {
3512 #[cfg(target_arch = "aarch64")]
3513 {
3514 return match feature {
3515 "lse" => Some(std::arch::is_aarch64_feature_detected!("lse")),
3516 "paca" => Some(std::arch::is_aarch64_feature_detected!("paca")),
3517 "fp16" => Some(std::arch::is_aarch64_feature_detected!("fp16")),
3518
3519 _ => None,
3520 };
3521 }
3522
3523 // There is no is_s390x_feature_detected macro yet, so for now
3524 // we use getauxval from the libc crate directly.
3525 #[cfg(all(target_arch = "s390x", target_os = "linux"))]
3526 {
3527 let v = unsafe { libc::getauxval(libc::AT_HWCAP) };
3528 const HWCAP_S390X_VXRS_EXT2: libc::c_ulong = 32768;
3529
3530 return match feature {
3531 // There is no separate HWCAP bit for mie2, so assume
3532 // that any machine with vxrs_ext2 also has mie2.
3533 "vxrs_ext2" | "mie2" => Some((v & HWCAP_S390X_VXRS_EXT2) != 0),
3534
3535 _ => None,
3536 };
3537 }
3538
3539 #[cfg(target_arch = "riscv64")]
3540 {
3541 return match feature {
3542 // due to `is_riscv64_feature_detected` is not stable.
3543 // we cannot use it. For now lie and say all features are always
3544 // found to keep tests working.
3545 _ => Some(true),
3546 };
3547 }
3548
3549 #[cfg(target_arch = "x86_64")]
3550 {
3551 return match feature {
3552 "cmpxchg16b" => Some(std::is_x86_feature_detected!("cmpxchg16b")),
3553 "sse3" => Some(std::is_x86_feature_detected!("sse3")),
3554 "ssse3" => Some(std::is_x86_feature_detected!("ssse3")),
3555 "sse4.1" => Some(std::is_x86_feature_detected!("sse4.1")),
3556 "sse4.2" => Some(std::is_x86_feature_detected!("sse4.2")),
3557 "popcnt" => Some(std::is_x86_feature_detected!("popcnt")),
3558 "avx" => Some(std::is_x86_feature_detected!("avx")),
3559 "avx2" => Some(std::is_x86_feature_detected!("avx2")),
3560 "fma" => Some(std::is_x86_feature_detected!("fma")),
3561 "bmi1" => Some(std::is_x86_feature_detected!("bmi1")),
3562 "bmi2" => Some(std::is_x86_feature_detected!("bmi2")),
3563 "avx512bitalg" => Some(std::is_x86_feature_detected!("avx512bitalg")),
3564 "avx512dq" => Some(std::is_x86_feature_detected!("avx512dq")),
3565 "avx512f" => Some(std::is_x86_feature_detected!("avx512f")),
3566 "avx512vl" => Some(std::is_x86_feature_detected!("avx512vl")),
3567 "avx512vbmi" => Some(std::is_x86_feature_detected!("avx512vbmi")),
3568 "lzcnt" => Some(std::is_x86_feature_detected!("lzcnt")),
3569
3570 _ => None,
3571 };
3572 }
3573
3574 #[allow(unreachable_code)]
3575 {
3576 let _ = feature;
3577 return None;
3578 }
3579}