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