rustc_middle/mir/
syntax.rs

1//! This defines the syntax of MIR, i.e., the set of available MIR operations, and other definitions
2//! closely related to MIR semantics.
3//! This is in a dedicated file so that changes to this file can be reviewed more carefully.
4//! The intention is that this file only contains datatype declarations, no code.
5
6use rustc_abi::{FieldIdx, VariantIdx};
7use rustc_ast::{InlineAsmOptions, InlineAsmTemplatePiece, Mutability};
8use rustc_data_structures::packed::Pu128;
9use rustc_hir::CoroutineKind;
10use rustc_hir::def_id::DefId;
11use rustc_index::IndexVec;
12use rustc_macros::{HashStable, TyDecodable, TyEncodable, TypeFoldable, TypeVisitable};
13use rustc_span::def_id::LocalDefId;
14use rustc_span::source_map::Spanned;
15use rustc_span::{Span, Symbol};
16use rustc_target::asm::InlineAsmRegOrRegClass;
17use smallvec::SmallVec;
18
19use super::{BasicBlock, Const, Local, UserTypeProjection};
20use crate::mir::coverage::CoverageKind;
21use crate::ty::adjustment::PointerCoercion;
22use crate::ty::{self, GenericArgsRef, List, Region, Ty, UserTypeAnnotationIndex};
23
24/// Represents the "flavors" of MIR.
25///
26/// The MIR pipeline is structured into a few major dialects, with one or more phases within each
27/// dialect. A MIR flavor is identified by a dialect-phase pair. A single `MirPhase` value
28/// specifies such a pair. All flavors of MIR use the same data structure to represent the program.
29///
30/// Different MIR dialects have different semantics. (The differences between dialects are small,
31/// but they do exist.) The progression from one MIR dialect to the next is technically a lowering
32/// from one IR to another. In other words, a single well-formed [`Body`](crate::mir::Body) might
33/// have different semantic meaning and different behavior at runtime in the different dialects.
34/// The specific differences between dialects are described on the variants below.
35///
36/// Phases exist only to place restrictions on what language constructs are permitted in
37/// well-formed MIR, and subsequent phases mostly increase those restrictions. I.e. to convert MIR
38/// from one phase to the next might require removing/replacing certain MIR constructs.
39///
40/// When adding dialects or phases, remember to update [`MirPhase::index`].
41#[derive(Copy, Clone, TyEncodable, TyDecodable, Debug, PartialEq, Eq, PartialOrd, Ord)]
42#[derive(HashStable)]
43pub enum MirPhase {
44    /// The "built MIR" dialect, as generated by MIR building.
45    ///
46    /// The only things that operate on this dialect are unsafeck, the various MIR lints, and const
47    /// qualifs.
48    ///
49    /// This dialect has just the one (implicit) phase, which places few restrictions on what MIR
50    /// constructs are allowed.
51    Built,
52
53    /// The "analysis MIR" dialect, used for borrowck and friends.
54    ///
55    /// The only semantic difference between built MIR and analysis MIR relates to constant
56    /// promotion. In built MIR, sequences of statements that would generally be subject to
57    /// constant promotion are semantically constants, while in analysis MIR all constants are
58    /// explicit.
59    ///
60    /// The result of const promotion is available from the `mir_promoted` and `promoted_mir`
61    /// queries.
62    ///
63    /// The phases of this dialect are described in `AnalysisPhase`.
64    Analysis(AnalysisPhase),
65
66    /// The "runtime MIR" dialect, used for CTFE, optimizations, and codegen.
67    ///
68    /// The semantic differences between analysis MIR and runtime MIR are as follows.
69    ///
70    /// - Drops: In analysis MIR, `Drop` terminators represent *conditional* drops; roughly
71    ///   speaking, if dataflow analysis determines that the place being dropped is uninitialized,
72    ///   the drop will not be executed. The exact semantics of this aren't written down anywhere,
73    ///   which means they are essentially "what drop elaboration does." In runtime MIR, the drops
74    ///   are unconditional; when a `Drop` terminator is reached, if the type has drop glue that
75    ///   drop glue is always executed. This may be UB if the underlying place is not initialized.
76    /// - Packed drops: Places might in general be misaligned - in most cases this is UB, the
77    ///   exception is fields of packed structs. In analysis MIR, `Drop(P)` for a `P` that might be
78    ///   misaligned for this reason implicitly moves `P` to a temporary before dropping. Runtime
79    ///   MIR has no such rules, and dropping a misaligned place is simply UB.
80    /// - Async drops: after drop elaboration some drops may become async (`drop`, `async_fut` fields).
81    ///   StateTransform pass will expand those async drops or reset to sync.
82    /// - Unwinding: in analysis MIR, unwinding from a function which may not unwind aborts. In
83    ///   runtime MIR, this is UB.
84    /// - Retags: If `-Zmir-emit-retag` is enabled, analysis MIR has "implicit" retags in the same
85    ///   way that Rust itself has them. Where exactly these are is generally subject to change,
86    ///   and so we don't document this here. Runtime MIR has most retags explicit (though implicit
87    ///   retags can still occur at `Rvalue::{Ref,AddrOf}`).
88    /// - Coroutine bodies: In analysis MIR, locals may actually be behind a pointer that user code
89    ///   has access to. This occurs in coroutine bodies. Such locals do not behave like other
90    ///   locals, because they e.g. may be aliased in surprising ways. Runtime MIR has no such
91    ///   special locals. All coroutine bodies are lowered and so all places that look like locals
92    ///   really are locals.
93    ///
94    /// Also note that the lint pass which reports eg `200_u8 + 200_u8` as an error is run as a part
95    /// of analysis to runtime MIR lowering. To ensure lints are reported reliably, this means that
96    /// transformations that can suppress such errors should not run on analysis MIR.
97    ///
98    /// The phases of this dialect are described in `RuntimePhase`.
99    Runtime(RuntimePhase),
100}
101
102/// See [`MirPhase::Analysis`].
103#[derive(Copy, Clone, TyEncodable, TyDecodable, Debug, PartialEq, Eq, PartialOrd, Ord)]
104#[derive(HashStable)]
105pub enum AnalysisPhase {
106    Initial = 0,
107    /// Beginning in this phase, the following variants are disallowed:
108    /// * [`TerminatorKind::FalseUnwind`]
109    /// * [`TerminatorKind::FalseEdge`]
110    /// * [`StatementKind::FakeRead`]
111    /// * [`StatementKind::AscribeUserType`]
112    /// * [`StatementKind::Coverage`] with [`CoverageKind::BlockMarker`] or
113    ///   [`CoverageKind::SpanMarker`]
114    /// * [`Rvalue::Ref`] with `BorrowKind::Fake`
115    /// * [`CastKind::PointerCoercion`] with any of the following:
116    ///   * [`PointerCoercion::ArrayToPointer`]
117    ///   * [`PointerCoercion::MutToConstPointer`]
118    ///
119    /// Furthermore, `Deref` projections must be the first projection within any place (if they
120    /// appear at all)
121    PostCleanup = 1,
122}
123
124/// See [`MirPhase::Runtime`].
125#[derive(Copy, Clone, TyEncodable, TyDecodable, Debug, PartialEq, Eq, PartialOrd, Ord)]
126#[derive(HashStable)]
127pub enum RuntimePhase {
128    /// In addition to the semantic changes, beginning with this phase, the following variants are
129    /// disallowed:
130    /// * [`TerminatorKind::Yield`]
131    /// * [`TerminatorKind::CoroutineDrop`]
132    /// * [`Rvalue::Aggregate`] for any `AggregateKind` except `Array`
133    /// * [`PlaceElem::OpaqueCast`]
134    ///
135    /// And the following variants are allowed:
136    /// * [`StatementKind::Retag`]
137    /// * [`StatementKind::SetDiscriminant`]
138    /// * [`StatementKind::Deinit`]
139    ///
140    /// Furthermore, `Copy` operands are allowed for non-`Copy` types.
141    Initial = 0,
142    /// Beginning with this phase, the following variant is disallowed:
143    /// * [`ProjectionElem::Deref`] of `Box`
144    PostCleanup = 1,
145    Optimized = 2,
146}
147
148///////////////////////////////////////////////////////////////////////////
149// Borrow kinds
150
151#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, TyEncodable, TyDecodable)]
152#[derive(Hash, HashStable)]
153pub enum BorrowKind {
154    /// Data must be immutable and is aliasable.
155    Shared,
156
157    /// An immutable, aliasable borrow that is discarded after borrow-checking. Can behave either
158    /// like a normal shared borrow or like a special shallow borrow (see [`FakeBorrowKind`]).
159    ///
160    /// This is used when lowering index expressions and matches. This is used to prevent code like
161    /// the following from compiling:
162    /// ```compile_fail,E0510
163    /// let mut x: &[_] = &[[0, 1]];
164    /// let y: &[_] = &[];
165    /// let _ = x[0][{x = y; 1}];
166    /// ```
167    /// ```compile_fail,E0510
168    /// let mut x = &Some(0);
169    /// match *x {
170    ///     None => (),
171    ///     Some(_) if { x = &None; false } => (),
172    ///     Some(_) => (),
173    /// }
174    /// ```
175    /// We can also report errors with this kind of borrow differently.
176    Fake(FakeBorrowKind),
177
178    /// Data is mutable and not aliasable.
179    Mut { kind: MutBorrowKind },
180}
181
182#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, TyEncodable, TyDecodable)]
183#[derive(Hash, HashStable)]
184pub enum RawPtrKind {
185    Mut,
186    Const,
187    /// Creates a raw pointer to a place that will only be used to access its metadata,
188    /// not the data behind the pointer. Note that this limitation is *not* enforced
189    /// by the validator.
190    ///
191    /// The borrow checker allows overlap of these raw pointers with references to the
192    /// data. This is sound even if the pointer is "misused" since any such use is anyway
193    /// unsafe. In terms of the operational semantics (i.e., Miri), this is equivalent
194    /// to `RawPtrKind::Mut`, but will never incur a retag.
195    FakeForPtrMetadata,
196}
197
198#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, TyEncodable, TyDecodable)]
199#[derive(Hash, HashStable)]
200pub enum MutBorrowKind {
201    Default,
202    /// This borrow arose from method-call auto-ref. (i.e., `adjustment::Adjust::Borrow`)
203    TwoPhaseBorrow,
204    /// Data must be immutable but not aliasable. This kind of borrow
205    /// cannot currently be expressed by the user and is used only in
206    /// implicit closure bindings. It is needed when the closure is
207    /// borrowing or mutating a mutable referent, e.g.:
208    /// ```
209    /// let mut z = 3;
210    /// let x: &mut isize = &mut z;
211    /// let y = || *x += 5;
212    /// ```
213    /// If we were to try to translate this closure into a more explicit
214    /// form, we'd encounter an error with the code as written:
215    /// ```compile_fail,E0594
216    /// struct Env<'a> { x: &'a &'a mut isize }
217    /// let mut z = 3;
218    /// let x: &mut isize = &mut z;
219    /// let y = (&mut Env { x: &x }, fn_ptr);  // Closure is pair of env and fn
220    /// fn fn_ptr(env: &mut Env) { **env.x += 5; }
221    /// ```
222    /// This is then illegal because you cannot mutate an `&mut` found
223    /// in an aliasable location. To solve, you'd have to translate with
224    /// an `&mut` borrow:
225    /// ```compile_fail,E0596
226    /// struct Env<'a> { x: &'a mut &'a mut isize }
227    /// let mut z = 3;
228    /// let x: &mut isize = &mut z;
229    /// let y = (&mut Env { x: &mut x }, fn_ptr); // changed from &x to &mut x
230    /// fn fn_ptr(env: &mut Env) { **env.x += 5; }
231    /// ```
232    /// Now the assignment to `**env.x` is legal, but creating a
233    /// mutable pointer to `x` is not because `x` is not mutable. We
234    /// could fix this by declaring `x` as `let mut x`. This is ok in
235    /// user code, if awkward, but extra weird for closures, since the
236    /// borrow is hidden.
237    ///
238    /// So we introduce a `ClosureCapture` borrow -- user will not have to mark the variable
239    /// containing the mutable reference as `mut`, as they didn't ever
240    /// intend to mutate the mutable reference itself. We still mutable capture it in order to
241    /// mutate the pointed value through it (but not mutating the reference itself).
242    ///
243    /// This solves the problem. For simplicity, we don't give users the way to express this
244    /// borrow, it's just used when translating closures.
245    ClosureCapture,
246}
247
248#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, TyEncodable, TyDecodable)]
249#[derive(Hash, HashStable)]
250pub enum FakeBorrowKind {
251    /// A shared shallow borrow. The immediately borrowed place must be immutable, but projections
252    /// from it don't need to be. For example, a shallow borrow of `a.b` doesn't conflict with a
253    /// mutable borrow of `a.b.c`.
254    ///
255    /// This is used when lowering matches: when matching on a place we want to ensure that place
256    /// have the same value from the start of the match until an arm is selected. This prevents this
257    /// code from compiling:
258    /// ```compile_fail,E0510
259    /// let mut x = &Some(0);
260    /// match *x {
261    ///     None => (),
262    ///     Some(_) if { x = &None; false } => (),
263    ///     Some(_) => (),
264    /// }
265    /// ```
266    /// This can't be a shared borrow because mutably borrowing `(*x as Some).0` should not checking
267    /// the discriminant or accessing other variants, because the mutating `(*x as Some).0` can't
268    /// affect the discriminant of `x`. E.g. the following is allowed:
269    /// ```rust
270    /// let mut x = Some(0);
271    /// match x {
272    ///     Some(_)
273    ///         if {
274    ///             if let Some(ref mut y) = x {
275    ///                 *y += 1;
276    ///             };
277    ///             true
278    ///         } => {}
279    ///     _ => {}
280    /// }
281    /// ```
282    Shallow,
283    /// A shared (deep) borrow. Data must be immutable and is aliasable.
284    ///
285    /// This is used when lowering deref patterns, where shallow borrows wouldn't prevent something
286    /// like:
287    // ```compile_fail
288    // let mut b = Box::new(false);
289    // match b {
290    //     deref!(true) => {} // not reached because `*b == false`
291    //     _ if { *b = true; false } => {} // not reached because the guard is `false`
292    //     deref!(false) => {} // not reached because the guard changed it
293    //     // UB because we reached the unreachable.
294    // }
295    // ```
296    Deep,
297}
298
299///////////////////////////////////////////////////////////////////////////
300// Statements
301
302/// The various kinds of statements that can appear in MIR.
303///
304/// Not all of these are allowed at every [`MirPhase`]. Check the documentation there to see which
305/// ones you do not have to worry about. The MIR validator will generally enforce such restrictions,
306/// causing an ICE if they are violated.
307#[derive(Clone, Debug, PartialEq, TyEncodable, TyDecodable, Hash, HashStable)]
308#[derive(TypeFoldable, TypeVisitable)]
309pub enum StatementKind<'tcx> {
310    /// Assign statements roughly correspond to an assignment in Rust proper (`x = ...`) except
311    /// without the possibility of dropping the previous value (that must be done separately, if at
312    /// all). The *exact* way this works is undecided. It probably does something like evaluating
313    /// the LHS to a place and the RHS to a value, and then storing the value to the place. Various
314    /// parts of this may do type specific things that are more complicated than simply copying
315    /// bytes.
316    ///
317    /// **Needs clarification**: The implication of the above idea would be that assignment implies
318    /// that the resulting value is initialized. I believe we could commit to this separately from
319    /// committing to whatever part of the memory model we would need to decide on to make the above
320    /// paragraph precise. Do we want to?
321    ///
322    /// Assignments in which the types of the place and rvalue differ are not well-formed.
323    ///
324    /// **Needs clarification**: Do we ever want to worry about non-free (in the body) lifetimes for
325    /// the typing requirement in post drop-elaboration MIR? I think probably not - I'm not sure we
326    /// could meaningfully require this anyway. How about free lifetimes? Is ignoring this
327    /// interesting for optimizations? Do we want to allow such optimizations?
328    ///
329    /// **Needs clarification**: We currently require that the LHS place not overlap with any place
330    /// read as part of computation of the RHS for some rvalues (generally those not producing
331    /// primitives). This requirement is under discussion in [#68364]. As a part of this discussion,
332    /// it is also unclear in what order the components are evaluated.
333    ///
334    /// [#68364]: https://github.com/rust-lang/rust/issues/68364
335    ///
336    /// See [`Rvalue`] documentation for details on each of those.
337    Assign(Box<(Place<'tcx>, Rvalue<'tcx>)>),
338
339    /// When executed at runtime, this is a nop.
340    ///
341    /// During static analysis, a fake read:
342    /// - requires that the value being read is initialized (or, in the case
343    ///   of closures, that it was fully initialized at some point in the past)
344    /// - constitutes a use of a value for the purposes of NLL (i.e. if the
345    ///   value being fake-read is a reference, the lifetime of that reference
346    ///   will be extended to cover the `FakeRead`)
347    /// - but, unlike an actual read, does *not* invalidate any exclusive
348    ///   borrows.
349    ///
350    /// See [`FakeReadCause`] for more details on the situations in which a
351    /// `FakeRead` is emitted.
352    ///
353    /// Disallowed after drop elaboration.
354    FakeRead(Box<(FakeReadCause, Place<'tcx>)>),
355
356    /// Write the discriminant for a variant to the enum Place.
357    ///
358    /// This is permitted for both coroutines and ADTs. This does not necessarily write to the
359    /// entire place; instead, it writes to the minimum set of bytes as required by the layout for
360    /// the type.
361    SetDiscriminant { place: Box<Place<'tcx>>, variant_index: VariantIdx },
362
363    /// Deinitializes the place.
364    ///
365    /// This writes `uninit` bytes to the entire place.
366    Deinit(Box<Place<'tcx>>),
367
368    /// `StorageLive` and `StorageDead` statements mark the live range of a local.
369    ///
370    /// At any point during the execution of a function, each local is either allocated or
371    /// unallocated. Except as noted below, all locals except function parameters are initially
372    /// unallocated. `StorageLive` statements cause memory to be allocated for the local while
373    /// `StorageDead` statements cause the memory to be freed. In other words,
374    /// `StorageLive`/`StorageDead` act like the heap operations `allocate`/`deallocate`, but for
375    /// stack-allocated local variables. Using a local in any way (not only reading/writing from it)
376    /// while it is unallocated is UB.
377    ///
378    /// Some locals have no `StorageLive` or `StorageDead` statements within the entire MIR body.
379    /// These locals are implicitly allocated for the full duration of the function. There is a
380    /// convenience method at `rustc_mir_dataflow::storage::always_storage_live_locals` for
381    /// computing these locals.
382    ///
383    /// If the local is already allocated, calling `StorageLive` again will implicitly free the
384    /// local and then allocate fresh uninitilized memory. If a local is already deallocated,
385    /// calling `StorageDead` again is a NOP.
386    StorageLive(Local),
387
388    /// See `StorageLive` above.
389    StorageDead(Local),
390
391    /// Retag references in the given place, ensuring they got fresh tags.
392    ///
393    /// This is part of the Stacked Borrows model. These statements are currently only interpreted
394    /// by miri and only generated when `-Z mir-emit-retag` is passed. See
395    /// <https://internals.rust-lang.org/t/stacked-borrows-an-aliasing-model-for-rust/8153/> for
396    /// more details.
397    ///
398    /// For code that is not specific to stacked borrows, you should consider retags to read and
399    /// modify the place in an opaque way.
400    ///
401    /// Only `RetagKind::Default` and `RetagKind::FnEntry` are permitted.
402    Retag(RetagKind, Box<Place<'tcx>>),
403
404    /// This statement exists to preserve a trace of a scrutinee matched against a wildcard binding.
405    /// This is especially useful for `let _ = PLACE;` bindings that desugar to a single
406    /// `PlaceMention(PLACE)`.
407    ///
408    /// When executed at runtime, this computes the given place, but then discards
409    /// it without doing a load. `let _ = *ptr;` is fine even if the pointer is dangling.
410    PlaceMention(Box<Place<'tcx>>),
411
412    /// Encodes a user's type ascription. These need to be preserved
413    /// intact so that NLL can respect them. For example:
414    /// ```ignore (illustrative)
415    /// let a: T = y;
416    /// ```
417    /// The effect of this annotation is to relate the type `T_y` of the place `y`
418    /// to the user-given type `T`. The effect depends on the specified variance:
419    ///
420    /// - `Covariant` -- requires that `T_y <: T`
421    /// - `Contravariant` -- requires that `T_y :> T`
422    /// - `Invariant` -- requires that `T_y == T`
423    /// - `Bivariant` -- no effect
424    ///
425    /// When executed at runtime this is a nop.
426    ///
427    /// Disallowed after drop elaboration.
428    AscribeUserType(Box<(Place<'tcx>, UserTypeProjection)>, ty::Variance),
429
430    /// Carries control-flow-sensitive information injected by `-Cinstrument-coverage`,
431    /// such as where to generate physical coverage-counter-increments during codegen.
432    ///
433    /// Coverage statements are used in conjunction with the coverage mappings and other
434    /// information stored in the function's
435    /// [`mir::Body::function_coverage_info`](crate::mir::Body::function_coverage_info).
436    /// (For inlined MIR, take care to look up the *original function's* coverage info.)
437    ///
438    /// Interpreters and codegen backends that don't support coverage instrumentation
439    /// can usually treat this as a no-op.
440    Coverage(
441        // Coverage statements are unlikely to ever contain type information in
442        // the foreseeable future, so excluding them from TypeFoldable/TypeVisitable
443        // avoids some unhelpful derive boilerplate.
444        #[type_foldable(identity)]
445        #[type_visitable(ignore)]
446        CoverageKind,
447    ),
448
449    /// Denotes a call to an intrinsic that does not require an unwind path and always returns.
450    /// This avoids adding a new block and a terminator for simple intrinsics.
451    Intrinsic(Box<NonDivergingIntrinsic<'tcx>>),
452
453    /// Instructs the const eval interpreter to increment a counter; this counter is used to track
454    /// how many steps the interpreter has taken. It is used to prevent the user from writing const
455    /// code that runs for too long or infinitely. Other than in the const eval interpreter, this
456    /// is a no-op.
457    ConstEvalCounter,
458
459    /// No-op. Useful for deleting instructions without affecting statement indices.
460    Nop,
461
462    /// Marker statement indicating where `place` would be dropped.
463    /// This is semantically equivalent to `Nop`, so codegen and MIRI should interpret this
464    /// statement as such.
465    /// The only use case of this statement is for linting in MIR to detect temporary lifetime
466    /// changes.
467    BackwardIncompatibleDropHint {
468        /// Place to drop
469        place: Box<Place<'tcx>>,
470        /// Reason for backward incompatibility
471        reason: BackwardIncompatibleDropReason,
472    },
473}
474
475#[derive(
476    Clone,
477    TyEncodable,
478    TyDecodable,
479    Debug,
480    PartialEq,
481    Hash,
482    HashStable,
483    TypeFoldable,
484    TypeVisitable
485)]
486pub enum NonDivergingIntrinsic<'tcx> {
487    /// Denotes a call to the intrinsic function `assume`.
488    ///
489    /// The operand must be a boolean. Optimizers may use the value of the boolean to backtrack its
490    /// computation to infer information about other variables. So if the boolean came from a
491    /// `x < y` operation, subsequent operations on `x` and `y` could elide various bound checks.
492    /// If the argument is `false`, this operation is equivalent to `TerminatorKind::Unreachable`.
493    Assume(Operand<'tcx>),
494
495    /// Denotes a call to the intrinsic function `copy_nonoverlapping`.
496    ///
497    /// First, all three operands are evaluated. `src` and `dest` must each be a reference, pointer,
498    /// or `Box` pointing to the same type `T`. `count` must evaluate to a `usize`. Then, `src` and
499    /// `dest` are dereferenced, and `count * size_of::<T>()` bytes beginning with the first byte of
500    /// the `src` place are copied to the contiguous range of bytes beginning with the first byte
501    /// of `dest`.
502    ///
503    /// **Needs clarification**: In what order are operands computed and dereferenced? It should
504    /// probably match the order for assignment, but that is also undecided.
505    ///
506    /// **Needs clarification**: Is this typed or not, ie is there a typed load and store involved?
507    /// I vaguely remember Ralf saying somewhere that he thought it should not be.
508    CopyNonOverlapping(CopyNonOverlapping<'tcx>),
509}
510
511/// Describes what kind of retag is to be performed.
512#[derive(Copy, Clone, TyEncodable, TyDecodable, Debug, PartialEq, Eq, Hash, HashStable)]
513#[rustc_pass_by_value]
514pub enum RetagKind {
515    /// The initial retag of arguments when entering a function.
516    FnEntry,
517    /// Retag preparing for a two-phase borrow.
518    TwoPhase,
519    /// Retagging raw pointers.
520    Raw,
521    /// A "normal" retag.
522    Default,
523}
524
525/// The `FakeReadCause` describes the type of pattern why a FakeRead statement exists.
526#[derive(Copy, Clone, TyEncodable, TyDecodable, Debug, Hash, HashStable, PartialEq)]
527pub enum FakeReadCause {
528    /// A fake read injected into a match guard to ensure that the discriminants
529    /// that are being matched on aren't modified while the match guard is being
530    /// evaluated.
531    ///
532    /// At the beginning of each match guard, a [fake borrow][FakeBorrowKind] is
533    /// inserted for each discriminant accessed in the entire `match` statement.
534    ///
535    /// Then, at the end of the match guard, a `FakeRead(ForMatchGuard)` is
536    /// inserted to keep the fake borrows alive until that point.
537    ///
538    /// This should ensure that you cannot change the variant for an enum while
539    /// you are in the midst of matching on it.
540    ForMatchGuard,
541
542    /// Fake read of the scrutinee of a `match` or destructuring `let`
543    /// (i.e. `let` with non-trivial pattern).
544    ///
545    /// In `match x { ... }`, we generate a `FakeRead(ForMatchedPlace, x)`
546    /// and insert it into the `otherwise_block` (which is supposed to be
547    /// unreachable for irrefutable pattern-matches like `match` or `let`).
548    ///
549    /// This is necessary because `let x: !; match x {}` doesn't generate any
550    /// actual read of x, so we need to generate a `FakeRead` to check that it
551    /// is initialized.
552    ///
553    /// If the `FakeRead(ForMatchedPlace)` is being performed with a closure
554    /// that doesn't capture the required upvars, the `FakeRead` within the
555    /// closure is omitted entirely.
556    ///
557    /// To make sure that this is still sound, if a closure matches against
558    /// a Place starting with an Upvar, we hoist the `FakeRead` to the
559    /// definition point of the closure.
560    ///
561    /// If the `FakeRead` comes from being hoisted out of a closure like this,
562    /// we record the `LocalDefId` of the closure. Otherwise, the `Option` will be `None`.
563    //
564    // We can use LocalDefId here since fake read statements are removed
565    // before codegen in the `CleanupNonCodegenStatements` pass.
566    ForMatchedPlace(Option<LocalDefId>),
567
568    /// A fake read injected into a match guard to ensure that the places
569    /// bound by the pattern are immutable for the duration of the match guard.
570    ///
571    /// Within a match guard, references are created for each place that the
572    /// pattern creates a binding for — this is known as the `RefWithinGuard`
573    /// version of the variables. To make sure that the references stay
574    /// alive until the end of the match guard, and properly prevent the
575    /// places in question from being modified, a `FakeRead(ForGuardBinding)`
576    /// is inserted at the end of the match guard.
577    ///
578    /// For details on how these references are created, see the extensive
579    /// documentation on `bind_matched_candidate_for_guard` in
580    /// `rustc_mir_build`.
581    ForGuardBinding,
582
583    /// Officially, the semantics of
584    ///
585    /// `let pattern = <expr>;`
586    ///
587    /// is that `<expr>` is evaluated into a temporary and then this temporary is
588    /// into the pattern.
589    ///
590    /// However, if we see the simple pattern `let var = <expr>`, we optimize this to
591    /// evaluate `<expr>` directly into the variable `var`. This is mostly unobservable,
592    /// but in some cases it can affect the borrow checker, as in #53695.
593    ///
594    /// Therefore, we insert a `FakeRead(ForLet)` immediately after each `let`
595    /// with a trivial pattern.
596    ///
597    /// FIXME: `ExprUseVisitor` has an entirely different opinion on what `FakeRead(ForLet)`
598    /// is supposed to mean. If it was accurate to what MIR lowering does,
599    /// would it even make sense to hoist these out of closures like
600    /// `ForMatchedPlace`?
601    ForLet(Option<LocalDefId>),
602
603    /// Currently, index expressions overloaded through the `Index` trait
604    /// get lowered differently than index expressions with builtin semantics
605    /// for arrays and slices — the latter will emit code to perform
606    /// bound checks, and then return a MIR place that will only perform the
607    /// indexing "for real" when it gets incorporated into an instruction.
608    ///
609    /// This is observable in the fact that the following compiles:
610    ///
611    /// ```
612    /// fn f(x: &mut [&mut [u32]], i: usize) {
613    ///     x[i][x[i].len() - 1] += 1;
614    /// }
615    /// ```
616    ///
617    /// However, we need to be careful to not let the user invalidate the
618    /// bound check with an expression like
619    ///
620    /// `(*x)[1][{ x = y; 4}]`
621    ///
622    /// Here, the first bounds check would be invalidated when we evaluate the
623    /// second index expression. To make sure that this doesn't happen, we
624    /// create a fake borrow of `x` and hold it while we evaluate the second
625    /// index.
626    ///
627    /// This borrow is kept alive by a `FakeRead(ForIndex)` at the end of its
628    /// scope.
629    ForIndex,
630}
631
632#[derive(Clone, Debug, PartialEq, TyEncodable, TyDecodable, Hash, HashStable)]
633#[derive(TypeFoldable, TypeVisitable)]
634pub struct CopyNonOverlapping<'tcx> {
635    pub src: Operand<'tcx>,
636    pub dst: Operand<'tcx>,
637    /// Number of elements to copy from src to dest, not bytes.
638    pub count: Operand<'tcx>,
639}
640
641/// Represents how a [`TerminatorKind::Call`] was constructed.
642/// Used only for diagnostics.
643#[derive(Clone, Copy, TyEncodable, TyDecodable, Debug, PartialEq, Hash, HashStable)]
644#[derive(TypeFoldable, TypeVisitable)]
645pub enum CallSource {
646    /// This came from something such as `a > b` or `a + b`. In THIR, if `from_hir_call`
647    /// is false then this is the desugaring.
648    OverloadedOperator,
649    /// This was from comparison generated by a match, used by const-eval for better errors
650    /// when the comparison cannot be done in compile time.
651    ///
652    /// (see <https://github.com/rust-lang/rust/issues/90237>)
653    MatchCmp,
654    /// Other types of desugaring that did not come from the HIR, but we don't care about
655    /// for diagnostics (yet).
656    Misc,
657    /// Use of value, generating a clone function call
658    Use,
659    /// Normal function call, no special source
660    Normal,
661}
662
663#[derive(Clone, Copy, Debug, TyEncodable, TyDecodable, Hash, HashStable, PartialEq)]
664#[derive(TypeFoldable, TypeVisitable)]
665/// The macro that an inline assembly block was created by
666pub enum InlineAsmMacro {
667    /// The `asm!` macro
668    Asm,
669    /// The `naked_asm!` macro
670    NakedAsm,
671}
672
673///////////////////////////////////////////////////////////////////////////
674// Terminators
675
676/// The various kinds of terminators, representing ways of exiting from a basic block.
677///
678/// A note on unwinding: Panics may occur during the execution of some terminators. Depending on the
679/// `-C panic` flag, this may either cause the program to abort or the call stack to unwind. Such
680/// terminators have a `unwind: UnwindAction` field on them. If stack unwinding occurs, then
681/// once the current function is reached, an action will be taken based on the `unwind` field.
682/// If the action is `Cleanup`, then the execution continues at the given basic block. If the
683/// action is `Continue` then no cleanup is performed, and the stack continues unwinding.
684///
685/// The basic block pointed to by a `Cleanup` unwind action must have its `cleanup` flag set.
686/// `cleanup` basic blocks have a couple restrictions:
687///  1. All `unwind` fields in them must be `UnwindAction::Terminate` or `UnwindAction::Unreachable`.
688///  2. `Return` terminators are not allowed in them. `Terminate` and `Resume` terminators are.
689///  3. All other basic blocks (in the current body) that are reachable from `cleanup` basic blocks
690///     must also be `cleanup`. This is a part of the type system and checked statically, so it is
691///     still an error to have such an edge in the CFG even if it's known that it won't be taken at
692///     runtime.
693///  4. The control flow between cleanup blocks must look like an upside down tree. Roughly
694///     speaking, this means that control flow that looks like a V is allowed, while control flow
695///     that looks like a W is not. This is necessary to ensure that landing pad information can be
696///     correctly codegened on MSVC. More precisely:
697///
698///     Begin with the standard control flow graph `G`. Modify `G` as follows: for any two cleanup
699///     vertices `u` and `v` such that `u` dominates `v`, contract `u` and `v` into a single vertex,
700///     deleting self edges and duplicate edges in the process. Now remove all vertices from `G`
701///     that are not cleanup vertices or are not reachable. The resulting graph must be an inverted
702///     tree, that is each vertex may have at most one successor and there may be no cycles.
703#[derive(Clone, TyEncodable, TyDecodable, Hash, HashStable, PartialEq, TypeFoldable, TypeVisitable)]
704pub enum TerminatorKind<'tcx> {
705    /// Block has one successor; we continue execution there.
706    Goto { target: BasicBlock },
707
708    /// Switches based on the computed value.
709    ///
710    /// First, evaluates the `discr` operand. The type of the operand must be a signed or unsigned
711    /// integer, char, or bool, and must match the given type. Then, if the list of switch targets
712    /// contains the computed value, continues execution at the associated basic block. Otherwise,
713    /// continues execution at the "otherwise" basic block.
714    ///
715    /// Target values may not appear more than once.
716    SwitchInt {
717        /// The discriminant value being tested.
718        discr: Operand<'tcx>,
719        targets: SwitchTargets,
720    },
721
722    /// Indicates that the landing pad is finished and that the process should continue unwinding.
723    ///
724    /// Like a return, this marks the end of this invocation of the function.
725    ///
726    /// Only permitted in cleanup blocks. `Resume` is not permitted with `-C unwind=abort` after
727    /// deaggregation runs.
728    UnwindResume,
729
730    /// Indicates that the landing pad is finished and that the process should terminate.
731    ///
732    /// Used to prevent unwinding for foreign items or with `-C unwind=abort`. Only permitted in
733    /// cleanup blocks.
734    UnwindTerminate(UnwindTerminateReason),
735
736    /// Returns from the function.
737    ///
738    /// Like function calls, the exact semantics of returns in Rust are unclear. Returning very
739    /// likely at least assigns the value currently in the return place (`_0`) to the place
740    /// specified in the associated `Call` terminator in the calling function, as if assigned via
741    /// `dest = move _0`. It might additionally do other things, like have side-effects in the
742    /// aliasing model.
743    ///
744    /// If the body is a coroutine body, this has slightly different semantics; it instead causes a
745    /// `CoroutineState::Returned(_0)` to be created (as if by an `Aggregate` rvalue) and assigned
746    /// to the return place.
747    Return,
748
749    /// Indicates a terminator that can never be reached.
750    ///
751    /// Executing this terminator is UB.
752    Unreachable,
753
754    /// The behavior of this statement differs significantly before and after drop elaboration.
755    ///
756    /// After drop elaboration: `Drop` terminators are a complete nop for types that have no drop
757    /// glue. For other types, `Drop` terminators behave exactly like a call to
758    /// `core::mem::drop_in_place` with a pointer to the given place.
759    ///
760    /// `Drop` before drop elaboration is a *conditional* execution of the drop glue. Specifically,
761    /// the `Drop` will be executed if...
762    ///
763    /// **Needs clarification**: End of that sentence. This in effect should document the exact
764    /// behavior of drop elaboration. The following sounds vaguely right, but I'm not quite sure:
765    ///
766    /// > The drop glue is executed if, among all statements executed within this `Body`, an assignment to
767    /// > the place or one of its "parents" occurred more recently than a move out of it. This does not
768    /// > consider indirect assignments.
769    ///
770    /// The `replace` flag indicates whether this terminator was created as part of an assignment.
771    /// This should only be used for diagnostic purposes, and does not have any operational
772    /// meaning.
773    ///
774    /// Async drop processing:
775    /// In compiler/rustc_mir_build/src/build/scope.rs we detect possible async drop:
776    ///   drop of object with `needs_async_drop`.
777    /// Async drop later, in StateTransform pass, may be expanded into additional yield-point
778    ///   for poll-loop of async drop future.
779    /// So we need prepared 'drop' target block in the similar way as for `Yield` terminator
780    ///   (see `drops.build_mir::<CoroutineDrop>` in scopes.rs).
781    /// In compiler/rustc_mir_transform/src/elaborate_drops.rs for object implementing `AsyncDrop` trait
782    ///   we need to prepare async drop feature - resolve `AsyncDrop::drop` and codegen call.
783    /// `async_fut` is set to the corresponding local.
784    /// For coroutine drop we don't need this logic because coroutine drop works with the same
785    ///   layout object as coroutine itself. So `async_fut` will be `None` for coroutine drop.
786    /// Both `drop` and `async_fut` fields are only used in compiler/rustc_mir_transform/src/coroutine.rs,
787    ///   StateTransform pass. In `expand_async_drops` async drops are expanded
788    ///   into one or two yield points with poll ready/pending switch.
789    /// When a coroutine has any internal async drop, the coroutine drop function will be async
790    ///   (generated by `create_coroutine_drop_shim_async`, not `create_coroutine_drop_shim`).
791    Drop {
792        place: Place<'tcx>,
793        target: BasicBlock,
794        unwind: UnwindAction,
795        replace: bool,
796        /// Cleanup to be done if the coroutine is dropped at this suspend point (for async drop).
797        drop: Option<BasicBlock>,
798        /// Prepared async future local (for async drop)
799        async_fut: Option<Local>,
800    },
801
802    /// Roughly speaking, evaluates the `func` operand and the arguments, and starts execution of
803    /// the referred to function. The operand types must match the argument types of the function.
804    /// The return place type must match the return type. The type of the `func` operand must be
805    /// callable, meaning either a function pointer, a function type, or a closure type.
806    ///
807    /// **Needs clarification**: The exact semantics of this. Current backends rely on `move`
808    /// operands not aliasing the return place. It is unclear how this is justified in MIR, see
809    /// [#71117].
810    ///
811    /// [#71117]: https://github.com/rust-lang/rust/issues/71117
812    Call {
813        /// The function that’s being called.
814        func: Operand<'tcx>,
815        /// Arguments the function is called with.
816        /// These are owned by the callee, which is free to modify them.
817        /// This allows the memory occupied by "by-value" arguments to be
818        /// reused across function calls without duplicating the contents.
819        /// The span for each arg is also included
820        /// (e.g. `a` and `b` in `x.foo(a, b)`).
821        args: Box<[Spanned<Operand<'tcx>>]>,
822        /// Where the returned value will be written
823        destination: Place<'tcx>,
824        /// Where to go after this call returns. If none, the call necessarily diverges.
825        target: Option<BasicBlock>,
826        /// Action to be taken if the call unwinds.
827        unwind: UnwindAction,
828        /// Where this call came from in HIR/THIR.
829        call_source: CallSource,
830        /// This `Span` is the span of the function, without the dot and receiver
831        /// e.g. `foo(a, b)` in `x.foo(a, b)`
832        fn_span: Span,
833    },
834
835    /// Tail call.
836    ///
837    /// Roughly speaking this is a chimera of [`Call`] and [`Return`], with some caveats.
838    /// Semantically tail calls consists of two actions:
839    /// - pop of the current stack frame
840    /// - a call to the `func`, with the return address of the **current** caller
841    ///   - so that a `return` inside `func` returns to the caller of the caller
842    ///     of the function that is currently being executed
843    ///
844    /// Note that in difference with [`Call`] this is missing
845    /// - `destination` (because it's always the return place)
846    /// - `target` (because it's always taken from the current stack frame)
847    /// - `unwind` (because it's always taken from the current stack frame)
848    ///
849    /// [`Call`]: TerminatorKind::Call
850    /// [`Return`]: TerminatorKind::Return
851    TailCall {
852        /// The function that’s being called.
853        func: Operand<'tcx>,
854        /// Arguments the function is called with.
855        /// These are owned by the callee, which is free to modify them.
856        /// This allows the memory occupied by "by-value" arguments to be
857        /// reused across function calls without duplicating the contents.
858        args: Box<[Spanned<Operand<'tcx>>]>,
859        // FIXME(explicit_tail_calls): should we have the span for `become`? is this span accurate? do we need it?
860        /// This `Span` is the span of the function, without the dot and receiver
861        /// (e.g. `foo(a, b)` in `x.foo(a, b)`
862        fn_span: Span,
863    },
864
865    /// Evaluates the operand, which must have type `bool`. If it is not equal to `expected`,
866    /// initiates a panic. Initiating a panic corresponds to a `Call` terminator with some
867    /// unspecified constant as the function to call, all the operands stored in the `AssertMessage`
868    /// as parameters, and `None` for the destination. Keep in mind that the `cleanup` path is not
869    /// necessarily executed even in the case of a panic, for example in `-C panic=abort`. If the
870    /// assertion does not fail, execution continues at the specified basic block.
871    ///
872    /// When overflow checking is disabled and this is run-time MIR (as opposed to compile-time MIR
873    /// that is used for CTFE), the following variants of this terminator behave as `goto target`:
874    /// - `OverflowNeg(..)`,
875    /// - `Overflow(op, ..)` if op is add, sub, mul, shl, shr, but NOT div or rem.
876    Assert {
877        cond: Operand<'tcx>,
878        expected: bool,
879        msg: Box<AssertMessage<'tcx>>,
880        target: BasicBlock,
881        unwind: UnwindAction,
882    },
883
884    /// Marks a suspend point.
885    ///
886    /// Like `Return` terminators in coroutine bodies, this computes `value` and then a
887    /// `CoroutineState::Yielded(value)` as if by `Aggregate` rvalue. That value is then assigned to
888    /// the return place of the function calling this one, and execution continues in the calling
889    /// function. When next invoked with the same first argument, execution of this function
890    /// continues at the `resume` basic block, with the second argument written to the `resume_arg`
891    /// place. If the coroutine is dropped before then, the `drop` basic block is invoked.
892    ///
893    /// Note that coroutines can be (unstably) cloned under certain conditions, which means that
894    /// this terminator can **return multiple times**! MIR optimizations that reorder code into
895    /// different basic blocks needs to be aware of that.
896    /// See <https://github.com/rust-lang/rust/issues/95360>.
897    ///
898    /// Not permitted in bodies that are not coroutine bodies, or after coroutine lowering.
899    ///
900    /// **Needs clarification**: What about the evaluation order of the `resume_arg` and `value`?
901    Yield {
902        /// The value to return.
903        value: Operand<'tcx>,
904        /// Where to resume to.
905        resume: BasicBlock,
906        /// The place to store the resume argument in.
907        resume_arg: Place<'tcx>,
908        /// Cleanup to be done if the coroutine is dropped at this suspend point.
909        drop: Option<BasicBlock>,
910    },
911
912    /// Indicates the end of dropping a coroutine.
913    ///
914    /// Semantically just a `return` (from the coroutines drop glue). Only permitted in the same situations
915    /// as `yield`.
916    ///
917    /// **Needs clarification**: Is that even correct? The coroutine drop code is always confusing
918    /// to me, because it's not even really in the current body.
919    ///
920    /// **Needs clarification**: Are there type system constraints on these terminators? Should
921    /// there be a "block type" like `cleanup` blocks for them?
922    CoroutineDrop,
923
924    /// A block where control flow only ever takes one real path, but borrowck needs to be more
925    /// conservative.
926    ///
927    /// At runtime this is semantically just a goto.
928    ///
929    /// Disallowed after drop elaboration.
930    FalseEdge {
931        /// The target normal control flow will take.
932        real_target: BasicBlock,
933        /// A block control flow could conceptually jump to, but won't in
934        /// practice.
935        imaginary_target: BasicBlock,
936    },
937
938    /// A terminator for blocks that only take one path in reality, but where we reserve the right
939    /// to unwind in borrowck, even if it won't happen in practice. This can arise in infinite loops
940    /// with no function calls for example.
941    ///
942    /// At runtime this is semantically just a goto.
943    ///
944    /// Disallowed after drop elaboration.
945    FalseUnwind {
946        /// The target normal control flow will take.
947        real_target: BasicBlock,
948        /// The imaginary cleanup block link. This particular path will never be taken
949        /// in practice, but in order to avoid fragility we want to always
950        /// consider it in borrowck. We don't want to accept programs which
951        /// pass borrowck only when `panic=abort` or some assertions are disabled
952        /// due to release vs. debug mode builds.
953        unwind: UnwindAction,
954    },
955
956    /// Block ends with an inline assembly block. This is a terminator since
957    /// inline assembly is allowed to diverge.
958    InlineAsm {
959        /// Macro used to create this inline asm: one of `asm!` or `naked_asm!`
960        asm_macro: InlineAsmMacro,
961
962        /// The template for the inline assembly, with placeholders.
963        #[type_foldable(identity)]
964        #[type_visitable(ignore)]
965        template: &'tcx [InlineAsmTemplatePiece],
966
967        /// The operands for the inline assembly, as `Operand`s or `Place`s.
968        operands: Box<[InlineAsmOperand<'tcx>]>,
969
970        /// Miscellaneous options for the inline assembly.
971        options: InlineAsmOptions,
972
973        /// Source spans for each line of the inline assembly code. These are
974        /// used to map assembler errors back to the line in the source code.
975        #[type_foldable(identity)]
976        #[type_visitable(ignore)]
977        line_spans: &'tcx [Span],
978
979        /// Valid targets for the inline assembly.
980        /// The first element is the fallthrough destination, unless
981        /// asm_macro == InlineAsmMacro::NakedAsm or InlineAsmOptions::NORETURN is set.
982        targets: Box<[BasicBlock]>,
983
984        /// Action to be taken if the inline assembly unwinds. This is present
985        /// if and only if InlineAsmOptions::MAY_UNWIND is set.
986        unwind: UnwindAction,
987    },
988}
989
990#[derive(
991    Clone,
992    Debug,
993    TyEncodable,
994    TyDecodable,
995    Hash,
996    HashStable,
997    PartialEq,
998    TypeFoldable,
999    TypeVisitable
1000)]
1001pub enum BackwardIncompatibleDropReason {
1002    Edition2024,
1003}
1004
1005#[derive(Debug, Clone, TyEncodable, TyDecodable, Hash, HashStable, PartialEq)]
1006pub struct SwitchTargets {
1007    /// Possible values. For each value, the location to branch to is found in
1008    /// the corresponding element in the `targets` vector.
1009    pub(super) values: SmallVec<[Pu128; 1]>,
1010
1011    /// Possible branch targets. The last element of this vector is used for
1012    /// the "otherwise" branch, so `targets.len() == values.len() + 1` always
1013    /// holds.
1014    //
1015    // Note: This invariant is non-obvious and easy to violate. This would be a
1016    // more rigorous representation:
1017    //
1018    //   normal: SmallVec<[(Pu128, BasicBlock); 1]>,
1019    //   otherwise: BasicBlock,
1020    //
1021    // But it's important to have the targets in a sliceable type, because
1022    // target slices show up elsewhere. E.g. `TerminatorKind::InlineAsm` has a
1023    // boxed slice, and `TerminatorKind::FalseEdge` has a single target that
1024    // can be converted to a slice with `slice::from_ref`.
1025    //
1026    // Why does this matter? In functions like `TerminatorKind::successors` we
1027    // return `impl Iterator` and a non-slice-of-targets representation here
1028    // causes problems because multiple different concrete iterator types would
1029    // be involved and we would need a boxed trait object, which requires an
1030    // allocation, which is expensive if done frequently.
1031    pub(super) targets: SmallVec<[BasicBlock; 2]>,
1032}
1033
1034/// Action to be taken when a stack unwind happens.
1035#[derive(Copy, Clone, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1036#[derive(TypeFoldable, TypeVisitable)]
1037pub enum UnwindAction {
1038    /// No action is to be taken. Continue unwinding.
1039    ///
1040    /// This is similar to `Cleanup(bb)` where `bb` does nothing but `Resume`, but they are not
1041    /// equivalent, as presence of `Cleanup(_)` will make a frame non-POF.
1042    Continue,
1043    /// Triggers undefined behavior if unwind happens.
1044    Unreachable,
1045    /// Terminates the execution if unwind happens.
1046    ///
1047    /// Depending on the platform and situation this may cause a non-unwindable panic or abort.
1048    Terminate(UnwindTerminateReason),
1049    /// Cleanups to be done.
1050    Cleanup(BasicBlock),
1051}
1052
1053/// The reason we are terminating the process during unwinding.
1054#[derive(Copy, Clone, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1055#[derive(TypeFoldable, TypeVisitable)]
1056pub enum UnwindTerminateReason {
1057    /// Unwinding is just not possible given the ABI of this function.
1058    Abi,
1059    /// We were already cleaning up for an ongoing unwind, and a *second*, *nested* unwind was
1060    /// triggered by the drop glue.
1061    InCleanup,
1062}
1063
1064/// Information about an assertion failure.
1065#[derive(Clone, Hash, HashStable, PartialEq, Debug)]
1066#[derive(TyEncodable, TyDecodable, TypeFoldable, TypeVisitable)]
1067pub enum AssertKind<O> {
1068    BoundsCheck { len: O, index: O },
1069    Overflow(BinOp, O, O),
1070    OverflowNeg(O),
1071    DivisionByZero(O),
1072    RemainderByZero(O),
1073    ResumedAfterReturn(CoroutineKind),
1074    ResumedAfterPanic(CoroutineKind),
1075    ResumedAfterDrop(CoroutineKind),
1076    MisalignedPointerDereference { required: O, found: O },
1077    NullPointerDereference,
1078}
1079
1080#[derive(Clone, Debug, PartialEq, TyEncodable, TyDecodable, Hash, HashStable)]
1081#[derive(TypeFoldable, TypeVisitable)]
1082pub enum InlineAsmOperand<'tcx> {
1083    In {
1084        reg: InlineAsmRegOrRegClass,
1085        value: Operand<'tcx>,
1086    },
1087    Out {
1088        reg: InlineAsmRegOrRegClass,
1089        late: bool,
1090        place: Option<Place<'tcx>>,
1091    },
1092    InOut {
1093        reg: InlineAsmRegOrRegClass,
1094        late: bool,
1095        in_value: Operand<'tcx>,
1096        out_place: Option<Place<'tcx>>,
1097    },
1098    Const {
1099        value: Box<ConstOperand<'tcx>>,
1100    },
1101    SymFn {
1102        value: Box<ConstOperand<'tcx>>,
1103    },
1104    SymStatic {
1105        def_id: DefId,
1106    },
1107    Label {
1108        /// This represents the index into the `targets` array in `TerminatorKind::InlineAsm`.
1109        target_index: usize,
1110    },
1111}
1112
1113/// Type for MIR `Assert` terminator error messages.
1114pub type AssertMessage<'tcx> = AssertKind<Operand<'tcx>>;
1115
1116///////////////////////////////////////////////////////////////////////////
1117// Places
1118
1119/// Places roughly correspond to a "location in memory." Places in MIR are the same mathematical
1120/// object as places in Rust. This of course means that what exactly they are is undecided and part
1121/// of the Rust memory model. However, they will likely contain at least the following pieces of
1122/// information in some form:
1123///
1124///  1. The address in memory that the place refers to.
1125///  2. The provenance with which the place is being accessed.
1126///  3. The type of the place and an optional variant index. See [`PlaceTy`][super::PlaceTy].
1127///  4. Optionally, some metadata. This exists if and only if the type of the place is not `Sized`.
1128///
1129/// We'll give a description below of how all pieces of the place except for the provenance are
1130/// calculated. We cannot give a description of the provenance, because that is part of the
1131/// undecided aliasing model - we only include it here at all to acknowledge its existence.
1132///
1133/// Each local naturally corresponds to the place `Place { local, projection: [] }`. This place has
1134/// the address of the local's allocation and the type of the local.
1135///
1136/// **Needs clarification:** Unsized locals seem to present a bit of an issue. Their allocation
1137/// can't actually be created on `StorageLive`, because it's unclear how big to make the allocation.
1138/// Furthermore, MIR produces assignments to unsized locals, although that is not permitted under
1139/// `#![feature(unsized_locals)]` in Rust. Besides just putting "unsized locals are special and
1140/// different" in a bunch of places, I (JakobDegen) don't know how to incorporate this behavior into
1141/// the current MIR semantics in a clean way - possibly this needs some design work first.
1142///
1143/// For places that are not locals, ie they have a non-empty list of projections, we define the
1144/// values as a function of the parent place, that is the place with its last [`ProjectionElem`]
1145/// stripped. The way this is computed of course depends on the kind of that last projection
1146/// element:
1147///
1148///  - [`Downcast`](ProjectionElem::Downcast): This projection sets the place's variant index to the
1149///    given one, and makes no other changes. A `Downcast` projection must always be followed
1150///    immediately by a `Field` projection.
1151///  - [`Field`](ProjectionElem::Field): `Field` projections take their parent place and create a
1152///    place referring to one of the fields of the type. The resulting address is the parent
1153///    address, plus the offset of the field. The type becomes the type of the field. If the parent
1154///    was unsized and so had metadata associated with it, then the metadata is retained if the
1155///    field is unsized and thrown out if it is sized.
1156///
1157///    These projections are only legal for tuples, ADTs, closures, and coroutines. If the ADT or
1158///    coroutine has more than one variant, the parent place's variant index must be set, indicating
1159///    which variant is being used. If it has just one variant, the variant index may or may not be
1160///    included - the single possible variant is inferred if it is not included.
1161///  - [`OpaqueCast`](ProjectionElem::OpaqueCast): This projection changes the place's type to the
1162///    given one, and makes no other changes. A `OpaqueCast` projection on any type other than an
1163///    opaque type from the current crate is not well-formed.
1164///  - [`ConstantIndex`](ProjectionElem::ConstantIndex): Computes an offset in units of `T` into the
1165///    place as described in the documentation for the `ProjectionElem`. The resulting address is
1166///    the parent's address plus that offset, and the type is `T`. This is only legal if the parent
1167///    place has type `[T;  N]` or `[T]` (*not* `&[T]`). Since such a `T` is always sized, any
1168///    resulting metadata is thrown out.
1169///  - [`Subslice`](ProjectionElem::Subslice): This projection calculates an offset and a new
1170///    address in a similar manner as `ConstantIndex`. It is also only legal on `[T; N]` and `[T]`.
1171///    However, this yields a `Place` of type `[T]`, and additionally sets the metadata to be the
1172///    length of the subslice.
1173///  - [`Index`](ProjectionElem::Index): Like `ConstantIndex`, only legal on `[T; N]` or `[T]`.
1174///    However, `Index` additionally takes a local from which the value of the index is computed at
1175///    runtime. Computing the value of the index involves interpreting the `Local` as a
1176///    `Place { local, projection: [] }`, and then computing its value as if done via
1177///    [`Operand::Copy`]. The array/slice is then indexed with the resulting value. The local must
1178///    have type `usize`.
1179///  - [`Deref`](ProjectionElem::Deref): Derefs are the last type of projection, and the most
1180///    complicated. They are only legal on parent places that are references, pointers, or `Box`. A
1181///    `Deref` projection begins by loading a value from the parent place, as if by
1182///    [`Operand::Copy`]. It then dereferences the resulting pointer, creating a place of the
1183///    pointee's type. The resulting address is the address that was stored in the pointer. If the
1184///    pointee type is unsized, the pointer additionally stored the value of the metadata.
1185///
1186/// The "validity invariant" of places is the same as that of raw pointers, meaning that e.g.
1187/// `*ptr` on a dangling or unaligned pointer is never UB. (Later doing a load/store on that place
1188/// or turning it into a reference can be UB though!) The only ways for a place computation can
1189/// cause UB are:
1190/// - On a `Deref` projection, we do an actual load of the inner place, with all the usual
1191///   consequences (the inner place must be based on an aligned pointer, it must point to allocated
1192///   memory, the aliasig model must allow reads, this must not be a data race).
1193/// - For the projections that perform pointer arithmetic, the offset must in-bounds of an
1194///   allocation (i.e., the preconditions of `ptr::offset` must be met).
1195#[derive(Copy, Clone, PartialEq, Eq, Hash, TyEncodable, HashStable, TypeFoldable, TypeVisitable)]
1196pub struct Place<'tcx> {
1197    pub local: Local,
1198
1199    /// projection out of a place (access a field, deref a pointer, etc)
1200    pub projection: &'tcx List<PlaceElem<'tcx>>,
1201}
1202
1203#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
1204#[derive(TyEncodable, TyDecodable, HashStable, TypeFoldable, TypeVisitable)]
1205pub enum ProjectionElem<V, T> {
1206    Deref,
1207
1208    /// A field (e.g., `f` in `_1.f`) is one variant of [`ProjectionElem`]. Conceptually,
1209    /// rustc can identify that a field projection refers to either two different regions of memory
1210    /// or the same one between the base and the 'projection element'.
1211    /// Read more about projections in the [rustc-dev-guide][mir-datatypes]
1212    ///
1213    /// [mir-datatypes]: https://rustc-dev-guide.rust-lang.org/mir/index.html#mir-data-types
1214    Field(FieldIdx, T),
1215
1216    /// Index into a slice/array.
1217    ///
1218    /// Note that this does not also dereference, and so it does not exactly correspond to slice
1219    /// indexing in Rust. In other words, in the below Rust code:
1220    ///
1221    /// ```rust
1222    /// let x = &[1, 2, 3, 4];
1223    /// let i = 2;
1224    /// x[i];
1225    /// ```
1226    ///
1227    /// The `x[i]` is turned into a `Deref` followed by an `Index`, not just an `Index`. The same
1228    /// thing is true of the `ConstantIndex` and `Subslice` projections below.
1229    Index(V),
1230
1231    /// These indices are generated by slice patterns. Easiest to explain
1232    /// by example:
1233    ///
1234    /// ```ignore (illustrative)
1235    /// [X, _, .._, _, _] => { offset: 0, min_length: 4, from_end: false },
1236    /// [_, X, .._, _, _] => { offset: 1, min_length: 4, from_end: false },
1237    /// [_, _, .._, X, _] => { offset: 2, min_length: 4, from_end: true },
1238    /// [_, _, .._, _, X] => { offset: 1, min_length: 4, from_end: true },
1239    /// ```
1240    ConstantIndex {
1241        /// index or -index (in Python terms), depending on from_end
1242        offset: u64,
1243        /// The thing being indexed must be at least this long -- otherwise, the
1244        /// projection is UB.
1245        ///
1246        /// For arrays this is always the exact length.
1247        min_length: u64,
1248        /// Counting backwards from end? This is always false when indexing an
1249        /// array.
1250        from_end: bool,
1251    },
1252
1253    /// These indices are generated by slice patterns.
1254    ///
1255    /// If `from_end` is true `slice[from..slice.len() - to]`.
1256    /// Otherwise `array[from..to]`.
1257    Subslice {
1258        from: u64,
1259        to: u64,
1260        /// Whether `to` counts from the start or end of the array/slice.
1261        /// For `PlaceElem`s this is `true` if and only if the base is a slice.
1262        /// For `ProjectionKind`, this can also be `true` for arrays.
1263        from_end: bool,
1264    },
1265
1266    /// "Downcast" to a variant of an enum or a coroutine.
1267    ///
1268    /// The included Symbol is the name of the variant, used for printing MIR.
1269    ///
1270    /// This operation itself is never UB, all it does is change the type of the place.
1271    Downcast(Option<Symbol>, VariantIdx),
1272
1273    /// Like an explicit cast from an opaque type to a concrete type, but without
1274    /// requiring an intermediate variable.
1275    ///
1276    /// This is unused with `-Znext-solver`.
1277    OpaqueCast(T),
1278
1279    /// A transmute from an unsafe binder to the type that it wraps. This is a projection
1280    /// of a place, so it doesn't necessarily constitute a move out of the binder.
1281    UnwrapUnsafeBinder(T),
1282
1283    /// A `Subtype(T)` projection is applied to any `StatementKind::Assign` where
1284    /// type of lvalue doesn't match the type of rvalue, the primary goal is making subtyping
1285    /// explicit during optimizations and codegen.
1286    ///
1287    /// This projection doesn't impact the runtime behavior of the program except for potentially changing
1288    /// some type metadata of the interpreter or codegen backend.
1289    ///
1290    /// This goal is achieved with mir_transform pass `Subtyper`, which runs right after
1291    /// borrowchecker, as we only care about subtyping that can affect trait selection and
1292    /// `TypeId`.
1293    Subtype(T),
1294}
1295
1296/// Alias for projections as they appear in places, where the base is a place
1297/// and the index is a local.
1298pub type PlaceElem<'tcx> = ProjectionElem<Local, Ty<'tcx>>;
1299
1300///////////////////////////////////////////////////////////////////////////
1301// Operands
1302
1303/// An operand in MIR represents a "value" in Rust, the definition of which is undecided and part of
1304/// the memory model. One proposal for a definition of values can be found [on UCG][value-def].
1305///
1306/// [value-def]: https://github.com/rust-lang/unsafe-code-guidelines/blob/master/wip/value-domain.md
1307///
1308/// The most common way to create values is via loading a place. Loading a place is an operation
1309/// which reads the memory of the place and converts it to a value. This is a fundamentally *typed*
1310/// operation. The nature of the value produced depends on the type of the conversion. Furthermore,
1311/// there may be other effects: if the type has a validity constraint loading the place might be UB
1312/// if the validity constraint is not met.
1313///
1314/// **Needs clarification:** Is loading a place that has its variant index set well-formed? Miri
1315/// currently implements it, but it seems like this may be something to check against in the
1316/// validator.
1317#[derive(Clone, PartialEq, TyEncodable, TyDecodable, Hash, HashStable, TypeFoldable, TypeVisitable)]
1318pub enum Operand<'tcx> {
1319    /// Creates a value by loading the given place.
1320    ///
1321    /// Before drop elaboration, the type of the place must be `Copy`. After drop elaboration there
1322    /// is no such requirement.
1323    Copy(Place<'tcx>),
1324
1325    /// Creates a value by performing loading the place, just like the `Copy` operand.
1326    ///
1327    /// This *may* additionally overwrite the place with `uninit` bytes, depending on how we decide
1328    /// in [UCG#188]. You should not emit MIR that may attempt a subsequent second load of this
1329    /// place without first re-initializing it.
1330    ///
1331    /// **Needs clarification:** The operational impact of `Move` is unclear. Currently (both in
1332    /// Miri and codegen) it has no effect at all unless it appears in an argument to `Call`; for
1333    /// `Call` it allows the argument to be passed to the callee "in-place", i.e. the callee might
1334    /// just get a reference to this place instead of a full copy. Miri implements this with a
1335    /// combination of aliasing model "protectors" and putting `uninit` into the place. Ralf
1336    /// proposes that we don't want these semantics for `Move` in regular assignments, because
1337    /// loading a place should not have side-effects, and the aliasing model "protectors" are
1338    /// inherently tied to a function call. Are these the semantics we want for MIR? Is this
1339    /// something we can even decide without knowing more about Rust's memory model?
1340    ///
1341    /// [UCG#188]: https://github.com/rust-lang/unsafe-code-guidelines/issues/188
1342    Move(Place<'tcx>),
1343
1344    /// Constants are already semantically values, and remain unchanged.
1345    Constant(Box<ConstOperand<'tcx>>),
1346}
1347
1348#[derive(Clone, Copy, PartialEq, TyEncodable, TyDecodable, Hash, HashStable)]
1349#[derive(TypeFoldable, TypeVisitable)]
1350pub struct ConstOperand<'tcx> {
1351    pub span: Span,
1352
1353    /// Optional user-given type: for something like
1354    /// `collect::<Vec<_>>`, this would be present and would
1355    /// indicate that `Vec<_>` was explicitly specified.
1356    ///
1357    /// Needed for NLL to impose user-given type constraints.
1358    pub user_ty: Option<UserTypeAnnotationIndex>,
1359
1360    pub const_: Const<'tcx>,
1361}
1362
1363///////////////////////////////////////////////////////////////////////////
1364// Rvalues
1365
1366/// The various kinds of rvalues that can appear in MIR.
1367///
1368/// Not all of these are allowed at every [`MirPhase`] - when this is the case, it's stated below.
1369///
1370/// Computing any rvalue begins by evaluating the places and operands in some order (**Needs
1371/// clarification**: Which order?). These are then used to produce a "value" - the same kind of
1372/// value that an [`Operand`] produces.
1373#[derive(Clone, TyEncodable, TyDecodable, Hash, HashStable, PartialEq, TypeFoldable, TypeVisitable)]
1374pub enum Rvalue<'tcx> {
1375    /// Yields the operand unchanged
1376    Use(Operand<'tcx>),
1377
1378    /// Creates an array where each element is the value of the operand.
1379    ///
1380    /// This is the cause of a bug in the case where the repetition count is zero because the value
1381    /// is not dropped, see [#74836].
1382    ///
1383    /// Corresponds to source code like `[x; 32]`.
1384    ///
1385    /// [#74836]: https://github.com/rust-lang/rust/issues/74836
1386    Repeat(Operand<'tcx>, ty::Const<'tcx>),
1387
1388    /// Creates a reference of the indicated kind to the place.
1389    ///
1390    /// There is not much to document here, because besides the obvious parts the semantics of this
1391    /// are essentially entirely a part of the aliasing model. There are many UCG issues discussing
1392    /// exactly what the behavior of this operation should be.
1393    ///
1394    /// `Shallow` borrows are disallowed after drop lowering.
1395    Ref(Region<'tcx>, BorrowKind, Place<'tcx>),
1396
1397    /// Creates a pointer/reference to the given thread local.
1398    ///
1399    /// The yielded type is a `*mut T` if the static is mutable, otherwise if the static is extern a
1400    /// `*const T`, and if neither of those apply a `&T`.
1401    ///
1402    /// **Note:** This is a runtime operation that actually executes code and is in this sense more
1403    /// like a function call. Also, eliminating dead stores of this rvalue causes `fn main() {}` to
1404    /// SIGILL for some reason that I (JakobDegen) never got a chance to look into.
1405    ///
1406    /// **Needs clarification**: Are there weird additional semantics here related to the runtime
1407    /// nature of this operation?
1408    ThreadLocalRef(DefId),
1409
1410    /// Creates a raw pointer with the indicated mutability to the place.
1411    ///
1412    /// This is generated by pointer casts like `&v as *const _` or raw borrow expressions like
1413    /// `&raw const v`.
1414    ///
1415    /// Like with references, the semantics of this operation are heavily dependent on the aliasing
1416    /// model.
1417    RawPtr(RawPtrKind, Place<'tcx>),
1418
1419    /// Yields the length of the place, as a `usize`.
1420    ///
1421    /// If the type of the place is an array, this is the array length. For slices (`[T]`, not
1422    /// `&[T]`) this accesses the place's metadata to determine the length. This rvalue is
1423    /// ill-formed for places of other types.
1424    ///
1425    /// This cannot be a `UnOp(PtrMetadata, _)` because that expects a value, and we only
1426    /// have a place, and `UnOp(PtrMetadata, RawPtr(place))` is not a thing.
1427    Len(Place<'tcx>),
1428
1429    /// Performs essentially all of the casts that can be performed via `as`.
1430    ///
1431    /// This allows for casts from/to a variety of types.
1432    ///
1433    /// **FIXME**: Document exactly which `CastKind`s allow which types of casts.
1434    Cast(CastKind, Operand<'tcx>, Ty<'tcx>),
1435
1436    /// * `Offset` has the same semantics as [`offset`](pointer::offset), except that the second
1437    ///   parameter may be a `usize` as well.
1438    /// * The comparison operations accept `bool`s, `char`s, signed or unsigned integers, floats,
1439    ///   raw pointers, or function pointers and return a `bool`. The types of the operands must be
1440    ///   matching, up to the usual caveat of the lifetimes in function pointers.
1441    /// * Left and right shift operations accept signed or unsigned integers not necessarily of the
1442    ///   same type and return a value of the same type as their LHS. Like in Rust, the RHS is
1443    ///   truncated as needed.
1444    /// * The `Bit*` operations accept signed integers, unsigned integers, or bools with matching
1445    ///   types and return a value of that type.
1446    /// * The `FooWithOverflow` are like the `Foo`, but returning `(T, bool)` instead of just `T`,
1447    ///   where the `bool` is true if the result is not equal to the infinite-precision result.
1448    /// * The remaining operations accept signed integers, unsigned integers, or floats with
1449    ///   matching types and return a value of that type.
1450    BinaryOp(BinOp, Box<(Operand<'tcx>, Operand<'tcx>)>),
1451
1452    /// Computes a value as described by the operation.
1453    NullaryOp(NullOp<'tcx>, Ty<'tcx>),
1454
1455    /// Exactly like `BinaryOp`, but less operands.
1456    ///
1457    /// Also does two's-complement arithmetic. Negation requires a signed integer or a float;
1458    /// bitwise not requires a signed integer, unsigned integer, or bool. Both operation kinds
1459    /// return a value with the same type as their operand.
1460    UnaryOp(UnOp, Operand<'tcx>),
1461
1462    /// Computes the discriminant of the place, returning it as an integer of type
1463    /// [`discriminant_ty`]. Returns zero for types without discriminant.
1464    ///
1465    /// The validity requirements for the underlying value are undecided for this rvalue, see
1466    /// [#91095]. Note too that the value of the discriminant is not the same thing as the
1467    /// variant index; use [`discriminant_for_variant`] to convert.
1468    ///
1469    /// [`discriminant_ty`]: crate::ty::Ty::discriminant_ty
1470    /// [#91095]: https://github.com/rust-lang/rust/issues/91095
1471    /// [`discriminant_for_variant`]: crate::ty::Ty::discriminant_for_variant
1472    Discriminant(Place<'tcx>),
1473
1474    /// Creates an aggregate value, like a tuple or struct.
1475    ///
1476    /// This is needed because dataflow analysis needs to distinguish
1477    /// `dest = Foo { x: ..., y: ... }` from `dest.x = ...; dest.y = ...;` in the case that `Foo`
1478    /// has a destructor.
1479    ///
1480    /// Disallowed after deaggregation for all aggregate kinds except `Array` and `Coroutine`. After
1481    /// coroutine lowering, `Coroutine` aggregate kinds are disallowed too.
1482    Aggregate(Box<AggregateKind<'tcx>>, IndexVec<FieldIdx, Operand<'tcx>>),
1483
1484    /// Transmutes a `*mut u8` into shallow-initialized `Box<T>`.
1485    ///
1486    /// This is different from a normal transmute because dataflow analysis will treat the box as
1487    /// initialized but its content as uninitialized. Like other pointer casts, this in general
1488    /// affects alias analysis.
1489    ShallowInitBox(Operand<'tcx>, Ty<'tcx>),
1490
1491    /// A CopyForDeref is equivalent to a read from a place at the
1492    /// codegen level, but is treated specially by drop elaboration. When such a read happens, it
1493    /// is guaranteed (via nature of the mir_opt `Derefer` in rustc_mir_transform/src/deref_separator)
1494    /// that the only use of the returned value is a deref operation, immediately
1495    /// followed by one or more projections. Drop elaboration treats this rvalue as if the
1496    /// read never happened and just projects further. This allows simplifying various MIR
1497    /// optimizations and codegen backends that previously had to handle deref operations anywhere
1498    /// in a place.
1499    CopyForDeref(Place<'tcx>),
1500
1501    /// Wraps a value in an unsafe binder.
1502    WrapUnsafeBinder(Operand<'tcx>, Ty<'tcx>),
1503}
1504
1505#[derive(Clone, Copy, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1506pub enum CastKind {
1507    /// An exposing pointer to address cast. A cast between a pointer and an integer type, or
1508    /// between a function pointer and an integer type.
1509    /// See the docs on `expose_provenance` for more details.
1510    PointerExposeProvenance,
1511    /// An address-to-pointer cast that picks up an exposed provenance.
1512    /// See the docs on `with_exposed_provenance` for more details.
1513    PointerWithExposedProvenance,
1514    /// Pointer related casts that are done by coercions. Note that reference-to-raw-ptr casts are
1515    /// translated into `&raw mut/const *r`, i.e., they are not actually casts.
1516    ///
1517    /// The following are allowed in [`AnalysisPhase::Initial`] as they're needed for borrowck,
1518    /// but after that are forbidden (including in all phases of runtime MIR):
1519    /// * [`PointerCoercion::ArrayToPointer`]
1520    /// * [`PointerCoercion::MutToConstPointer`]
1521    ///
1522    /// Both are runtime nops, so should be [`CastKind::PtrToPtr`] instead in runtime MIR.
1523    PointerCoercion(PointerCoercion, CoercionSource),
1524    IntToInt,
1525    FloatToInt,
1526    FloatToFloat,
1527    IntToFloat,
1528    PtrToPtr,
1529    FnPtrToPtr,
1530    /// Reinterpret the bits of the input as a different type.
1531    ///
1532    /// MIR is well-formed if the input and output types have different sizes,
1533    /// but running a transmute between differently-sized types is UB.
1534    ///
1535    /// Allowed only in [`MirPhase::Runtime`]; Earlier it's a [`TerminatorKind::Call`].
1536    Transmute,
1537}
1538
1539/// Represents how a [`CastKind::PointerCoercion`] was constructed.
1540/// Used only for diagnostics.
1541#[derive(Clone, Copy, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1542pub enum CoercionSource {
1543    /// The coercion was manually written by the user with an `as` cast.
1544    AsCast,
1545    /// The coercion was automatically inserted by the compiler.
1546    Implicit,
1547}
1548
1549#[derive(Clone, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1550#[derive(TypeFoldable, TypeVisitable)]
1551pub enum AggregateKind<'tcx> {
1552    /// The type is of the element
1553    Array(Ty<'tcx>),
1554    Tuple,
1555
1556    /// The second field is the variant index. It's equal to 0 for struct
1557    /// and union expressions. The last field is the
1558    /// active field number and is present only for union expressions
1559    /// -- e.g., for a union expression `SomeUnion { c: .. }`, the
1560    /// active field index would identity the field `c`
1561    Adt(DefId, VariantIdx, GenericArgsRef<'tcx>, Option<UserTypeAnnotationIndex>, Option<FieldIdx>),
1562
1563    Closure(DefId, GenericArgsRef<'tcx>),
1564    Coroutine(DefId, GenericArgsRef<'tcx>),
1565    CoroutineClosure(DefId, GenericArgsRef<'tcx>),
1566
1567    /// Construct a raw pointer from the data pointer and metadata.
1568    ///
1569    /// The `Ty` here is the type of the *pointee*, not the pointer itself.
1570    /// The `Mutability` indicates whether this produces a `*const` or `*mut`.
1571    ///
1572    /// The [`Rvalue::Aggregate`] operands for thus must be
1573    ///
1574    /// 0. A raw pointer of matching mutability with any [`core::ptr::Thin`] pointee
1575    /// 1. A value of the appropriate [`core::ptr::Pointee::Metadata`] type
1576    ///
1577    /// *Both* operands must always be included, even the unit value if this is
1578    /// creating a thin pointer. If you're just converting between thin pointers,
1579    /// you may want an [`Rvalue::Cast`] with [`CastKind::PtrToPtr`] instead.
1580    RawPtr(Ty<'tcx>, Mutability),
1581}
1582
1583#[derive(Copy, Clone, Debug, PartialEq, Eq, TyEncodable, TyDecodable, Hash, HashStable)]
1584pub enum NullOp<'tcx> {
1585    /// Returns the size of a value of that type
1586    SizeOf,
1587    /// Returns the minimum alignment of a type
1588    AlignOf,
1589    /// Returns the offset of a field
1590    OffsetOf(&'tcx List<(VariantIdx, FieldIdx)>),
1591    /// Returns whether we should perform some UB-checking at runtime.
1592    /// See the `ub_checks` intrinsic docs for details.
1593    UbChecks,
1594    /// Returns whether we should perform contract-checking at runtime.
1595    /// See the `contract_checks` intrinsic docs for details.
1596    ContractChecks,
1597}
1598
1599#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
1600#[derive(HashStable, TyEncodable, TyDecodable, TypeFoldable, TypeVisitable)]
1601pub enum UnOp {
1602    /// The `!` operator for logical inversion
1603    Not,
1604    /// The `-` operator for negation
1605    Neg,
1606    /// Gets the metadata `M` from a `*const`/`*mut`/`&`/`&mut` to
1607    /// `impl Pointee<Metadata = M>`.
1608    ///
1609    /// For example, this will give a `()` from `*const i32`, a `usize` from
1610    /// `&mut [u8]`, or a `ptr::DynMetadata<dyn Foo>` (internally a pointer)
1611    /// from a `*mut dyn Foo`.
1612    ///
1613    /// Allowed only in [`MirPhase::Runtime`]; earlier it's an intrinsic.
1614    PtrMetadata,
1615}
1616
1617#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
1618#[derive(TyEncodable, TyDecodable, HashStable, TypeFoldable, TypeVisitable)]
1619pub enum BinOp {
1620    /// The `+` operator (addition)
1621    Add,
1622    /// Like `Add`, but with UB on overflow.  (Integers only.)
1623    AddUnchecked,
1624    /// Like `Add`, but returns `(T, bool)` of both the wrapped result
1625    /// and a bool indicating whether it overflowed.
1626    AddWithOverflow,
1627    /// The `-` operator (subtraction)
1628    Sub,
1629    /// Like `Sub`, but with UB on overflow.  (Integers only.)
1630    SubUnchecked,
1631    /// Like `Sub`, but returns `(T, bool)` of both the wrapped result
1632    /// and a bool indicating whether it overflowed.
1633    SubWithOverflow,
1634    /// The `*` operator (multiplication)
1635    Mul,
1636    /// Like `Mul`, but with UB on overflow.  (Integers only.)
1637    MulUnchecked,
1638    /// Like `Mul`, but returns `(T, bool)` of both the wrapped result
1639    /// and a bool indicating whether it overflowed.
1640    MulWithOverflow,
1641    /// The `/` operator (division)
1642    ///
1643    /// For integer types, division by zero is UB, as is `MIN / -1` for signed.
1644    /// The compiler should have inserted checks prior to this.
1645    ///
1646    /// Floating-point division by zero is safe, and does not need guards.
1647    Div,
1648    /// The `%` operator (modulus)
1649    ///
1650    /// For integer types, using zero as the modulus (second operand) is UB,
1651    /// as is `MIN % -1` for signed.
1652    /// The compiler should have inserted checks prior to this.
1653    ///
1654    /// Floating-point remainder by zero is safe, and does not need guards.
1655    Rem,
1656    /// The `^` operator (bitwise xor)
1657    BitXor,
1658    /// The `&` operator (bitwise and)
1659    BitAnd,
1660    /// The `|` operator (bitwise or)
1661    BitOr,
1662    /// The `<<` operator (shift left)
1663    ///
1664    /// The offset is given by `RHS.rem_euclid(LHS::BITS)`.
1665    /// In other words, it is (uniquely) determined as follows:
1666    /// - it is "equal modulo LHS::BITS" to the RHS
1667    /// - it is in the range `0..LHS::BITS`
1668    Shl,
1669    /// Like `Shl`, but is UB if the RHS >= LHS::BITS or RHS < 0
1670    ShlUnchecked,
1671    /// The `>>` operator (shift right)
1672    ///
1673    /// The offset is given by `RHS.rem_euclid(LHS::BITS)`.
1674    /// In other words, it is (uniquely) determined as follows:
1675    /// - it is "equal modulo LHS::BITS" to the RHS
1676    /// - it is in the range `0..LHS::BITS`
1677    ///
1678    /// This is an arithmetic shift if the LHS is signed
1679    /// and a logical shift if the LHS is unsigned.
1680    Shr,
1681    /// Like `Shl`, but is UB if the RHS >= LHS::BITS or RHS < 0
1682    ShrUnchecked,
1683    /// The `==` operator (equality)
1684    Eq,
1685    /// The `<` operator (less than)
1686    Lt,
1687    /// The `<=` operator (less than or equal to)
1688    Le,
1689    /// The `!=` operator (not equal to)
1690    Ne,
1691    /// The `>=` operator (greater than or equal to)
1692    Ge,
1693    /// The `>` operator (greater than)
1694    Gt,
1695    /// The `<=>` operator (three-way comparison, like `Ord::cmp`)
1696    ///
1697    /// This is supported only on the integer types and `char`, always returning
1698    /// [`rustc_hir::LangItem::OrderingEnum`] (aka [`std::cmp::Ordering`]).
1699    ///
1700    /// [`Rvalue::BinaryOp`]`(BinOp::Cmp, A, B)` returns
1701    /// - `Ordering::Less` (`-1_i8`, as a Scalar) if `A < B`
1702    /// - `Ordering::Equal` (`0_i8`, as a Scalar) if `A == B`
1703    /// - `Ordering::Greater` (`+1_i8`, as a Scalar) if `A > B`
1704    Cmp,
1705    /// The `ptr.offset` operator
1706    Offset,
1707}
1708
1709// Assignment operators, e.g. `+=`. See comments on the corresponding variants
1710// in `BinOp` for details.
1711#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, HashStable)]
1712pub enum AssignOp {
1713    AddAssign,
1714    SubAssign,
1715    MulAssign,
1716    DivAssign,
1717    RemAssign,
1718    BitXorAssign,
1719    BitAndAssign,
1720    BitOrAssign,
1721    ShlAssign,
1722    ShrAssign,
1723}
1724
1725// Sometimes `BinOp` and `AssignOp` need the same treatment. The operations
1726// covered by `AssignOp` are a subset of those covered by `BinOp`, so it makes
1727// sense to convert `AssignOp` to `BinOp`.
1728impl From<AssignOp> for BinOp {
1729    fn from(op: AssignOp) -> BinOp {
1730        match op {
1731            AssignOp::AddAssign => BinOp::Add,
1732            AssignOp::SubAssign => BinOp::Sub,
1733            AssignOp::MulAssign => BinOp::Mul,
1734            AssignOp::DivAssign => BinOp::Div,
1735            AssignOp::RemAssign => BinOp::Rem,
1736            AssignOp::BitXorAssign => BinOp::BitXor,
1737            AssignOp::BitAndAssign => BinOp::BitAnd,
1738            AssignOp::BitOrAssign => BinOp::BitOr,
1739            AssignOp::ShlAssign => BinOp::Shl,
1740            AssignOp::ShrAssign => BinOp::Shr,
1741        }
1742    }
1743}
1744
1745// Some nodes are used a lot. Make sure they don't unintentionally get bigger.
1746#[cfg(target_pointer_width = "64")]
1747mod size_asserts {
1748    use rustc_data_structures::static_assert_size;
1749
1750    use super::*;
1751    // tidy-alphabetical-start
1752    static_assert_size!(AggregateKind<'_>, 32);
1753    static_assert_size!(Operand<'_>, 24);
1754    static_assert_size!(Place<'_>, 16);
1755    static_assert_size!(PlaceElem<'_>, 24);
1756    static_assert_size!(Rvalue<'_>, 40);
1757    static_assert_size!(StatementKind<'_>, 16);
1758    static_assert_size!(TerminatorKind<'_>, 80);
1759    // tidy-alphabetical-end
1760}