1 //! Contains the common Wasmtime command line interface (CLI) flags. 2 3 use anyhow::Result; 4 use clap::Parser; 5 use std::time::Duration; 6 use wasmtime::Config; 7 8 pub mod opt; 9 10 #[cfg(feature = "logging")] 11 fn init_file_per_thread_logger(prefix: &'static str) { 12 file_per_thread_logger::initialize(prefix); 13 file_per_thread_logger::allow_uninitialized(); 14 15 // Extending behavior of default spawner: 16 // https://docs.rs/rayon/1.1.0/rayon/struct.ThreadPoolBuilder.html#method.spawn_handler 17 // Source code says DefaultSpawner is implementation detail and 18 // shouldn't be used directly. 19 #[cfg(feature = "parallel-compilation")] 20 rayon::ThreadPoolBuilder::new() 21 .spawn_handler(move |thread| { 22 let mut b = std::thread::Builder::new(); 23 if let Some(name) = thread.name() { 24 b = b.name(name.to_owned()); 25 } 26 if let Some(stack_size) = thread.stack_size() { 27 b = b.stack_size(stack_size); 28 } 29 b.spawn(move || { 30 file_per_thread_logger::initialize(prefix); 31 thread.run() 32 })?; 33 Ok(()) 34 }) 35 .build_global() 36 .unwrap(); 37 } 38 39 wasmtime_option_group! { 40 #[derive(PartialEq, Clone)] 41 pub struct OptimizeOptions { 42 /// Optimization level of generated code (0-2, s; default: 0) 43 pub opt_level: Option<wasmtime::OptLevel>, 44 45 /// Byte size of the guard region after dynamic memories are allocated 46 pub dynamic_memory_guard_size: Option<u64>, 47 48 /// Force using a "static" style for all wasm memories 49 pub static_memory_forced: Option<bool>, 50 51 /// Maximum size in bytes of wasm memory before it becomes dynamically 52 /// relocatable instead of up-front-reserved. 53 pub static_memory_maximum_size: Option<u64>, 54 55 /// Byte size of the guard region after static memories are allocated 56 pub static_memory_guard_size: Option<u64>, 57 58 /// Bytes to reserve at the end of linear memory for growth for dynamic 59 /// memories. 60 pub dynamic_memory_reserved_for_growth: Option<u64>, 61 62 /// Enable the pooling allocator, in place of the on-demand allocator. 63 pub pooling_allocator: Option<bool>, 64 65 /// How many bytes to keep resident between instantiations for the 66 /// pooling allocator in linear memories. 67 pub pooling_memory_keep_resident: Option<usize>, 68 69 /// How many bytes to keep resident between instantiations for the 70 /// pooling allocator in tables. 71 pub pooling_table_keep_resident: Option<usize>, 72 73 /// Enable memory protection keys for the pooling allocator; this can 74 /// optimize the size of memory slots. 75 pub memory_protection_keys: Option<bool>, 76 77 /// Configure attempting to initialize linear memory via a 78 /// copy-on-write mapping (default: yes) 79 pub memory_init_cow: Option<bool>, 80 } 81 82 enum Optimize { 83 ... 84 } 85 } 86 87 wasmtime_option_group! { 88 #[derive(PartialEq, Clone)] 89 pub struct CodegenOptions { 90 /// Either `cranelift` or `winch`. 91 /// 92 /// Currently only `cranelift` and `winch` are supported, but not all 93 /// builds of Wasmtime have both built in. 94 pub compiler: Option<wasmtime::Strategy>, 95 /// Enable Cranelift's internal debug verifier (expensive) 96 pub cranelift_debug_verifier: Option<bool>, 97 /// Whether or not to enable caching of compiled modules. 98 pub cache: Option<bool>, 99 /// Configuration for compiled module caching. 100 pub cache_config: Option<String>, 101 /// Whether or not to enable parallel compilation of modules. 102 pub parallel_compilation: Option<bool>, 103 /// Whether to enable proof-carrying code (PCC)-based validation. 104 pub pcc: Option<bool>, 105 106 #[prefixed = "cranelift"] 107 /// Set a cranelift-specific option. Use `wasmtime settings` to see 108 /// all. 109 pub cranelift: Vec<(String, Option<String>)>, 110 } 111 112 enum Codegen { 113 ... 114 } 115 } 116 117 wasmtime_option_group! { 118 #[derive(PartialEq, Clone)] 119 pub struct DebugOptions { 120 /// Enable generation of DWARF debug information in compiled code. 121 pub debug_info: Option<bool>, 122 /// Configure whether compiled code can map native addresses to wasm. 123 pub address_map: Option<bool>, 124 /// Configure whether logging is enabled. 125 pub logging: Option<bool>, 126 /// Configure whether logs are emitted to files 127 pub log_to_files: Option<bool>, 128 /// Enable coredump generation to this file after a WebAssembly trap. 129 pub coredump: Option<String>, 130 } 131 132 enum Debug { 133 ... 134 } 135 } 136 137 wasmtime_option_group! { 138 #[derive(PartialEq, Clone)] 139 pub struct WasmOptions { 140 /// Enable canonicalization of all NaN values. 141 pub nan_canonicalization: Option<bool>, 142 /// Enable execution fuel with N units fuel, trapping after running out 143 /// of fuel. 144 /// 145 /// Most WebAssembly instructions consume 1 unit of fuel. Some 146 /// instructions, such as `nop`, `drop`, `block`, and `loop`, consume 0 147 /// units, as any execution cost associated with them involves other 148 /// instructions which do consume fuel. 149 pub fuel: Option<u64>, 150 /// Yield when a global epoch counter changes, allowing for async 151 /// operation without blocking the executor. 152 pub epoch_interruption: Option<bool>, 153 /// Maximum stack size, in bytes, that wasm is allowed to consume before a 154 /// stack overflow is reported. 155 pub max_wasm_stack: Option<usize>, 156 /// Allow unknown exports when running commands. 157 pub unknown_exports_allow: Option<bool>, 158 /// Allow the main module to import unknown functions, using an 159 /// implementation that immediately traps, when running commands. 160 pub unknown_imports_trap: Option<bool>, 161 /// Allow the main module to import unknown functions, using an 162 /// implementation that returns default values, when running commands. 163 pub unknown_imports_default: Option<bool>, 164 /// Enables memory error checking. (see wmemcheck.md for more info) 165 pub wmemcheck: Option<bool>, 166 /// Maximum size, in bytes, that a linear memory is allowed to reach. 167 /// 168 /// Growth beyond this limit will cause `memory.grow` instructions in 169 /// WebAssembly modules to return -1 and fail. 170 pub max_memory_size: Option<usize>, 171 /// Maximum size, in table elements, that a table is allowed to reach. 172 pub max_table_elements: Option<u32>, 173 /// Maximum number of WebAssembly instances allowed to be created. 174 pub max_instances: Option<usize>, 175 /// Maximum number of WebAssembly tables allowed to be created. 176 pub max_tables: Option<usize>, 177 /// Maximum number of WebAssembly linear memories allowed to be created. 178 pub max_memories: Option<usize>, 179 /// Force a trap to be raised on `memory.grow` and `table.grow` failure 180 /// instead of returning -1 from these instructions. 181 /// 182 /// This is not necessarily a spec-compliant option to enable but can be 183 /// useful for tracking down a backtrace of what is requesting so much 184 /// memory, for example. 185 pub trap_on_grow_failure: Option<bool>, 186 /// Maximum execution time of wasm code before timing out (1, 2s, 100ms, etc) 187 pub timeout: Option<Duration>, 188 /// Configures support for all WebAssembly proposals implemented. 189 pub all_proposals: Option<bool>, 190 /// Configure support for the bulk memory proposal. 191 pub bulk_memory: Option<bool>, 192 /// Configure support for the multi-memory proposal. 193 pub multi_memory: Option<bool>, 194 /// Configure support for the multi-value proposal. 195 pub multi_value: Option<bool>, 196 /// Configure support for the reference-types proposal. 197 pub reference_types: Option<bool>, 198 /// Configure support for the simd proposal. 199 pub simd: Option<bool>, 200 /// Configure support for the relaxed-simd proposal. 201 pub relaxed_simd: Option<bool>, 202 /// Configure forcing deterministic and host-independent behavior of 203 /// the relaxed-simd instructions. 204 /// 205 /// By default these instructions may have architecture-specific behavior as 206 /// allowed by the specification, but this can be used to force the behavior 207 /// of these instructions to match the deterministic behavior classified in 208 /// the specification. Note that enabling this option may come at a 209 /// performance cost. 210 pub relaxed_simd_deterministic: Option<bool>, 211 /// Configure support for the tail-call proposal. 212 pub tail_call: Option<bool>, 213 /// Configure support for the threads proposal. 214 pub threads: Option<bool>, 215 /// Configure support for the memory64 proposal. 216 pub memory64: Option<bool>, 217 /// Configure support for the component-model proposal. 218 pub component_model: Option<bool>, 219 /// Configure support for the function-references proposal. 220 pub function_references: Option<bool>, 221 } 222 223 enum Wasm { 224 ... 225 } 226 } 227 228 wasmtime_option_group! { 229 #[derive(PartialEq, Clone)] 230 pub struct WasiOptions { 231 /// Enable support for WASI common APIs 232 pub common: Option<bool>, 233 /// Enable suport for WASI neural network API (experimental) 234 pub nn: Option<bool>, 235 /// Enable suport for WASI threading API (experimental) 236 pub threads: Option<bool>, 237 /// Enable suport for WASI HTTP API (experimental) 238 pub http: Option<bool>, 239 /// Inherit environment variables and file descriptors following the 240 /// systemd listen fd specification (UNIX only) 241 pub listenfd: Option<bool>, 242 /// Grant access to the given TCP listen socket 243 pub tcplisten: Vec<String>, 244 /// Implement WASI with preview2 primitives (experimental). 245 /// 246 /// Indicates that the implementation of WASI preview1 should be backed by 247 /// the preview2 implementation for components. 248 /// 249 /// This will become the default in the future and this option will be 250 /// removed. For now this is primarily here for testing. 251 pub preview2: Option<bool>, 252 /// Pre-load machine learning graphs (i.e., models) for use by wasi-nn. 253 /// 254 /// Each use of the flag will preload a ML model from the host directory 255 /// using the given model encoding. The model will be mapped to the 256 /// directory name: e.g., `--wasi-nn-graph openvino:/foo/bar` will preload 257 /// an OpenVINO model named `bar`. Note that which model encodings are 258 /// available is dependent on the backends implemented in the 259 /// `wasmtime_wasi_nn` crate. 260 pub nn_graph: Vec<WasiNnGraph>, 261 /// Flag for WASI preview2 to inherit the host's network within the 262 /// guest so it has full access to all addresses/ports/etc. 263 pub inherit_network: Option<bool>, 264 /// Indicates whether `wasi:sockets/ip-name-lookup` is enabled or not. 265 pub allow_ip_name_lookup: Option<bool>, 266 /// Indicates whether `wasi:sockets` TCP support is enabled or not. 267 pub tcp: Option<bool>, 268 /// Indicates whether `wasi:sockets` UDP support is enabled or not. 269 pub udp: Option<bool>, 270 /// Allows imports from the `wasi_unstable` core wasm module. 271 pub preview0: Option<bool>, 272 } 273 274 enum Wasi { 275 ... 276 } 277 } 278 279 #[derive(Debug, Clone, PartialEq)] 280 pub struct WasiNnGraph { 281 pub format: String, 282 pub dir: String, 283 } 284 285 /// Common options for commands that translate WebAssembly modules 286 #[derive(Parser, Clone)] 287 pub struct CommonOptions { 288 // These options groups are used to parse `-O` and such options but aren't 289 // the raw form consumed by the CLI. Instead they're pushed into the `pub` 290 // fields below as part of the `configure` method. 291 // 292 // Ideally clap would support `pub opts: OptimizeOptions` and parse directly 293 // into that but it does not appear to do so for multiple `-O` flags for 294 // now. 295 /// Optimization and tuning related options for wasm performance, `-O help` to 296 /// see all. 297 #[arg(short = 'O', long = "optimize", value_name = "KEY[=VAL[,..]]")] 298 opts_raw: Vec<opt::CommaSeparated<Optimize>>, 299 300 /// Codegen-related configuration options, `-C help` to see all. 301 #[arg(short = 'C', long = "codegen", value_name = "KEY[=VAL[,..]]")] 302 codegen_raw: Vec<opt::CommaSeparated<Codegen>>, 303 304 /// Debug-related configuration options, `-D help` to see all. 305 #[arg(short = 'D', long = "debug", value_name = "KEY[=VAL[,..]]")] 306 debug_raw: Vec<opt::CommaSeparated<Debug>>, 307 308 /// Options for configuring semantic execution of WebAssembly, `-W help` to see 309 /// all. 310 #[arg(short = 'W', long = "wasm", value_name = "KEY[=VAL[,..]]")] 311 wasm_raw: Vec<opt::CommaSeparated<Wasm>>, 312 313 /// Options for configuring WASI and its proposals, `-S help` to see all. 314 #[arg(short = 'S', long = "wasi", value_name = "KEY[=VAL[,..]]")] 315 wasi_raw: Vec<opt::CommaSeparated<Wasi>>, 316 317 // These fields are filled in by the `configure` method below via the 318 // options parsed from the CLI above. This is what the CLI should use. 319 #[arg(skip)] 320 configured: bool, 321 #[arg(skip)] 322 pub opts: OptimizeOptions, 323 #[arg(skip)] 324 pub codegen: CodegenOptions, 325 #[arg(skip)] 326 pub debug: DebugOptions, 327 #[arg(skip)] 328 pub wasm: WasmOptions, 329 #[arg(skip)] 330 pub wasi: WasiOptions, 331 } 332 333 macro_rules! match_feature { 334 ( 335 [$feat:tt : $config:expr] 336 $val:ident => $e:expr, 337 $p:pat => err, 338 ) => { 339 #[cfg(feature = $feat)] 340 { 341 if let Some($val) = $config { 342 $e; 343 } 344 } 345 #[cfg(not(feature = $feat))] 346 { 347 if let Some($p) = $config { 348 anyhow::bail!(concat!("support for ", $feat, " disabled at compile time")); 349 } 350 } 351 }; 352 } 353 354 impl CommonOptions { 355 fn configure(&mut self) { 356 if self.configured { 357 return; 358 } 359 self.configured = true; 360 self.opts.configure_with(&self.opts_raw); 361 self.codegen.configure_with(&self.codegen_raw); 362 self.debug.configure_with(&self.debug_raw); 363 self.wasm.configure_with(&self.wasm_raw); 364 self.wasi.configure_with(&self.wasi_raw); 365 } 366 367 pub fn init_logging(&mut self) -> Result<()> { 368 self.configure(); 369 if self.debug.logging == Some(false) { 370 return Ok(()); 371 } 372 #[cfg(feature = "logging")] 373 if self.debug.log_to_files == Some(true) { 374 let prefix = "wasmtime.dbg."; 375 init_file_per_thread_logger(prefix); 376 } else { 377 use std::io::IsTerminal; 378 use tracing_subscriber::{EnvFilter, FmtSubscriber}; 379 let b = FmtSubscriber::builder() 380 .with_writer(std::io::stderr) 381 .with_env_filter(EnvFilter::from_env("WASMTIME_LOG")) 382 .with_ansi(std::io::stderr().is_terminal()); 383 b.init(); 384 } 385 #[cfg(not(feature = "logging"))] 386 if self.debug.log_to_files == Some(true) || self.debug.logging == Some(true) { 387 anyhow::bail!("support for logging disabled at compile time"); 388 } 389 Ok(()) 390 } 391 392 pub fn config(&mut self, target: Option<&str>) -> Result<Config> { 393 self.configure(); 394 let mut config = Config::new(); 395 396 match_feature! { 397 ["cranelift" : self.codegen.compiler] 398 strategy => config.strategy(strategy), 399 _ => err, 400 } 401 match_feature! { 402 ["cranelift" : target] 403 target => config.target(target)?, 404 _ => err, 405 } 406 match_feature! { 407 ["cranelift" : self.codegen.cranelift_debug_verifier] 408 enable => config.cranelift_debug_verifier(enable), 409 true => err, 410 } 411 if let Some(enable) = self.debug.debug_info { 412 config.debug_info(enable); 413 } 414 if self.debug.coredump.is_some() { 415 #[cfg(feature = "coredump")] 416 config.coredump_on_trap(true); 417 #[cfg(not(feature = "coredump"))] 418 anyhow::bail!("support for coredumps disabled at compile time"); 419 } 420 match_feature! { 421 ["cranelift" : self.opts.opt_level] 422 level => config.cranelift_opt_level(level), 423 _ => err, 424 } 425 match_feature! { 426 ["cranelift" : self.wasm.nan_canonicalization] 427 enable => config.cranelift_nan_canonicalization(enable), 428 true => err, 429 } 430 match_feature! { 431 ["cranelift" : self.codegen.pcc] 432 enable => config.cranelift_pcc(enable), 433 true => err, 434 } 435 436 self.enable_wasm_features(&mut config)?; 437 438 #[cfg(feature = "cranelift")] 439 for (name, value) in self.codegen.cranelift.iter() { 440 let name = name.replace('-', "_"); 441 unsafe { 442 match value { 443 Some(val) => { 444 config.cranelift_flag_set(&name, val); 445 } 446 None => { 447 config.cranelift_flag_enable(&name); 448 } 449 } 450 } 451 } 452 #[cfg(not(feature = "cranelift"))] 453 if !self.codegen.cranelift.is_empty() { 454 anyhow::bail!("support for cranelift disabled at compile time"); 455 } 456 457 #[cfg(feature = "cache")] 458 if self.codegen.cache != Some(false) { 459 match &self.codegen.cache_config { 460 Some(path) => { 461 config.cache_config_load(path)?; 462 } 463 None => { 464 config.cache_config_load_default()?; 465 } 466 } 467 } 468 #[cfg(not(feature = "cache"))] 469 if self.codegen.cache == Some(true) { 470 anyhow::bail!("support for caching disabled at compile time"); 471 } 472 473 match_feature! { 474 ["parallel-compilation" : self.codegen.parallel_compilation] 475 enable => config.parallel_compilation(enable), 476 true => err, 477 } 478 479 if let Some(max) = self.opts.static_memory_maximum_size { 480 config.static_memory_maximum_size(max); 481 } 482 483 if let Some(enable) = self.opts.static_memory_forced { 484 config.static_memory_forced(enable); 485 } 486 487 if let Some(size) = self.opts.static_memory_guard_size { 488 config.static_memory_guard_size(size); 489 } 490 491 if let Some(size) = self.opts.dynamic_memory_guard_size { 492 config.dynamic_memory_guard_size(size); 493 } 494 if let Some(size) = self.opts.dynamic_memory_reserved_for_growth { 495 config.dynamic_memory_reserved_for_growth(size); 496 } 497 498 // If fuel has been configured, set the `consume fuel` flag on the config. 499 if self.wasm.fuel.is_some() { 500 config.consume_fuel(true); 501 } 502 503 if let Some(enable) = self.wasm.epoch_interruption { 504 config.epoch_interruption(enable); 505 } 506 if let Some(enable) = self.debug.address_map { 507 config.generate_address_map(enable); 508 } 509 if let Some(enable) = self.opts.memory_init_cow { 510 config.memory_init_cow(enable); 511 } 512 513 match_feature! { 514 ["pooling-allocator" : self.opts.pooling_allocator] 515 enable => { 516 if enable { 517 let mut cfg = wasmtime::PoolingAllocationConfig::default(); 518 if let Some(size) = self.opts.pooling_memory_keep_resident { 519 cfg.linear_memory_keep_resident(size); 520 } 521 if let Some(size) = self.opts.pooling_table_keep_resident { 522 cfg.table_keep_resident(size); 523 } 524 if let Some(enable) = self.opts.memory_protection_keys { 525 if enable { 526 cfg.memory_protection_keys(wasmtime::MpkEnabled::Enable); 527 } 528 } 529 config.allocation_strategy(wasmtime::InstanceAllocationStrategy::Pooling(cfg)); 530 } 531 }, 532 true => err, 533 } 534 535 if self.opts.memory_protection_keys.unwrap_or(false) 536 && !self.opts.pooling_allocator.unwrap_or(false) 537 { 538 anyhow::bail!("memory protection keys require the pooling allocator"); 539 } 540 541 if let Some(max) = self.wasm.max_wasm_stack { 542 config.max_wasm_stack(max); 543 } 544 545 if let Some(enable) = self.wasm.relaxed_simd_deterministic { 546 config.relaxed_simd_deterministic(enable); 547 } 548 match_feature! { 549 ["cranelift" : self.wasm.wmemcheck] 550 enable => config.wmemcheck(enable), 551 true => err, 552 } 553 554 Ok(config) 555 } 556 557 pub fn enable_wasm_features(&self, config: &mut Config) -> Result<()> { 558 let all = self.wasm.all_proposals; 559 560 if let Some(enable) = self.wasm.simd.or(all) { 561 config.wasm_simd(enable); 562 } 563 if let Some(enable) = self.wasm.relaxed_simd.or(all) { 564 config.wasm_relaxed_simd(enable); 565 } 566 if let Some(enable) = self.wasm.bulk_memory.or(all) { 567 config.wasm_bulk_memory(enable); 568 } 569 if let Some(enable) = self.wasm.reference_types.or(all) { 570 config.wasm_reference_types(enable); 571 } 572 if let Some(enable) = self.wasm.function_references.or(all) { 573 config.wasm_function_references(enable); 574 } 575 if let Some(enable) = self.wasm.multi_value.or(all) { 576 config.wasm_multi_value(enable); 577 } 578 if let Some(enable) = self.wasm.tail_call.or(all) { 579 config.wasm_tail_call(enable); 580 } 581 if let Some(enable) = self.wasm.threads.or(all) { 582 config.wasm_threads(enable); 583 } 584 if let Some(enable) = self.wasm.multi_memory.or(all) { 585 config.wasm_multi_memory(enable); 586 } 587 if let Some(enable) = self.wasm.memory64.or(all) { 588 config.wasm_memory64(enable); 589 } 590 if let Some(enable) = self.wasm.component_model.or(all) { 591 #[cfg(feature = "component-model")] 592 config.wasm_component_model(enable); 593 #[cfg(not(feature = "component-model"))] 594 if enable && all.is_none() { 595 anyhow::bail!("support for the component model was disabled at compile-time"); 596 } 597 } 598 Ok(()) 599 } 600 } 601 602 impl PartialEq for CommonOptions { 603 fn eq(&self, other: &CommonOptions) -> bool { 604 let mut me = self.clone(); 605 me.configure(); 606 let mut other = other.clone(); 607 other.configure(); 608 let CommonOptions { 609 opts_raw: _, 610 codegen_raw: _, 611 debug_raw: _, 612 wasm_raw: _, 613 wasi_raw: _, 614 configured: _, 615 616 opts, 617 codegen, 618 debug, 619 wasm, 620 wasi, 621 } = me; 622 opts == other.opts 623 && codegen == other.codegen 624 && debug == other.debug 625 && wasm == other.wasm 626 && wasi == other.wasi 627 } 628 } 629