charon_lib/transform/
mod.rs

1pub mod check_generics;
2pub mod compute_short_names;
3pub mod ctx;
4pub mod duplicate_defaulted_methods;
5pub mod duplicate_return;
6pub mod expand_associated_types;
7pub mod filter_invisible_trait_impls;
8pub mod filter_unreachable_blocks;
9pub mod graphs;
10pub mod hide_marker_traits;
11pub mod index_intermediate_assigns;
12pub mod index_to_function_calls;
13pub mod inline_local_panic_functions;
14pub mod inline_promoted_consts;
15pub mod insert_assign_return_unit;
16pub mod insert_storage_lives;
17pub mod lift_associated_item_clauses;
18pub mod merge_goto_chains;
19pub mod monomorphize;
20pub mod ops_to_function_calls;
21pub mod prettify_cfg;
22pub mod reconstruct_asserts;
23pub mod reconstruct_boxes;
24pub mod recover_body_comments;
25pub mod remove_drop_never;
26pub mod remove_dynamic_checks;
27pub mod remove_nops;
28pub mod remove_read_discriminant;
29pub mod remove_unit_locals;
30pub mod remove_unused_locals;
31pub mod remove_unused_methods;
32pub mod remove_unused_self_clause;
33pub mod reorder_decls;
34pub mod simplify_constants;
35pub mod skip_trait_refs_when_known;
36pub mod ullbc_to_llbc;
37pub mod unbind_item_vars;
38pub mod update_block_indices;
39
40pub use ctx::TransformCtx;
41use ctx::{LlbcPass, TransformPass, UllbcPass};
42use Pass::*;
43
44/// Item and type cleanup passes.
45pub static INITIAL_CLEANUP_PASSES: &[Pass] = &[
46    // Compute short names
47    NonBody(&compute_short_names::Transform),
48    // Remove the trait/impl methods that were not translated (because not used).
49    NonBody(&remove_unused_methods::Transform),
50    // Move clauses on associated types to be parent clauses
51    NonBody(&lift_associated_item_clauses::Transform),
52    // Check that all supplied generic types match the corresponding generic parameters.
53    // Needs `lift_associated_item_clauses`.
54    NonBody(&check_generics::Check("after translation")),
55    // # Micro-pass: hide some overly-common traits we don't need: Sized, Sync, Allocator, etc..
56    NonBody(&hide_marker_traits::Transform),
57    // # Micro-pass: filter the trait impls that were marked invisible since we couldn't filter
58    // them out earlier.
59    NonBody(&filter_invisible_trait_impls::Transform),
60    // # Micro-pass: remove the explicit `Self: Trait` clause of methods/assoc const declaration
61    // items if they're not used. This simplifies the graph of dependencies between definitions.
62    NonBody(&remove_unused_self_clause::Transform),
63    // Add missing methods to trait impls by duplicating the default method.
64    NonBody(&duplicate_defaulted_methods::Transform),
65    // # Micro-pass: whenever we call a trait method on a known type, refer to the method `FunDecl`
66    // directly instead of going via a `TraitRef`. This is done before `reorder_decls` to remove
67    // some sources of mutual recursion.
68    UnstructuredBody(&skip_trait_refs_when_known::Transform),
69    // Change trait associated types to be type parameters instead. See the module for details.
70    NonBody(&expand_associated_types::Transform),
71];
72
73/// Body cleanup passes on the ullbc.
74pub static ULLBC_PASSES: &[Pass] = &[
75    // Inline promoted consts into their parent bodies.
76    UnstructuredBody(&inline_promoted_consts::Transform),
77    // # Micro-pass: merge single-origin gotos into their parent. This drastically reduces the
78    // graph size of the CFG.
79    UnstructuredBody(&merge_goto_chains::Transform),
80    // # Micro-pass: Remove overflow/div-by-zero/bounds checks since they are already part of the
81    // arithmetic/array operation in the semantics of (U)LLBC.
82    // **WARNING**: this pass uses the fact that the dynamic checks introduced by Rustc use a
83    // special "assert" construct. Because of this, it must happen *before* the
84    // [reconstruct_asserts] pass. See the comments in [crate::remove_dynamic_checks].
85    // **WARNING**: this pass relies on a precise structure of the MIR statements. Because of this,
86    // it must happen before passes that insert statements like [simplify_constants].
87    UnstructuredBody(&remove_dynamic_checks::Transform),
88    // # Micro-pass: reconstruct the special `Box::new` operations inserted e.g. in the `vec![]`
89    // macro.
90    // **WARNING**: this pass relies on a precise structure of the MIR statements. Because of this,
91    // it must happen before passes that insert statements like [simplify_constants].
92    // **WARNING**: this pass works across calls, hence must happen after `merge_goto_chains`,
93    UnstructuredBody(&reconstruct_boxes::Transform),
94    // # Micro-pass: desugar the constants to other values/operands as much
95    // as possible.
96    UnstructuredBody(&simplify_constants::Transform),
97    // # Micro-pass: make sure the block ids used in the ULLBC are consecutive
98    UnstructuredBody(&update_block_indices::Transform),
99    // # Micro-pass: reconstruct the asserts
100    UnstructuredBody(&reconstruct_asserts::Transform),
101    // # Micro-pass: duplicate the return blocks
102    UnstructuredBody(&duplicate_return::Transform),
103    // # Micro-pass: filter the "dangling" blocks. Those might have been introduced by,
104    // for instance, [`reconstruct_asserts`].
105    UnstructuredBody(&filter_unreachable_blocks::Transform),
106    // # Micro-pass: `panic!()` expands to a new function definition each time. This pass cleans
107    // those up.
108    UnstructuredBody(&inline_local_panic_functions::Transform),
109    // # Micro-pass: introduce intermediate assignments in preparation of the
110    // [`index_to_function_calls`] pass.
111    UnstructuredBody(&index_intermediate_assigns::Transform),
112    // # Micro-pass: add the missing assignments to the return value.
113    // When the function return type is unit, the generated MIR doesn't
114    // set the return value to `()`. This can be a concern: in the case
115    // of Aeneas, it means the return variable contains ⊥ upon returning.
116    // For this reason, when the function has return type unit, we insert
117    // an extra assignment just before returning.
118    UnstructuredBody(&insert_assign_return_unit::Transform),
119    // # Micro-pass: remove locals of type `()` which show up a lot.
120    UnstructuredBody(&remove_unit_locals::Transform),
121    // # Micro-pass: remove the drops of locals whose type is `Never` (`!`). This
122    // is in preparation of the next transformation.
123    UnstructuredBody(&remove_drop_never::Transform),
124];
125
126/// Body cleanup passes after control flow reconstruction.
127pub static LLBC_PASSES: &[Pass] = &[
128    // # Go from ULLBC to LLBC (Low-Level Borrow Calculus) by reconstructing the control flow.
129    NonBody(&ullbc_to_llbc::Transform),
130    // # Micro-pass: replace some unops/binops and the array aggregates with
131    // function calls (introduces: ArrayToSlice, etc.)
132    StructuredBody(&ops_to_function_calls::Transform),
133    // # Micro-pass: replace the arrays/slices index operations with function
134    // calls.
135    // (introduces: ArrayIndexShared, ArrayIndexMut, etc.)
136    StructuredBody(&index_to_function_calls::Transform),
137    // # Micro-pass: Remove the discriminant reads (merge them with the switches)
138    StructuredBody(&remove_read_discriminant::Transform),
139    // Cleanup the cfg.
140    StructuredBody(&prettify_cfg::Transform),
141];
142
143/// Cleanup passes useful for both llbc and ullbc.
144pub static SHARED_FINALIZING_PASSES: &[Pass] = &[
145    // # Micro-pass: remove the locals which are never used.
146    NonBody(&remove_unused_locals::Transform),
147    // Insert storage lives for locals that are always allocated at the beginning of the function.
148    NonBody(&insert_storage_lives::Transform),
149    // # Micro-pass: remove the useless `StatementKind::Nop`s.
150    NonBody(&remove_nops::Transform),
151    // Monomorphize the functions and types.
152    NonBody(&monomorphize::Transform),
153    // # Micro-pass: take all the comments found in the original body and assign them to
154    // statements. This must be last after all the statement-affecting passes to avoid losing
155    // comments.
156    NonBody(&recover_body_comments::Transform),
157    // # Reorder the graph of dependencies and compute the strictly connex components to:
158    // - compute the order in which to extract the definitions
159    // - find the recursive definitions
160    // - group the mutually recursive definitions
161    NonBody(&reorder_decls::Transform),
162];
163
164/// Final passes to run at the end, after pretty-printing the llbc if applicable. These are only
165/// split from the above list to get test outputs even when generics fail to match.
166pub static FINAL_CLEANUP_PASSES: &[Pass] = &[
167    // Check that all supplied generic types match the corresponding generic parameters.
168    NonBody(&check_generics::Check("after transformations")),
169    // Use `DeBruijnVar::Free` for the variables bound in item signatures.
170    NonBody(&unbind_item_vars::Check),
171];
172
173#[derive(Clone, Copy)]
174pub enum Pass {
175    NonBody(&'static dyn TransformPass),
176    UnstructuredBody(&'static dyn UllbcPass),
177    StructuredBody(&'static dyn LlbcPass),
178}
179
180impl Pass {
181    pub fn run(self, ctx: &mut TransformCtx) {
182        match self {
183            NonBody(pass) => pass.transform_ctx(ctx),
184            UnstructuredBody(pass) => pass.transform_ctx(ctx),
185            StructuredBody(pass) => pass.transform_ctx(ctx),
186        }
187    }
188
189    pub fn name(&self) -> &str {
190        match self {
191            NonBody(pass) => pass.name(),
192            UnstructuredBody(pass) => pass.name(),
193            StructuredBody(pass) => pass.name(),
194        }
195    }
196}
197
198pub struct PrintCtxPass {
199    pub message: String,
200    /// Whether we're printing to stdout or only logging.
201    pub to_stdout: bool,
202}
203
204impl PrintCtxPass {
205    pub fn new(to_stdout: bool, message: String) -> &'static Self {
206        let ret = Self { message, to_stdout };
207        Box::leak(Box::new(ret))
208    }
209}
210
211impl TransformPass for PrintCtxPass {
212    fn transform_ctx(&self, ctx: &mut TransformCtx) {
213        let message = &self.message;
214        if self.to_stdout {
215            println!("{message}:\n\n{ctx}\n");
216        } else {
217            trace!("{message}:\n\n{ctx}\n");
218        }
219    }
220}