Cranelift: add debug tag infrastructure.

cranelift/codegen/meta/src/shared/instructions.rs

@@ -3902,4 +3902,20 @@ pub(crate) fn define(
             Operand::new("a", &TxN.dynamic_to_vector()).with_doc("New fixed vector"),
         ]),
     );
+
+    ig.push(
+        Inst::new(
+            "sequence_point",
+            r#"
+         A compiler barrier that acts as an immovable marker from IR input to machine-code output.
+
+         This "sequence point" can have debug tags attached to it, and these tags will be
+         noted in the output `MachBuffer`.
+
+         It prevents motion of any other side-effects across this boundary.
+         "#,
+            &formats.nullary,
+        )
+        .other_side_effects(),
+    );
 }

cranelift/codegen/src/inline.rs

@@ -20,7 +20,7 @@
 //! Cranelift the body of the callee that is to be inlined.
 
 use crate::cursor::{Cursor as _, FuncCursor};
-use crate::ir::{self, ExceptionTableData, ExceptionTableItem, InstBuilder as _};
+use crate::ir::{self, DebugTag, ExceptionTableData, ExceptionTableItem, InstBuilder as _};
 use crate::result::CodegenResult;
 use crate::trace;
 use crate::traversals::Dfs;
@@ -366,6 +366,13 @@ fn inline_one(
     // callee.
     let mut last_inlined_block = inline_block_layout(func, call_block, callee, &entity_map);
 
+    // Get a copy of debug tags on the call instruction; these are
+    // prepended to debug tags on inlined instructions. Remove them
+    // from the call itself as it will be rewritten to a jump (which
+    // cannot have tags).
+    let call_debug_tags = func.debug_tags.get(call_inst).to_vec();
+    func.debug_tags.set(call_inst, []);
+
     // Translate each instruction from the callee into the caller,
     // appending them to their associated block in the caller.
     //
@@ -403,6 +410,29 @@ fn inline_one(
             let inlined_inst = func.dfg.make_inst(inlined_inst_data);
             func.layout.append_inst(inlined_inst, inlined_block);
 
+            // Copy over debug tags, translating referenced entities
+            // as appropriate.
+            let debug_tags = callee.debug_tags.get(callee_inst);
+            // If there are tags on the inlined instruction, we always
+            // add tags, and we prepend any tags from the call
+            // instruction; but we don't add tags if only the callsite
+            // had them (this would otherwise mean that every single
+            // instruction in an inlined function body would get
+            // tags).
+            if !debug_tags.is_empty() {
+                let tags = call_debug_tags
+                    .iter()
+                    .cloned()
+                    .chain(debug_tags.iter().map(|tag| match *tag {
+                        DebugTag::User(value) => DebugTag::User(value),
+                        DebugTag::StackSlot(slot) => {
+                            DebugTag::StackSlot(entity_map.inlined_stack_slot(slot))
+                        }
+                    }))
+                    .collect::<SmallVec<[_; 4]>>();
+                func.debug_tags.set(inlined_inst, tags);
+            }
+
             let opcode = callee.dfg.insts[callee_inst].opcode();
             if opcode.is_return() {
                 // Instructions that return do not define any values, so we

cranelift/codegen/src/inst_predicates.rs

@@ -147,7 +147,8 @@ pub fn has_memory_fence_semantics(op: Opcode) -> bool {
         | Opcode::AtomicLoad
         | Opcode::AtomicStore
         | Opcode::Fence
-        | Opcode::Debugtrap => true,
+        | Opcode::Debugtrap
+        | Opcode::SequencePoint => true,
         Opcode::Call | Opcode::CallIndirect | Opcode::TryCall | Opcode::TryCallIndirect => true,
         op if op.can_trap() => true,
         _ => false,

cranelift/codegen/src/ir/debug_tags.rs

@@ -0,0 +1,141 @@
+//! Debug tag storage.
+//!
+//! Cranelift permits the embedder to place "debug tags" on
+//! instructions in CLIF. These tags are sequences of items of various
+//! kinds, with no other meaning imposed by Cranelift. They are passed
+//! through to metadata provided alongside the compilation result.
+//!
+//! When Cranelift inlines a function, it will prepend any tags from
+//! the call instruction at the inlining callsite to tags on all
+//! inlined instructions.
+//!
+//! These tags can be used, for example, to identify stackslots that
+//! store user state, or to denote positions in user source. In
+//! general, the intent is to allow perfect reconstruction of original
+//! (source-level) program state in an instrumentation-based
+//! debug-info scheme, as long as the instruction(s) on which these
+//! tags are attached are preserved. This will be the case for any
+//! instructions with side-effects.
+//!
+//! A few answers to design questions that lead to this design:
+//!
+//! - Why not use the SourceLoc mechanism? Debug tags are richer than
+//!   that infrastructure because they preserve inlining location and
+//!   are interleaved properly with any other tags describing the
+//!   frame.
+//! - Why not attach debug tags only to special sequence-point
+//!   instructions? This is driven by inlining: we should have the
+//!   semantic information about a callsite attached directly to the
+//!   call and observe it there, not have a magic "look backward to
+//!   find a sequence point" behavior in the inliner.
+//!
+//! In other words, the needs of preserving "virtual" frames across an
+//! inlining transform drive this design.
+
+use crate::ir::{Inst, StackSlot};
+use alloc::collections::BTreeMap;
+use alloc::vec::Vec;
+use core::ops::Range;
+
+/// Debug tags for instructions.
+#[derive(Clone, PartialEq, Hash, Default)]
+#[cfg_attr(
+    feature = "enable-serde",
+    derive(serde_derive::Serialize, serde_derive::Deserialize)
+)]
+pub struct DebugTags {
+    /// Pool of tags, referred to by `insts` below.
+    tags: Vec<DebugTag>,
+
+    /// Per-instruction range for its list of tags in the tag pool (if
+    /// any).
+    ///
+    /// Note: we don't use `PackedOption` and `EntityList` here
+    /// because the values that we are storing are not entities.
+    insts: BTreeMap<Inst, Range<u32>>,
+}
+
+/// One debug tag.
+#[derive(Clone, Debug, PartialEq, Hash)]
+#[cfg_attr(
+    feature = "enable-serde",
+    derive(serde_derive::Serialize, serde_derive::Deserialize)
+)]
+pub enum DebugTag {
+    /// User-specified `u32` value, opaque to Cranelift.
+    User(u32),
+
+    /// A stack slot reference.
+    StackSlot(StackSlot),
+}
+
+impl DebugTags {
+    /// Set the tags on an instruction, overwriting existing tag list.
+    ///
+    /// Tags can only be set on call instructions (those for which
+    /// [`crate::Opcode::is_call()`] returns `true`) and on
+    /// `sequence_point` instructions. This property is checked by the
+    /// CLIF verifier.
+    pub fn set(&mut self, inst: Inst, tags: impl IntoIterator<Item = DebugTag>) {
+        let start = u32::try_from(self.tags.len()).unwrap();
+        self.tags.extend(tags);
+        let end = u32::try_from(self.tags.len()).unwrap();
+        if end > start {
+            self.insts.insert(inst, start..end);
+        } else {
+            self.insts.remove(&inst);
+        }
+    }
+
+    /// Get the tags associated with an instruction.
+    pub fn get(&self, inst: Inst) -> &[DebugTag] {
+        if let Some(range) = self.insts.get(&inst) {
+            let start = usize::try_from(range.start).unwrap();
+            let end = usize::try_from(range.end).unwrap();
+            &self.tags[start..end]
+        } else {
+            &[]
+        }
+    }
+
+    /// Does the given instruction have any tags?
+    pub fn has(&self, inst: Inst) -> bool {
+        // We rely on the invariant that an entry in the map is
+        // present only if the list range is non-empty.
+        self.insts.contains_key(&inst)
+    }
+
+    /// Clone the tags from one instruction to another.
+    ///
+    /// This clone is cheap (references the same underlying storage)
+    /// because the tag lists are immutable.
+    pub fn clone_tags(&mut self, from: Inst, to: Inst) {
+        if let Some(range) = self.insts.get(&from).cloned() {
+            self.insts.insert(to, range);
+        } else {
+            self.insts.remove(&to);
+        }
+    }
+
+    /// Are any debug tags present?
+    ///
+    /// This is used for adjusting margins when pretty-printing CLIF.
+    pub fn is_empty(&self) -> bool {
+        self.insts.is_empty()
+    }
+
+    /// Clear all tags.
+    pub fn clear(&mut self) {
+        self.insts.clear();
+        self.tags.clear();
+    }
+}
+
+impl core::fmt::Display for DebugTag {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        match self {
+            DebugTag::User(value) => write!(f, "{value}"),
+            DebugTag::StackSlot(slot) => write!(f, "{slot}"),
+        }
+    }
+}

cranelift/codegen/src/ir/function.rs

@@ -5,6 +5,7 @@
 
 use crate::HashMap;
 use crate::entity::{PrimaryMap, SecondaryMap};
+use crate::ir::DebugTags;
 use crate::ir::{
     self, Block, DataFlowGraph, DynamicStackSlot, DynamicStackSlotData, DynamicStackSlots,
     DynamicType, ExtFuncData, FuncRef, GlobalValue, GlobalValueData, Inst, JumpTable,
@@ -190,6 +191,22 @@ pub struct FunctionStencil {
     /// interpreted by Cranelift, only preserved.
     pub srclocs: SourceLocs,
 
+    /// Opaque debug-info tags on sequence-point and call
+    /// instructions.
+    ///
+    /// These tags are not interpreted by Cranelift, and are passed
+    /// through to compilation-result metadata. The only semantic
+    /// structure that Cranelift imposes is that when inlining, it
+    /// prepends the callsite call instruction's tags to the tags on
+    /// inlined instructions.
+    ///
+    /// In order to ensure clarity around guaranteed compiler
+    /// behavior, tags are only permitted on instructions whose
+    /// presence and sequence will remain the same in the compiled
+    /// output: namely, `sequence_point` instructions and ordinary
+    /// call instructions.
+    pub debug_tags: DebugTags,
+
     /// An optional global value which represents an expression evaluating to
     /// the stack limit for this function. This `GlobalValue` will be
     /// interpreted in the prologue, if necessary, to insert a stack check to
@@ -209,6 +226,7 @@ impl FunctionStencil {
         self.dfg.clear();
         self.layout.clear();
         self.srclocs.clear();
+        self.debug_tags.clear();
         self.stack_limit = None;
     }
 
@@ -408,6 +426,7 @@ impl Function {
                 layout: Layout::new(),
                 srclocs: SecondaryMap::new(),
                 stack_limit: None,
+                debug_tags: DebugTags::default(),
             },
             params: FunctionParameters::new(),
         }

cranelift/codegen/src/ir/mod.rs

@@ -4,6 +4,7 @@ mod atomic_rmw_op;
 mod builder;
 pub mod condcodes;
 pub mod constant;
+mod debug_tags;
 pub mod dfg;
 pub mod dynamic_type;
 pub mod entities;
@@ -36,6 +37,7 @@ pub use crate::ir::builder::{
     InsertBuilder, InstBuilder, InstBuilderBase, InstInserterBase, ReplaceBuilder,
 };
 pub use crate::ir::constant::{ConstantData, ConstantPool};
+pub use crate::ir::debug_tags::{DebugTag, DebugTags};
 pub use crate::ir::dfg::{BlockData, DataFlowGraph, ValueDef};
 pub use crate::ir::dynamic_type::{DynamicTypeData, DynamicTypes, dynamic_to_fixed};
 pub use crate::ir::entities::{
@@ -64,7 +66,7 @@ pub use crate::ir::progpoint::ProgramPoint;
 pub use crate::ir::sourceloc::RelSourceLoc;
 pub use crate::ir::sourceloc::SourceLoc;
 pub use crate::ir::stackslot::{
-    DynamicStackSlotData, DynamicStackSlots, StackSlotData, StackSlotKind, StackSlots,
+    DynamicStackSlotData, DynamicStackSlots, StackSlotData, StackSlotKey, StackSlotKind, StackSlots,
 };
 pub use crate::ir::trapcode::TrapCode;
 pub use crate::ir::types::Type;

cranelift/codegen/src/ir/stackslot.rs

@@ -69,6 +69,37 @@ pub struct StackSlotData {
     /// be aligned according to other considerations, such as minimum
     /// stack slot size or machine word size, as well.
     pub align_shift: u8,
+
+    /// Opaque stackslot metadata handle, passed through to
+    /// compilation result metadata describing stackslot location.
+    ///
+    /// In the face of compiler transforms like inlining that may move
+    /// stackslots between functions, when an embedder wants to
+    /// externally observe stackslots, it needs a first-class way for
+    /// the identity of stackslots to be carried along with the IR
+    /// entities. This opaque `StackSlotKey` allows the embedder to do
+    /// so.
+    pub key: Option<StackSlotKey>,
+}
+
+/// An opaque key uniquely identifying a stack slot.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
+pub struct StackSlotKey(u64);
+impl StackSlotKey {
+    /// Construct a [`StackSlotKey`] from raw bits.
+    ///
+    /// An embedder can use any 64-bit value to describe a stack slot;
+    /// there are no restrictions, and the value does not mean
+    /// anything to Cranelift itself.
+    pub fn new(value: u64) -> StackSlotKey {
+        StackSlotKey(value)
+    }
+
+    /// Get the raw bits from the [`StackSlotKey`].
+    pub fn bits(&self) -> u64 {
+        self.0
+    }
 }
 
 impl StackSlotData {
@@ -78,23 +109,40 @@ impl StackSlotData {
             kind,
             size,
             align_shift,
+            key: None,
+        }
+    }
+
+    /// Create a stack slot with the specified byte size and alignment
+    /// and the given user-defined key.
+    pub fn new_with_key(
+        kind: StackSlotKind,
+        size: StackSize,
+        align_shift: u8,
+        key: StackSlotKey,
+    ) -> Self {
+        Self {
+            kind,
+            size,
+            align_shift,
+            key: Some(key),
         }
     }
 }
 
 impl fmt::Display for StackSlotData {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        if self.align_shift != 0 {
-            write!(
-                f,
-                "{} {}, align = {}",
-                self.kind,
-                self.size,
-                1u32 << self.align_shift
-            )
+        let align_shift = if self.align_shift != 0 {
+            format!(", align = {}", 1u32 << self.align_shift)
         } else {
-            write!(f, "{} {}", self.kind, self.size)
-        }
+            "".into()
+        };
+        let key = match self.key {
+            Some(value) => format!(", key = {}", value.bits()),
+            None => "".into(),
+        };
+
+        write!(f, "{} {}{align_shift}{key}", self.kind, self.size)
     }
 }