1 use crate::cdsl::settings::{SettingGroup, SettingGroupBuilder}; 2 3 pub(crate) fn define() -> SettingGroup { 4 let mut settings = SettingGroupBuilder::new("shared"); 5 6 settings.add_bool( 7 "regalloc_checker", 8 "Enable the symbolic checker for register allocation.", 9 r#" 10 This performs a verification that the register allocator preserves 11 equivalent dataflow with respect to the original (pre-regalloc) 12 program. This analysis is somewhat expensive. However, if it succeeds, 13 it provides independent evidence (by a carefully-reviewed, from-first-principles 14 analysis) that no regalloc bugs were triggered for the particular compilations 15 performed. This is a valuable assurance to have as regalloc bugs can be 16 very dangerous and difficult to debug. 17 "#, 18 false, 19 ); 20 21 settings.add_bool( 22 "regalloc_verbose_logs", 23 "Enable verbose debug logs for regalloc2.", 24 r#" 25 This adds extra logging for regalloc2 output, that is quite valuable to understand 26 decisions taken by the register allocator as well as debugging it. It is disabled by 27 default, as it can cause many log calls which can slow down compilation by a large 28 amount. 29 "#, 30 false, 31 ); 32 33 settings.add_enum( 34 "regalloc_algorithm", 35 "Algorithm to use in register allocator.", 36 r#" 37 Supported options: 38 39 - `backtracking`: A backtracking allocator with range splitting; more expensive 40 but generates better code. 41 42 Note that the `single_pass` option is currently disabled because it does not 43 have adequate support for the kinds of allocations required by exception 44 handling (https://github.com/bytecodealliance/regalloc2/issues/217). 45 "#, 46 vec!["backtracking"], 47 ); 48 49 settings.add_enum( 50 "opt_level", 51 "Optimization level for generated code.", 52 r#" 53 Supported levels: 54 55 - `none`: Minimise compile time by disabling most optimizations. 56 - `speed`: Generate the fastest possible code 57 - `speed_and_size`: like "speed", but also perform transformations aimed at reducing code size. 58 "#, 59 vec!["none", "speed", "speed_and_size"], 60 ); 61 62 settings.add_bool( 63 "enable_alias_analysis", 64 "Do redundant-load optimizations with alias analysis.", 65 r#" 66 This enables the use of a simple alias analysis to optimize away redundant loads. 67 Only effective when `opt_level` is `speed` or `speed_and_size`. 68 "#, 69 true, 70 ); 71 72 settings.add_bool( 73 "enable_verifier", 74 "Run the Cranelift IR verifier at strategic times during compilation.", 75 r#" 76 This makes compilation slower but catches many bugs. The verifier is always enabled by 77 default, which is useful during development. 78 "#, 79 true, 80 ); 81 82 settings.add_bool( 83 "enable_pcc", 84 "Enable proof-carrying code translation validation.", 85 r#" 86 This adds a proof-carrying-code mode. Proof-carrying code (PCC) is a strategy to verify 87 that the compiler preserves certain properties or invariants in the compiled code. 88 For example, a frontend that translates WebAssembly to CLIF can embed PCC facts in 89 the CLIF, and Cranelift will verify that the final machine code satisfies the stated 90 facts at each intermediate computed value. Loads and stores can be marked as "checked" 91 and their memory effects can be verified as safe. 92 "#, 93 false, 94 ); 95 96 // Note that Cranelift doesn't currently need an is_pie flag, because PIE is 97 // just PIC where symbols can't be pre-empted, which can be expressed with the 98 // `colocated` flag on external functions and global values. 99 settings.add_bool( 100 "is_pic", 101 "Enable Position-Independent Code generation.", 102 "", 103 false, 104 ); 105 106 settings.add_bool( 107 "use_colocated_libcalls", 108 "Use colocated libcalls.", 109 r#" 110 Generate code that assumes that libcalls can be declared "colocated", 111 meaning they will be defined along with the current function, such that 112 they can use more efficient addressing. 113 "#, 114 false, 115 ); 116 117 settings.add_bool( 118 "enable_float", 119 "Enable the use of floating-point instructions.", 120 r#" 121 Disabling use of floating-point instructions is not yet implemented. 122 "#, 123 true, 124 ); 125 126 settings.add_bool( 127 "enable_nan_canonicalization", 128 "Enable NaN canonicalization.", 129 r#" 130 This replaces NaNs with a single canonical value, for users requiring 131 entirely deterministic WebAssembly computation. This is not required 132 by the WebAssembly spec, so it is not enabled by default. 133 "#, 134 false, 135 ); 136 137 settings.add_bool( 138 "enable_pinned_reg", 139 "Enable the use of the pinned register.", 140 r#" 141 This register is excluded from register allocation, and is completely under the control of 142 the end-user. It is possible to read it via the get_pinned_reg instruction, and to set it 143 with the set_pinned_reg instruction. 144 "#, 145 false, 146 ); 147 148 settings.add_bool( 149 "enable_atomics", 150 "Enable the use of atomic instructions", 151 "", 152 true, 153 ); 154 155 settings.add_bool( 156 "enable_safepoints", 157 "Enable safepoint instruction insertions.", 158 r#" 159 This will allow the emit_stack_maps() function to insert the safepoint 160 instruction on top of calls and interrupt traps in order to display the 161 live reference values at that point in the program. 162 "#, 163 false, 164 ); 165 166 settings.add_enum( 167 "tls_model", 168 "Defines the model used to perform TLS accesses.", 169 "", 170 vec!["none", "elf_gd", "macho", "coff"], 171 ); 172 173 settings.add_enum( 174 "stack_switch_model", 175 "Defines the model used to performing stack switching.", 176 r#" 177 This determines the compilation of `stack_switch` instructions. If 178 set to `basic`, we simply save all registers, update stack pointer 179 and frame pointer (if needed), and jump to the target IP. 180 If set to `update_windows_tib`, we *additionally* update information 181 about the active stack in Windows' Thread Information Block. 182 "#, 183 vec!["none", "basic", "update_windows_tib"], 184 ); 185 186 settings.add_enum( 187 "libcall_call_conv", 188 "Defines the calling convention to use for LibCalls call expansion.", 189 r#" 190 This may be different from the ISA default calling convention. 191 192 The default value is to use the same calling convention as the ISA 193 default calling convention. 194 195 This list should be kept in sync with the list of calling 196 conventions available in isa/call_conv.rs. 197 "#, 198 vec![ 199 "isa_default", 200 "fast", 201 "cold", 202 "system_v", 203 "windows_fastcall", 204 "apple_aarch64", 205 "probestack", 206 ], 207 ); 208 209 settings.add_bool( 210 "enable_llvm_abi_extensions", 211 "Enable various ABI extensions defined by LLVM's behavior.", 212 r#" 213 In some cases, LLVM's implementation of an ABI (calling convention) 214 goes beyond a standard and supports additional argument types or 215 behavior. This option instructs Cranelift codegen to follow LLVM's 216 behavior where applicable. 217 218 Currently, this applies only to Windows Fastcall on x86-64, and 219 allows an `i128` argument to be spread across two 64-bit integer 220 registers. The Fastcall implementation otherwise does not support 221 `i128` arguments, and will panic if they are present and this 222 option is not set. 223 "#, 224 false, 225 ); 226 227 settings.add_bool( 228 "enable_multi_ret_implicit_sret", 229 "Enable support for sret arg introduction when there are too many ret vals.", 230 r#" 231 When there are more returns than available return registers, the 232 return value has to be returned through the introduction of a 233 return area pointer. Normally this return area pointer has to be 234 introduced as `ArgumentPurpose::StructReturn` parameter, but for 235 backward compatibility reasons Cranelift also supports implicitly 236 introducing this parameter and writing the return values through it. 237 238 **This option currently does not conform to platform ABIs and the 239 used ABI should not be assumed to remain the same between Cranelift 240 versions.** 241 242 This option is **deprecated** and will be removed in the future. 243 244 Because of the above issues, and complexities of native ABI support 245 for the concept in general, Cranelift's support for multiple return 246 values may also be removed in the future (#9510). For the most 247 robust solution, it is recommended to build a convention on top of 248 Cranelift's primitives for passing multiple return values, for 249 example by allocating a stackslot in the caller, passing it as an 250 explicit StructReturn argument, storing return values in the callee, 251 and loading results in the caller. 252 "#, 253 false, 254 ); 255 256 settings.add_bool( 257 "unwind_info", 258 "Generate unwind information.", 259 r#" 260 This increases metadata size and compile time, but allows for the 261 debugger to trace frames, is needed for GC tracing that relies on 262 libunwind (such as in Wasmtime), and is unconditionally needed on 263 certain platforms (such as Windows) that must always be able to unwind. 264 "#, 265 true, 266 ); 267 268 settings.add_bool( 269 "preserve_frame_pointers", 270 "Preserve frame pointers", 271 r#" 272 Preserving frame pointers -- even inside leaf functions -- makes it 273 easy to capture the stack of a running program, without requiring any 274 side tables or metadata (like `.eh_frame` sections). Many sampling 275 profilers and similar tools walk frame pointers to capture stacks. 276 Enabling this option will play nice with those tools. 277 "#, 278 false, 279 ); 280 281 settings.add_bool( 282 "machine_code_cfg_info", 283 "Generate CFG metadata for machine code.", 284 r#" 285 This increases metadata size and compile time, but allows for the 286 embedder to more easily post-process or analyze the generated 287 machine code. It provides code offsets for the start of each 288 basic block in the generated machine code, and a list of CFG 289 edges (with blocks identified by start offsets) between them. 290 This is useful for, e.g., machine-code analyses that verify certain 291 properties of the generated code. 292 "#, 293 false, 294 ); 295 296 // Stack probing options. 297 298 settings.add_bool( 299 "enable_probestack", 300 "Enable the use of stack probes for supported calling conventions.", 301 "", 302 false, 303 ); 304 305 settings.add_num( 306 "probestack_size_log2", 307 "The log2 of the size of the stack guard region.", 308 r#" 309 Stack frames larger than this size will have stack overflow checked 310 by calling the probestack function. 311 312 The default is 12, which translates to a size of 4096. 313 "#, 314 12, 315 ); 316 317 settings.add_enum( 318 "probestack_strategy", 319 "Controls what kinds of stack probes are emitted.", 320 r#" 321 Supported strategies: 322 323 - `outline`: Always emits stack probes as calls to a probe stack function. 324 - `inline`: Always emits inline stack probes. 325 "#, 326 vec!["outline", "inline"], 327 ); 328 329 // Jump table options. 330 331 settings.add_bool( 332 "enable_jump_tables", 333 "Enable the use of jump tables in generated machine code.", 334 "", 335 true, 336 ); 337 338 // Spectre options. 339 340 settings.add_bool( 341 "enable_heap_access_spectre_mitigation", 342 "Enable Spectre mitigation on heap bounds checks.", 343 r#" 344 This is a no-op for any heap that needs no bounds checks; e.g., 345 if the limit is static and the guard region is large enough that 346 the index cannot reach past it. 347 348 This option is enabled by default because it is highly 349 recommended for secure sandboxing. The embedder should consider 350 the security implications carefully before disabling this option. 351 "#, 352 true, 353 ); 354 355 settings.add_bool( 356 "enable_table_access_spectre_mitigation", 357 "Enable Spectre mitigation on table bounds checks.", 358 r#" 359 This option uses a conditional move to ensure that when a table 360 access index is bounds-checked and a conditional branch is used 361 for the out-of-bounds case, a misspeculation of that conditional 362 branch (falsely predicted in-bounds) will select an in-bounds 363 index to load on the speculative path. 364 365 This option is enabled by default because it is highly 366 recommended for secure sandboxing. The embedder should consider 367 the security implications carefully before disabling this option. 368 "#, 369 true, 370 ); 371 372 settings.add_bool( 373 "enable_incremental_compilation_cache_checks", 374 "Enable additional checks for debugging the incremental compilation cache.", 375 r#" 376 Enables additional checks that are useful during development of the incremental 377 compilation cache. This should be mostly useful for Cranelift hackers, as well as for 378 helping to debug false incremental cache positives for embedders. 379 380 This option is disabled by default and requires enabling the "incremental-cache" Cargo 381 feature in cranelift-codegen. 382 "#, 383 false, 384 ); 385 386 settings.add_num( 387 "bb_padding_log2_minus_one", 388 "The log2 of the size to insert dummy padding between basic blocks", 389 r#" 390 This is a debugging option for stressing various cases during code 391 generation without requiring large functions. This will insert 392 0-byte padding between basic blocks of the specified size. 393 394 The amount of padding inserted two raised to the power of this value 395 minus one. If this value is 0 then no padding is inserted. 396 397 The default for this option is 0 to insert no padding as it's only 398 intended for testing and development. 399 "#, 400 0, 401 ); 402 403 settings.add_num( 404 "log2_min_function_alignment", 405 "The log2 of the minimum alignment of functions", 406 "The bigger of this value and the default alignment will be used as actual alignment.", 407 0, 408 ); 409 410 // When adding new settings please check if they can also be added 411 // in cranelift/fuzzgen/src/lib.rs for fuzzing. 412 settings.build() 413 } 414