[DebugInfo][RemoveDIs] Add new behind-the-scenes plumbing for debug-info

This is the "central" patch to the removing-debug-intrinsics project: it
changes the instruction movement APIs (insert, move, splice) to interpret
the "Head" bits we're attaching to BasicBlock::iterators, and updates
debug-info records in the background to preserve the ordering of debug-info
(which is in DPValue objects instead of dbg.values). The cost is the
complexity of this patch, plus memory. The benefit is that LLVM developers
can cease thinking about whether they're moving debug-info or not, because
it'll happen behind the scenes.

All that complexity appears in BasicBlock::spliceDebugInfo, see the diagram
there for how we now manually shuffle debug-info around. Each potential
splice configuration gets tested in the added unit tests.

The rest of this patch applies the same reasoning in a variety of
scenarios. When moveBefore (and it's siblings) are used to move
instructions around, the caller has to indicate whether they intend for
debug-info to move too (is it a "Preserving" call or not), and then the
"Head" bits used to determine where debug-info moves to. Similar reasoning
is needed for insertBefore.

Differential Revision: https://reviews.llvm.org/D154353

Author: jmorse

llvm/include/llvm/IR/BasicBlock.h

@@ -19,6 +19,7 @@
 #include "llvm/ADT/ilist_node.h"
 #include "llvm/ADT/iterator.h"
 #include "llvm/ADT/iterator_range.h"
+#include "llvm/IR/DebugProgramInstruction.h"
 #include "llvm/IR/Instruction.h"
 #include "llvm/IR/DebugProgramInstruction.h"
 #include "llvm/IR/SymbolTableListTraits.h"
@@ -118,6 +119,28 @@ class BasicBlock final : public Value, // Basic blocks are data objects also
 
   void dumpDbgValues() const;
 
+  /// Return the DPMarker for the position given by \p It, so that DPValues can
+  /// be inserted there. This will either be nullptr if not present, a DPMarker,
+  /// or TrailingDPValues if It is end().
+  DPMarker *getMarker(InstListType::iterator It);
+
+  /// Return the DPMarker for the position that comes after \p I. \see
+  /// BasicBlock::getMarker, this can be nullptr, a DPMarker, or
+  /// TrailingDPValues if there is no next instruction.
+  DPMarker *getNextMarker(Instruction *I);
+
+  /// Insert a DPValue into a block at the position given by \p I.
+  void insertDPValueAfter(DPValue *DPV, Instruction *I);
+
+  /// Insert a DPValue into a block at the position given by \p Here.
+  void insertDPValueBefore(DPValue *DPV, InstListType::iterator Here);
+
+  /// Eject any debug-info trailing at the end of a block. DPValues can
+  /// transiently be located "off the end" of a block if the blocks terminator
+  /// is temporarily removed. Once a terminator is re-inserted this method will
+  /// move such DPValues back to the right place (ahead of the terminator).
+  void flushTerminatorDbgValues();
+
 private:
   void setParent(Function *parent);
 
@@ -154,6 +177,19 @@ class BasicBlock final : public Value, // Basic blocks are data objects also
   friend class llvm::ilist_node_with_parent<llvm::Instruction, llvm::BasicBlock,
                                             ilist_iterator_bits<true>>;
 
+  // Friendly methods that need to access us for the maintenence of
+  // debug-info attachments.
+  friend void Instruction::insertBefore(BasicBlock::iterator InsertPos);
+  friend void Instruction::insertAfter(Instruction *InsertPos);
+  friend void Instruction::insertBefore(BasicBlock &BB,
+                                        InstListType::iterator InsertPos);
+  friend void Instruction::moveBeforeImpl(BasicBlock &BB,
+                                          InstListType::iterator I,
+                                          bool Preserve);
+  friend iterator_range<DPValue::self_iterator> Instruction::cloneDebugInfoFrom(
+      const Instruction *From, std::optional<DPValue::self_iterator> FromHere,
+      bool InsertAtHead);
+
   /// Creates a new BasicBlock.
   ///
   /// If the Parent parameter is specified, the basic block is automatically
@@ -478,6 +514,21 @@ class BasicBlock final : public Value, // Basic blocks are data objects also
     return &BasicBlock::InstList;
   }
 
+  /// Dedicated function for splicing debug-info: when we have an empty
+  /// splice (i.e. zero instructions), the caller may still intend any
+  /// debug-info in between the two "positions" to be spliced.
+  void spliceDebugInfoEmptyBlock(BasicBlock::iterator ToIt, BasicBlock *FromBB,
+                                 BasicBlock::iterator FromBeginIt,
+                                 BasicBlock::iterator FromEndIt);
+
+  /// Perform any debug-info specific maintenence for the given splice
+  /// activity. In the DPValue debug-info representation, debug-info is not
+  /// in instructions, and so it does not automatically move from one block
+  /// to another.
+  void spliceDebugInfo(BasicBlock::iterator ToIt, BasicBlock *FromBB,
+                       BasicBlock::iterator FromBeginIt,
+                       BasicBlock::iterator FromEndIt);
+
 public:
   /// Returns a pointer to the symbol table if one exists.
   ValueSymbolTable *getValueSymbolTable();

llvm/include/llvm/IR/Instruction.h

@@ -59,6 +59,38 @@ class Instruction : public User,
   /// debugging information present.
   DPMarker *DbgMarker = nullptr;
 
+  /// Clone any debug-info attached to \p From onto this instruction. Used to
+  /// copy debugging information from one block to another, when copying entire
+  /// blocks. \see DebugProgramInstruction.h , because the ordering of DPValues
+  /// is still important, fine grain control of which instructions are moved and
+  /// where they go is necessary.
+  /// \p From The instruction to clone debug-info from.
+  /// \p from_here Optional iterator to limit DPValues cloned to be a range from
+  ///    from_here to end().
+  /// \p InsertAtHead Whether the cloned DPValues should be placed at the end
+  ///    or the beginning of existing DPValues attached to this.
+  /// \returns A range over the newly cloned DPValues.
+  iterator_range<simple_ilist<DPValue>::iterator> cloneDebugInfoFrom(
+      const Instruction *From,
+      std::optional<simple_ilist<DPValue>::iterator> FromHere = std::nullopt,
+      bool InsertAtHead = false);
+
+  /// Return a range over the DPValues attached to this instruction.
+  iterator_range<simple_ilist<DPValue>::iterator> getDbgValueRange() const;
+
+  /// Returns true if any DPValues are attached to this instruction.
+  bool hasDbgValues() const;
+
+  /// Erase any DPValues attached to this instruction.
+  void dropDbgValues();
+
+  /// Erase a single DPValue \p I that is attached to this instruction.
+  void dropOneDbgValue(DPValue *I);
+
+  /// Handle the debug-info implications of this instruction being removed. Any
+  /// attached DPValues need to "fall" down onto the next instruction.
+  void handleMarkerRemoval();
+
 protected:
   // The 15 first bits of `Value::SubclassData` are available for subclasses of
   // `Instruction` to use.
@@ -135,9 +167,7 @@ class Instruction : public User,
   /// Insert an unlinked instruction into a basic block immediately before
   /// the specified instruction.
   void insertBefore(Instruction *InsertPos);
-  void insertBefore(InstListType::iterator InsertPos) {
-    insertBefore(&*InsertPos);
-  }
+  void insertBefore(InstListType::iterator InsertPos);
 
   /// Insert an unlinked instruction into a basic block immediately after the
   /// specified instruction.
@@ -148,9 +178,7 @@ class Instruction : public User,
   InstListType::iterator insertInto(BasicBlock *ParentBB,
                                     InstListType::iterator It);
 
-  void insertBefore(BasicBlock &BB, InstListType::iterator InsertPos) {
-    insertInto(&BB, InsertPos);
-  }
+  void insertBefore(BasicBlock &BB, InstListType::iterator InsertPos);
 
   /// Unlink this instruction from its current basic block and insert it into
   /// the basic block that MovePos lives in, right before MovePos.
@@ -161,28 +189,28 @@ class Instruction : public User,
   /// means that any adjacent debug-info should move with this instruction.
   /// This method is currently a no-op placeholder, but it will become meaningful
   /// when the "RemoveDIs" project is enabled.
-  void moveBeforePreserving(Instruction *MovePos) {
-    moveBefore(MovePos);
-  }
+  void moveBeforePreserving(Instruction *MovePos);
 
+private:
+  /// RemoveDIs project: all other moves implemented with this method,
+  /// centralising debug-info updates into one place.
+  void moveBeforeImpl(BasicBlock &BB, InstListType::iterator I, bool Preserve);
+
+public:
   /// Unlink this instruction and insert into BB before I.
   ///
   /// \pre I is a valid iterator into BB.
   void moveBefore(BasicBlock &BB, InstListType::iterator I);
 
   /// (See other overload for moveBeforePreserving).
-  void moveBeforePreserving(BasicBlock &BB, InstListType::iterator I) {
-    moveBefore(BB, I);
-  }
+  void moveBeforePreserving(BasicBlock &BB, InstListType::iterator I);
 
   /// Unlink this instruction from its current basic block and insert it into
   /// the basic block that MovePos lives in, right after MovePos.
   void moveAfter(Instruction *MovePos);
 
   /// See \ref moveBeforePreserving .
-  void moveAfterPreserving(Instruction *MovePos) {
-    moveAfter(MovePos);
-  }
+  void moveAfterPreserving(Instruction *MovePos);
 
   /// Given an instruction Other in the same basic block as this instruction,
   /// return true if this instruction comes before Other. In this worst case,