cranelift_codegen_meta/shared/
settings.rs

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