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