[DebugInfo][RemoveDIs] Add prototype storage classes for non-instruction variable debug-info

[jmorse]

Summary

Here's a patch that adds the basic storage for non-instruction variable location information. This has the potential to be very exciting, but only in the future: this implementation is deliberately na\"ive, implementing a base level of functionality. We're not looking to make debug-info super fast in this specific patch series.

Additionally, it also has a "rough" surface area because there's one artefact that we haven't managed to polish out yet: the total order of debug records, i.e. the fact that blocks of dbg.values in a block have a meaningful order and can affect each other. Eliminating that is tied in with future storage optimisations, so we haven't tried to eliminate that yet. There are only roughly five places in LLVM that really need to care about this (see future patches).

Hopefully the file-level comment in the added files and other docucomments are sufficient to piece together what's happening here: dbg.values are represented by DPValues, with their position stored in a DPMarker, which is then attached to an instruction. DPValues attempt to look as much like a DbgValueInst as possible, having most of the same accessors, the primary difference with them is that they're not an Instruction and don't exist in the Value hierachy. DPMarkers exist as a connection to the Instruction that is the position of the DPValue in a block, and to provide various utility methods for shuffling DPValues around. These are exercised in the DebugInfoTest.cpp unit test added.

Because a DPValue is neither metadata nor a Value, but still needs to refer to ValueAsMetadata objects wrapping instructions and things in the Value hierachy, we need to plumb DPValues into the metadata-lookup facilities. This is so that we can later query "give me all the DPValues referring to this Value", in the same way that you can do that for dbg.values. It's also needed so that when a Value gets RAUW'd, all the metadata-connected users get told about it: see the added unit test in LocalTest.cpp

This patch is probably the correct place to talk about two significant storage changes:

• Instructions will gain another pointer in their body, pointing at an optional DPMarker. This is a noteworthy cost because it affects non-debuginfo builds. I also think it's unavoidable, we need to store precise positions for debug-info and access them from an instruction quickly. This is a trade-off: more memory in normal builds contributes to faster -g builds, in the same way that there's a DebugLoc in class Instruction already.
• Blocks will gain a "TrailingDPValues" object, essentially a list of "dangling" DPValues for when blocks transiently don't have a terminator. Again, this inflates the size of a data structure; again, I don't think this is avoidable. Removing the terminator from a block is a legitimate operation, and we still require a location for debug-info in those circumstances.

Naming: note that the files added are named "DebugProgramInstruction", and other classes prefixed "DP". This is because we originally prototyped all of this as a "shadow" list in a block, effectively a "debug program" behind the real program. We've since moved on from that, but there are still a few names baked in, and I can't for the life of me come up with anything better right now. Suggestions welcome!

Looking back over this, we should be using a unique_ptr to store the pointer references being added, but I'm a bit to burnt out to fix that right now; coming in a future revision!

[Orlando]

I started reviewing this but didn't have time to finish it. For fear of losing my comments I'll post what I've got so far. Note to self: start at Instruction.h.

llvm/include/llvm/IR/BasicBlock.h

65

How frequently do we expect TrailingDPValues to be used? Is it worth having this heap allocated instead to save some bits?

llvm/include/llvm/IR/DebugProgramInstruction.h

46

Comment SGTM

83

nit: LLVM's

113–115

Looks like these fields have 'getters' already - should they be private? Or, if they don't change after ctor we could make them const instead.

212

nit: we changed DbgVariableIntrinsic's get/setUndef to get/setKillLocation - IMO it'd be better to keep the names consistent here.

330

TODO? Or can this comment be removed?

343

nit: Chrome's built in spell check says gnarlyness isn't a word, but it also doesn't think the result from Googling it, gnarliness, is either, so I don't know what to believe.

[Orlando]

Code changes LGTM pending inline comments. I haven't looked at the tests yet.

llvm/include/llvm/IR/DebugProgramInstruction.h

119

Looking at the constructor definition (and the parameter type), this comment is possibly out of date? DVI is not necessarily a dbg.value.

122–123

Might be worth mentioning something about assuming this is a dbg.value?

345

from_here -> FromHere?
Froms -> From's

llvm/include/llvm/IR/Instruction.h

56–58

Not sure about "happens" but can't come up with anything better myself. For debugging information that takes effect before this instruction? For variable locations that start before this instruction? I'll leave it with you, feel free to ignore this.

llvm/include/llvm/IR/Metadata.h

220

///////////

272

///////////

llvm/lib/IR/DebugInfoMetadata.cpp

2107–2115

Please could you explain this change to me (why/what it's doing)? It seems the couple of months I've not touched metadata have clouded my memory.

llvm/lib/IR/DebugProgramInstruction.cpp

23

Can we drop these braces? IMO they are just a bit of added clutter here but YMMV, feel free to ignore.

41–43

Any reason Type isn't initialized in the member initializer list like the other fields? And is it right to assume LocationType::Value?

64

IMO worth asserting this, since metadata tends to be tricksy. wdyt?

181

(personal preference nit: unnecessary braces, ymmv, feel free to ignore)

271

I think this line is redundant (eraseFromParent -> removeFromParent -> MarkedInstr->DbgMarker = nullptr?).

272

nit: Unnecessary return

329

Why reverse here? (And if it's not needed, can the fors be merged with a conditional insert pos?)

llvm/lib/IR/Metadata.cpp

412

nit: unnecessary braces, same below.

[Orlando]

LGTM once inline comments have been addressed

llvm/unittests/IR/DebugInfoTest.cpp

773

clang-format

818–821

Is there an API for handling this behind the scenes by adding DPValues to instructions? If not, why not, if yes, please can we test that too?

[jmorse]

llvm/include/llvm/IR/BasicBlock.h

65

Yuh; in fact, given that this is a transitory state that crops up rarely, we can probably put a map in Function rather than making every block pay a penalty.

llvm/lib/IR/DebugInfoMetadata.cpp

2107–2115

I...... can't remember. Or at least, I think this comes from the work @StephenTozer did on these patches, and this deep into the metadata is out of my zone of comfort too. Any opinion on this Stephen?

I'll also see if we can just delete it.

[jmorse]

Implement review feedback from Orlando.

[Orlando]

New changes LGTM. There are still a few outstanding questions to look at (including the inline question for @StephenTozer) so I'll hold off on Accepting just yet.

llvm/include/llvm/IR/BasicBlock.h

65

SGTM, IMO it's ok to put that change in another patch if it makes things easier, since this does already all work and has been performance tested etc.

llvm/lib/IR/DebugProgramInstruction.cpp

329

ping

llvm/unittests/IR/DebugInfoTest.cpp

818–821

ping

[jmorse]

(Missed inline comments being submitted...)

llvm/include/llvm/IR/DebugProgramInstruction.h

113–115

Shifted them up to the "private" area of the class

llvm/lib/IR/DebugInfoMetadata.cpp

2107–2115

Giving this another eyeball -- previously all DIArgList's have been referred to through a single MetadataAsValue object which (AFAIUI) could be directly looked up, and whenever an operand changed that single MAV/DIArgList gets rewritten and re-uniqueified. Which is fine because with only one reference to that Metadata, it's like being RAUW'd.

However with the DebugValueUser changes in Metadata.cpp here, we're tolerating replaceable metadata references to ValueAsMetadata's and DIArgLists -- instead of funnelling connections from the Value hierarchy to the Metadata hierarchy through a VAM/MAV pair there's a web of connections. Thus, now when an operand to a DIArgList changes, we have to go through all the DPValues that refer to this DIArgList and redirect them to the new one. That means the code here changes from "this Metadata object now means something different" to "rewrite all the users to point at this new object".

Is it a good idea to use this web of connections instead of the funnel? That's something we can model/measure at a later date seeing how DPValues are going to be using it a lot.

llvm/unittests/IR/DebugInfoTest.cpp

818–821

There is one coming in D154353, just this is the order that it made sense to stage the patches (insert shrugging emoticon here). Alright if we patch this up later?

[Orlando]

LGTM

llvm/lib/IR/DebugInfoMetadata.cpp

2107–2115

Ok, tyvm for the explanation.

llvm/lib/IR/DebugProgramInstruction.cpp

329

Ah I've got it - if InsertAtHead then prepend, otherwise append.

llvm/unittests/IR/DebugInfoTest.cpp

818–821

SGTM

[jmorse]

Sitrep on the TrailingDPValues situation -- we had a chat offline, and this is sort of a leftover from an earlier prototype where all DPValues were in a "shadow" list that existed behind the main instruction-list, and had a total order on them. TrailingPDValues was the "end" of that list. The model we've ended up with doesn't have that total order (because collections of DPValues are split between instructions) but we still use TrailingDPValues to pretend it is, so there's a bit of extra reshuffling that has to happen.

Long story short, I'm going to shift storage of any DPValues that dangle while we remove/add terminators into LLVMContext, as it's effectively temporary global data that we want to hide from the usual instruction APIs, and it doesn't make sense to allocate it into every block or function.

[jmorse]

Here's a revised patch -- I've shifted the location of the TrailingDPValues data structure into LLVMContextImpl, as it seems we only ever have one or two blocks with trailing DPValues at a time. It doesn't make sense to bloat BasicBlock with a dedicated field for a special case. I'm planning on plumbing this through BasicBlock, as a result the relevant useful methods turn up in the next patch (D154080), so I've left an llvm_unreachable in DPMarker::removeMarker until that lands.

I've also shoved an assertion in LLVMContext that checks whether any DPValues get accidentally left in TrailingDPValues for the lifetime of the LLVMContext. The only scenario where I think that can happen is where someone erases a terminator and then destroys the LLVMContext? It's sort of awkward behaviour, however I think in most scenarios if you leave a datastructure in an illegal state and try to clean it up gracefully, you'll run into issues anyway.

The confusing pair of loops in DPMarker::cloneDebugInfoFrom have also been refactored as a I realised they can just be a single one, and I've added some comments.

Finally, I've noticed that this patch won't build independently as there are some forward declarations of stuff that doesn't have a definition, that later needs a definition -- this is due to the shifting sands of this patch series. I could jam in various shims to make it work; or I could just land the next patch at the same time, which works fine. I think that's a reasonable approach as these were only split up to make review easier anyway.

[jmorse]

Other bits and pieces that have changed, now that I look at the history-diff:

• setTailCall() is called on DPValues that are converted back to dbg.values. This is consistent with the rest of LLVM.
• I've added a global static DPMarker with an empty StoredDPValues field, so that we can always produce a legitimate, empty range of DPValues in the added getEmptyDPValueRange, from methods where there's no debug-info.

The latter is another case of patch shuffling. This prototype as it stands is going to always allocate one DPMarker per instruction, but a later patch is going to optimise that to reduce the number of memory allocations. As a result there are going to be (in the future) scenarios where we need to describe empty ranges of DPValues, but there's no DPMarker to do that with, hence the static one. It just happened to end up in this particular patch.

[Orlando]

LGTM + a few comments

Finally, I've noticed that this patch won't build independently as there are some forward declarations of stuff that doesn't have a definition, that later needs a definition -- this is due to the shifting sands of this patch series. I could jam in various shims to make it work; or I could just land the next patch at the same time, which works fine. I think that's a reasonable approach as these were only split up to make review easier anyway.

If the two commits can't be easily separated, perhaps better to squash them? YMMV.

llvm/include/llvm/IR/DebugProgramInstruction.h

369

This will bite us if someone tries to insert a DPValue in that range

Is there no way to create an empty range without an object to grab iterators from?

If not, you could return make_range(EmptyDPMarker.StoredDPValues.end(), EmptyDPMarker.StoredDPValues.end()); (end(), end()) to avoid those issues? wdyt?

llvm/lib/IR/LLVMContextImpl.cpp

50 ↗

(On Diff #557864)

nit: remove comma

llvm/lib/IR/LLVMContextImpl.h

1661–1663 ↗

(On Diff #557864)

DenseMap::lookup returns a default constructed ValueType (so, nullptr here).

[jmorse]

llvm/include/llvm/IR/DebugProgramInstruction.h

369

We can generate iterators with nullptr pointers in them, and they'll compare equal indicating that the range is empty, but I fear this is going to be leaning on undefined behaviour in some way that comes back to bite us later. Returning end-end ranges sounds good, hopefully any faults that cause things to be stored in EmptyDPMarker will then trigger the leak-sanitizer buildbots.

[jmorse]

Closed by rG7d77bbef4ad9230 .

llvm/include/llvm/IR/BasicBlock.h

 #define LLVM_IR_BASICBLOCK_H
 
 #include "llvm-c/Types.h"
 #include "llvm/ADT/Twine.h"
 #include "llvm/ADT/ilist.h"
 #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/SymbolTableListTraits.h"
 #include "llvm/IR/Value.h"
 #include <cassert>
 #include <cstddef>
 #include <iterator>
 
 namespace llvm {

 /// the blocks. The BasicBlock class allows malformed basic blocks to occur
 /// because it may be useful in the intermediate stage of constructing or
 /// modifying a program. However, the verifier will ensure that basic blocks are
 /// "well formed".
 class BasicBlock final : public Value, // Basic blocks are data objects also
                          public ilist_node_with_parent<BasicBlock, Function> {
 public:
   using InstListType = SymbolTableList<Instruction, ilist_iterator_bits<true>>;
+  /// Storage for "trailing" debug-info. It is possible for a block to be
+  /// completely empty yet still contain debug-info, such as when manipulating
+  /// the terminator in a block with no other instructions. In these transient
+  /// scenarios, debug-info must be stored somewhere temporarily before the
+  /// block returns to a cannonical form when the terminator is re-inserted.
+  DPMarker TrailingDPValues;
 
 private:
   friend class BlockAddress;
   friend class SymbolTableListTraits<BasicBlock>;
 
   InstListType InstList;
   Function *Parent;
 

llvm/include/llvm/IR/DebugInfoMetadata.h

public:
 
   TempDIArgList clone() const { return cloneImpl(); }
 
   ArrayRef<ValueAsMetadata *> getArgs() const { return Args; }
 
   iterator args_begin() { return Args.begin(); }
   iterator args_end() { return Args.end(); }
 
+  ReplaceableMetadataImpl *getReplaceableUses() {
+    return Context.getReplaceableUses();
+  }
+
   static bool classof(const Metadata *MD) {
     return MD->getMetadataID() == DIArgListKind;
   }
 
   void handleChangedOperand(void *Ref, Metadata *New);
 };
 
 /// Identifies a unique instance of a variable.

llvm/include/llvm/IR/DebugProgramInstruction.h

+//===-- llvm/DebugProgramInstruction.h - Stream of debug info -------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Data structures for storing variable assignment information in LLVM. In the
+// dbg.value design, a dbg.value intrinsic specifies the position in a block
+// a source variable take on an LLVM Value:
+//
+//    %foo = add i32 1, %0
+//    dbg.value(metadata i32 %foo, ...)
+//    %bar = void call @ext(%foo);
+//
+// and all information is stored in the Value / Metadata hierachy defined
+// elsewhere in LLVM. In the "DPValue" design, each instruction /may/ have a
+// connection with a DPMarker, which identifies a position immediately before the
+// instruction, and each DPMarker /may/ then have connections to DPValues which
+// record the variable assignment information. To illustrate:
+//
+//    %foo = add i32 1, %0
+//       ; foo->DbgMarker == nullptr
+//       ;; There are no variable assignments / debug records "in front" of
+//       ;; the instruction for %foo, therefore it has no DbgMarker.
+//    %bar = void call @ext(%foo)
+//       ; bar->DbgMarker = {
+//       ;   StoredDPValues = {
+//       ;     DPValue(metadata i32 %foo, ...)
+//       ;   }
+//       ; }
+//       ;; There is a debug-info record in front of the %bar instruction,
+//       ;; thus it points at a DPMarker object. That DPMarker contains a
+//       ;; DPValue in it's ilist, storing the equivalent information to the
+//       ;; dbg.value above: the Value, DILocalVariable, etc.
+//
+// This structure separates the two concerns of the position of the debug-info
+// in the function, and the Value that it refers to. It also creates a new
+// "place" in-between the Value / Metadata hierachy where we can customise
+// storage and allocation techniques to better suite debug-info workloads.
+// NB: as of the initial prototype, none of that has actually been attempted
+// yet.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
+#define LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
+
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/Bitfields.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/ADT/ilist_node.h"
+#include "llvm/ADT/iterator.h"
+#include "llvm/IR/DebugInfoMetadata.h"
+#include "llvm/IR/DebugLoc.h"
+#include "llvm/IR/DerivedTypes.h"
+#include "llvm/IR/SymbolTableListTraits.h"
+#include "llvm/IR/TrackingMDRef.h"
+#include "llvm/Support/AtomicOrdering.h"
+#include <cstdint>
+#include <utility>
+
+namespace llvm {
+
+class Instruction;
+class BasicBlock;
+class MDNode;
+class Module;
+class DbgVariableIntrinsic;
+class DPMarker;
+class DPValue;
+class raw_ostream;
+
+/// Record of a variable value-assignment, aka a non instruction representation
+/// of the dbg.value intrinsic. Features various methods copied across from the
+/// Instruction class to aid ease-of-use. DPValue objects should always be
+/// linked into a DPMarker's StoredDPValues list. The marker connects a DPValue
+/// back to it's position in the BasicBlock.
+///
+/// This class inherits from DebugValueUser to allow LLVM's metadata facilities
+/// to update our references to metadata beneath our feet.
+class DPValue : public ilist_node<DPValue>, private DebugValueUser {
+  friend class DebugValueUser;
+
+  // NB: there is no explicit "Value" field in this class, it's effectively the
+  // DebugValueUser superclass instead. The referred to Value can either be a
+  // ValueAsMetadata or a DIArgList.
+
+  DILocalVariable *Variable;
+  DIExpression *Expression;
+  DebugLoc DbgLoc;
+
+public:
+  void deleteInstr();
+
+  const BasicBlock *getParent() const;
+  BasicBlock *getParent();
+  void dump() const;
+  void removeFromParent();
+  void eraseFromParent();
+
+  using self_iterator = simple_ilist<DPValue>::iterator;
+  using const_self_iterator = simple_ilist<DPValue>::const_iterator;
+
+  enum class LocationType {
+    Declare,
+    Value,
+  };
+  /// Classification of the debug-info record that this DPValue represents.
+  /// Essentially, "is this a dbg.value or dbg.declare?". dbg.declares are not
+  /// currently supported, but it would be trivial to do so.
+  LocationType Type;
+
+  /// Marker that this DPValue is linked into.
+  DPMarker *Marker = nullptr;
+
+  /// Create a new DPValue representing the intrinsic \p DVI, for example the
+  /// assignment represented by a dbg.value.
+  DPValue(const DbgVariableIntrinsic *DVI);
+  DPValue(const DPValue &DPV);
+  /// Directly construct a new DPValue representing a dbg.value intrinsic
+  /// assigning \p Location to the DV / Expr / DI variable.
+  DPValue(Metadata *Location, DILocalVariable *DV, DIExpression *Expr,
+          const DILocation *DI);
+
+  /// Iterator for ValueAsMetadata that internally uses direct pointer iteration
+  /// over either a ValueAsMetadata* or a ValueAsMetadata**, dereferencing to the
+  /// ValueAsMetadata .
+  class location_op_iterator
+      : public iterator_facade_base<location_op_iterator,
+                                    std::bidirectional_iterator_tag, Value *> {
+    PointerUnion<ValueAsMetadata *, ValueAsMetadata **> I;
+
+  public:
+    location_op_iterator(ValueAsMetadata *SingleIter) : I(SingleIter) {}
+    location_op_iterator(ValueAsMetadata **MultiIter) : I(MultiIter) {}
+
+    location_op_iterator(const location_op_iterator &R) : I(R.I) {}
+    location_op_iterator &operator=(const location_op_iterator &R) {
+      I = R.I;
+      return *this;
+    }
+    bool operator==(const location_op_iterator &RHS) const {
+      return I == RHS.I;
+    }
+    const Value *operator*() const {
+      ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
+                                 ? I.get<ValueAsMetadata *>()
+                                 : *I.get<ValueAsMetadata **>();
+      return VAM->getValue();
+    };
+    Value *operator*() {
+      ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
+                                 ? I.get<ValueAsMetadata *>()
+                                 : *I.get<ValueAsMetadata **>();
+      return VAM->getValue();
+    }
+    location_op_iterator &operator++() {
+      if (I.is<ValueAsMetadata *>())
+        I = I.get<ValueAsMetadata *>() + 1;
+      else
+        I = I.get<ValueAsMetadata **>() + 1;
+      return *this;
+    }
+    location_op_iterator &operator--() {
+      if (I.is<ValueAsMetadata *>())
+        I = I.get<ValueAsMetadata *>() - 1;
+      else
+        I = I.get<ValueAsMetadata **>() - 1;
+      return *this;
+    }
+  };
+
+  /// Get the locations corresponding to the variable referenced by the debug
+  /// info intrinsic.  Depending on the intrinsic, this could be the
+  /// variable's value or its address.
+  iterator_range<location_op_iterator> location_ops() const;
+
+  Value *getVariableLocationOp(unsigned OpIdx) const;
+
+  void replaceVariableLocationOp(Value *OldValue, Value *NewValue,
+                                 bool AllowEmpty = false);
+  void replaceVariableLocationOp(unsigned OpIdx, Value *NewValue);
+  /// Adding a new location operand will always result in this intrinsic using
+  /// an ArgList, and must always be accompanied by a new expression that uses
+  /// the new operand.
+  void addVariableLocationOps(ArrayRef<Value *> NewValues,
+                              DIExpression *NewExpr);
+
+  void setVariable(DILocalVariable *NewVar) { Variable = NewVar; }
+
+  void setExpression(DIExpression *NewExpr) { Expression = NewExpr; }
+
+  unsigned getNumVariableLocationOps() const {
+    if (hasArgList())
+      return cast<DIArgList>(getRawLocation())->getArgs().size();
+    return 1;
+  }
+
+  bool hasArgList() const { return isa<DIArgList>(getRawLocation()); }
+  /// Returns true if this DPValue has no empty MDNodes in its location list.
+  bool hasValidLocation() const { return getVariableLocationOp(0) != nullptr; }
+
+  /// Does this describe the address of a local variable. True for dbg.addr
+  /// and dbg.declare, but not dbg.value, which describes its value.
+  bool isAddressOfVariable() const { return Type != LocationType::Value; }
+  LocationType getType() const { return Type; }
+
+  DebugLoc getDebugLoc() const { return DbgLoc; }
+  void setDebugLoc(DebugLoc Loc) { DbgLoc = std::move(Loc); }
+
+  void setKillLocation() {
+    // TODO: When/if we remove duplicate values from DIArgLists, we don't need
+    // this set anymore.
+    SmallPtrSet<Value *, 4> RemovedValues;
+    for (Value *OldValue : location_ops()) {
+      if (!RemovedValues.insert(OldValue).second)
+        continue;
+      Value *Poison = PoisonValue::get(OldValue->getType());
+      replaceVariableLocationOp(OldValue, Poison);
+    }
+  }
+
+  bool isKillLocation() const {
+    return (getNumVariableLocationOps() == 0 &&
+            !getExpression()->isComplex()) ||
+           any_of(location_ops(), [](Value *V) { return isa<UndefValue>(V); });
+  }
+
+  DILocalVariable *getVariable() const { return Variable; }
+
+  DIExpression *getExpression() const { return Expression; }
+
+  Metadata *getRawLocation() const { return DebugValue; }
+
+  /// Use of this should generally be avoided; instead,
+  /// replaceVariableLocationOp and addVariableLocationOps should be used where
+  /// possible to avoid creating invalid state.
+  void setRawLocation(Metadata *NewLocation) {
+    assert(
+        (isa<ValueAsMetadata>(NewLocation) || isa<DIArgList>(NewLocation) ||
+         isa<MDNode>(NewLocation)) &&
+        "Location for a DPValue must be either ValueAsMetadata or DIArgList");
+    resetDebugValue(NewLocation);
+  }
+
+  /// Get the size (in bits) of the variable, or fragment of the variable that
+  /// is described.
+  std::optional<uint64_t> getFragmentSizeInBits() const;
+
+  DPValue *clone() const;
+  /// Convert this DPValue back into a dbg.value intrinsic.
+  /// \p InsertBefore Optional position to insert this intrinsic.
+  /// \returns A new dbg.value intrinsic representiung this DPValue.
+  DbgVariableIntrinsic *createDebugIntrinsic(Module *M,
+                                             Instruction *InsertBefore) const;
+  /// Handle changes to the location of the Value(s) that we refer to happening
+  /// "under our feet".
+  void handleChangedLocation(Metadata *NewLocation);
+
+  void setMarker(DPMarker *M) { Marker = M; }
+
+  DPMarker *getMarker() { return Marker; }
+  const DPMarker *getMarker() const { return Marker; }
+
+  BasicBlock *getBlock();
+  const BasicBlock *getBlock() const;
+
+  Function *getFunction();
+  const Function *getFunction() const;
+
+  Module *getModule();
+  const Module *getModule() const;
+
+  LLVMContext &getContext();
+  const LLVMContext &getContext() const;
+
+  void print(raw_ostream &O, bool IsForDebug = false) const;
+  void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
+};
+
+/// Per-instruction record of debug-info. If an Instruction is the position of
+/// some debugging information, it points at a DPMarker storing that info. Each
+/// marker points back at the instruction that owns it. Various utilities are
+/// provided for manipulating the DPValues contained within this marker.
+///
+/// This class has a rough surface area, because it's needed to preserve the one
+/// arefact that we can't yet eliminate from the intrinsic / dbg.value
+/// debug-info design: the order of DPValues/records is significant, and
+/// duplicates can exist. Thus, if one has a run of debug-info records such as:
+///    dbg.value(...
+///    %foo = barinst
+///    dbg.value(...
+/// and remove barinst, then the dbg.values must be preserved in the correct
+/// order. Hence, the use of iterators to select positions to insert things
+/// into, or the occasional InsertAtHead parameter indicating that new records
+/// should go at the start of the list.
+///
+/// There are only five or six places in LLVM that truly rely on this ordering,
+/// which we can improve in the future. Additionally, many improvements in the
+/// way that debug-info is stored can be achieved in this class, at a future
+/// date.
+class DPMarker {
+public:
+  DPMarker() {}
+  /// Link back to the Instruction that owns this marker. Can be null during
+  /// operations that move a marker from one instruction to another.
+  Instruction *MarkedInstr;
+
+  /// List of DPValues, each recording a single variable assignment, the
+  /// equivalent of a dbg.value intrinsic. There is a one-to-one relationship
+  /// between each dbg.value in a block and each DPValue once the
+  /// representation has been converted, and the ordering of DPValues is
+  /// meaningful in the same was a dbg.values.
+  simple_ilist<DPValue> StoredDPValues;
+
+  const BasicBlock *getParent() const;
+  BasicBlock *getParent();
+
+  /// Handle the removal of a marker: the position of debug-info has gone away,
+  /// but the stored debug records should not. Drop them onto the next
+  /// instruction, or otherwise work out what to do with them.
+  void removeMarker();
+  void dump() const;
+
+  void removeFromParent();
+  void eraseFromParent();
+
+  /// Implement operator<< on DPMarker.
+  void print(raw_ostream &O, bool IsForDebug = false) const;
+  void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
+
+  /// Produce a range over all the DPValues in this Marker.
+  iterator_range<simple_ilist<DPValue>::iterator> getDbgValueRange();
+  /// Transfer any DPValues from \p Src into this DPMarker. If \p InsertAtHead
+  /// is true, place them before existing DPValues, otherwise afterwards.
+  void absorbDebugValues(DPMarker &Src, bool InsertAtHead);
+  /// Insert a DPValue into this DPMarker, at the end of the list. If
+  /// \p InsertAtHead is true, at the start.
+  void insertDPValue(DPValue *New, bool InsertAtHead);
+  /// Clone all DPMarkers from \p From into this marker. There are numerous
+  /// options to customise the source/destination, due to gnarliness, see class
+  /// comment.
+  /// \p FromHere If non-null, copy from FromHere to the end of From's DPValues
+  /// \p InsertAtHead Place the cloned DPValues at the start of StoredDPValues
+  /// \returns Range over all the newly cloned DPValues
+  iterator_range<simple_ilist<DPValue>::iterator>
+  cloneDebugInfoFrom(DPMarker *From,
+                     std::optional<simple_ilist<DPValue>::iterator> FromHere,
+                     bool InsertAtHead = false);
+  /// Erase all DPValues in this DPMarker.
+  void dropDPValues();
+  /// Erase a single DPValue from this marker. In an ideal future, we would
+  /// never erase an assignment in this way, but it's the equivalent to
+  /// erasing a dbg.value from a block.
+  void dropOneDPValue(DPValue *DPV);
+};
+
+inline raw_ostream &operator<<(raw_ostream &OS, const DPMarker &Marker) {
+  Marker.print(OS);
+  return OS;
+}
+
+inline raw_ostream &operator<<(raw_ostream &OS, const DPValue &Value) {
+  Value.print(OS);
+  return OS;
+}
+
+} // namespace llvm
+
+#endif // LLVM_IR_DEBUGPROGRAMINSTRUCTION_H

llvm/include/llvm/IR/Instruction.h

 #include "llvm/IR/Value.h"
 #include "llvm/Support/AtomicOrdering.h"
 #include <cstdint>
 #include <utility>
 
 namespace llvm {
 
 class BasicBlock;
+class DPMarker;
 class FastMathFlags;
 class MDNode;
 class Module;
 struct AAMDNodes;
 
 template <> struct ilist_alloc_traits<Instruction> {
   static inline void deleteNode(Instruction *V);
 };
 
 class Instruction : public User,
                     public ilist_node_with_parent<Instruction, BasicBlock,
                                                   ilist_iterator_bits<true>> {
 public:
   using InstListType = SymbolTableList<Instruction, ilist_iterator_bits<true>>;
 private:
   BasicBlock *Parent;
   DebugLoc DbgLoc;                         // 'dbg' Metadata cache.
 
   /// Relative order of this instruction in its parent basic block. Used for
   /// O(1) local dominance checks between instructions.
   mutable unsigned Order = 0;
 
+public:
+  /// Optional marker recording the position for debugging information that
+  /// takes effect immediately before this instruction. Null unless there is
+  /// debugging information present.
+  DPMarker *DbgMarker = nullptr;
+
 protected:
   // The 15 first bits of `Value::SubclassData` are available for subclasses of
   // `Instruction` to use.
   using OpaqueField = Bitfield::Element<uint16_t, 0, 15>;
 
   // Template alias so that all Instruction storing alignment use the same
   // definiton.
   // Valid alignments are powers of two from 2^0 to 2^MaxAlignmentExponent =

llvm/include/llvm/IR/Metadata.h

 #include <type_traits>
 #include <utility>
 
 namespace llvm {
 
 class Module;
 class ModuleSlotTracker;
 class raw_ostream;
+class DPValue;
 template <typename T> class StringMapEntry;
 template <typename ValueTy> class StringMapEntryStorage;
 class Type;
 
 enum LLVMConstants : uint32_t {
   DEBUG_METADATA_VERSION = 3 // Current debug info version number.
 };
 
public:
   }
 
 private:
   void handleChangedMetadata(Metadata *MD);
   void track();
   void untrack();
 };
 
+/// Base class for tracking ValueAsMetadata/DIArgLists with user lookups and
+/// Owner callbacks outside of ValueAsMetadata.
+///
+/// Currently only inherited by DPValue; if other classes need to use it, then
+/// a SubclassID will need to be added (either as a new field or by making
+/// DebugValue into a PointerIntUnion) to discriminate between the subclasses in
+/// lookup and callback handling.
+class DebugValueUser {
+protected:
+  Metadata *DebugValue;
+
+public:
+  DPValue *getUser();
+  const DPValue *getUser() const;
+  void handleChangedValue(Metadata *NewDebugValue);
+  DebugValueUser() = default;
+  explicit DebugValueUser(Metadata *DebugValue) : DebugValue(DebugValue) {
+    trackDebugValue();
+  }
+
+  DebugValueUser(DebugValueUser &&X) : DebugValue(X.DebugValue) {
+    retrackDebugValue(X);
+  }
+  DebugValueUser(const DebugValueUser &X) : DebugValue(X.DebugValue) {
+    trackDebugValue();
+  }
+
+  DebugValueUser &operator=(DebugValueUser &&X) {
+    if (&X == this)
+      return *this;
+
+    untrackDebugValue();
+    DebugValue = X.DebugValue;
+    retrackDebugValue(X);
+    return *this;
+  }
+
+  DebugValueUser &operator=(const DebugValueUser &X) {
+    if (&X == this)
+      return *this;
+
+    untrackDebugValue();
+    DebugValue = X.DebugValue;
+    trackDebugValue();
+    return *this;
+  }
+
+  ~DebugValueUser() { untrackDebugValue(); }
+
+  void resetDebugValue() {
+    untrackDebugValue();
+    DebugValue = nullptr;
+  }
+  void resetDebugValue(Metadata *DebugValue) {
+    untrackDebugValue();
+    this->DebugValue = DebugValue;
+    trackDebugValue();
+  }
+
+  bool operator==(const DebugValueUser &X) const {
+    return DebugValue == X.DebugValue;
+  }
+  bool operator!=(const DebugValueUser &X) const {
+    return DebugValue != X.DebugValue;
+  }
+
+private:
+  void trackDebugValue();
+  void untrackDebugValue();
+  void retrackDebugValue(DebugValueUser &X);
+};
+
 /// API for tracking metadata references through RAUW and deletion.
 ///
 /// Shared API for updating \a Metadata pointers in subclasses that support
 /// RAUW.
 ///
 /// This API is not meant to be used directly.  See \a TrackingMDRef for a
 /// user-friendly tracking reference.
 class MetadataTracking {
public:
   ///
   /// As \a track(Metadata*&), but with support for calling back to \c Owner to
   /// tell it that its operand changed.  This could trigger \c Owner being
   /// re-uniqued.
   static bool track(void *Ref, Metadata &MD, MetadataAsValue &Owner) {
     return track(Ref, MD, &Owner);
   }
 
+  /// Track the reference to metadata for \a DebugValueUser.
+  ///
+  /// As \a track(Metadata*&), but with support for calling back to \c Owner to
+  /// tell it that its operand changed.  This could trigger \c Owner being
+  /// re-uniqued.
+  static bool track(void *Ref, Metadata &MD, DebugValueUser &Owner) {
+    return track(Ref, MD, &Owner);
+  }
+
   /// Stop tracking a reference to metadata.
   ///
   /// Stops \c *MD from tracking \c MD.
   static void untrack(Metadata *&MD) { untrack(&MD, *MD); }
   static void untrack(void *Ref, Metadata &MD);
 
   /// Move tracking from one reference to another.
   ///
   /// Semantically equivalent to \c untrack(MD) followed by \c track(New),
   /// except that ownership callbacks are maintained.
   ///
   /// Note: it is an error if \c *MD does not equal \c New.
   ///
   /// \return true iff tracking is supported by \c MD.
   static bool retrack(Metadata *&MD, Metadata *&New) {
     return retrack(&MD, *MD, &New);
   }
   static bool retrack(void *Ref, Metadata &MD, void *New);
 
   /// Check whether metadata is replaceable.
   static bool isReplaceable(const Metadata &MD);
 
-  using OwnerTy = PointerUnion<MetadataAsValue *, Metadata *>;
+  using OwnerTy = PointerUnion<MetadataAsValue *, Metadata *, DebugValueUser *>;
 
 private:
   /// Track a reference to metadata for an owner.
   ///
   /// Generalized version of tracking.
   static bool track(void *Ref, Metadata &MD, OwnerTy Owner);
 };
 
 /// Shared implementation of use-lists for replaceable metadata.
 ///
 /// Most metadata cannot be RAUW'ed.  This is a shared implementation of
-/// use-lists and associated API for the two that support it (\a ValueAsMetadata
-/// and \a TempMDNode).
+/// use-lists and associated API for the three that support it (
+/// \a ValueAsMetadata, \a TempMDNode, and \a DIArgList).
 class ReplaceableMetadataImpl {
   friend class MetadataTracking;
 
 public:
   using OwnerTy = MetadataTracking::OwnerTy;
 
 private:
   LLVMContext &Context;
public:
   /// Replace all uses of this with MD.
   ///
   /// Replace all uses of this with \c MD, which is allowed to be null.
   void replaceAllUsesWith(Metadata *MD);
    /// Replace all uses of the constant with Undef in debug info metadata
   static void SalvageDebugInfo(const Constant &C); 
   /// Returns the list of all DIArgList users of this.
   SmallVector<Metadata *> getAllArgListUsers();
+  /// Returns the list of all DPValue users of this.
+  SmallVector<DPValue *> getAllDPValueUsers();
 
   /// Resolve all uses of this.
   ///
   /// Resolve all uses of this, turning off RAUW permanently.  If \c
   /// ResolveUsers, call \a MDNode::resolve() on any users whose last operand
   /// is resolved.
   void resolveAllUses(bool ResolveUsers = true);
 
public:
 
   Value *getValue() const { return V; }
   Type *getType() const { return V->getType(); }
   LLVMContext &getContext() const { return V->getContext(); }
 
   SmallVector<Metadata *> getAllArgListUsers() {
     return ReplaceableMetadataImpl::getAllArgListUsers();
   }
+  SmallVector<DPValue *> getAllDPValueUsers() {
+    return ReplaceableMetadataImpl::getAllDPValueUsers();
+  }
 
   static void handleDeletion(Value *V);
   static void handleRAUW(Value *From, Value *To);
 
 protected:
   /// Handle collisions after \a Value::replaceAllUsesWith().
   ///
   /// RAUW isn't supported directly for \a ValueAsMetadata, but if the wrapped
public:
   /// resolved automatically.  However, if this (or one of its operands) is
   /// involved in a cycle, \a resolveCycles() needs to be called explicitly.
   bool isResolved() const { return !isTemporary() && !getNumUnresolved(); }
 
   bool isUniqued() const { return Storage == Uniqued; }
   bool isDistinct() const { return Storage == Distinct; }
   bool isTemporary() const { return Storage == Temporary; }
 
+  bool isReplaceable() const {
+    return isTemporary() || getMetadataID() == DIArgListKind;
+  }
+
   /// RAUW a temporary.
   ///
   /// \pre \a isTemporary() must be \c true.
   void replaceAllUsesWith(Metadata *MD) {
-    assert(isTemporary() && "Expected temporary node");
+    assert(isReplaceable() && "Expected temporary/replaceable node");
     if (Context.hasReplaceableUses())
       Context.getReplaceableUses()->replaceAllUsesWith(MD);
   }
 
   /// Resolve cycles.
   ///
   /// Once all forward declarations have been resolved, force cycles to be
   /// resolved.

llvm/lib/IR/CMakeLists.txt

add_llvm_component_library(LLVMCore
   Constants.cpp
   ConvergenceVerifier.cpp
   Core.cpp
   CycleInfo.cpp
   DIBuilder.cpp
   DataLayout.cpp
   DebugInfo.cpp
   DebugInfoMetadata.cpp
+  DebugProgramInstruction.cpp
   DebugLoc.cpp
   DiagnosticHandler.cpp
   DiagnosticInfo.cpp
   DiagnosticPrinter.cpp
   Dominators.cpp
   EHPersonalities.cpp
   FPEnv.cpp
   Function.cpp

llvm/lib/IR/DebugInfoMetadata.cpp

for (ValueAsMetadata *&VM : Args) {
     if (&VM == OldVMPtr) {
       if (NewVM)
         VM = NewVM;
       else
         VM = ValueAsMetadata::get(PoisonValue::get(VM->getValue()->getType()));
     }
   }
   if (Uniq) {
-    if (uniquify() != this)
-      storeDistinctInContext();
+    MDNode *UniqueArgList = uniquify();
+    if (UniqueArgList != this) {
+      replaceAllUsesWith(UniqueArgList);
+      // Clear this here so we don't try to untrack in the destructor.
+      Args.clear();
+      delete this;
+      return;
+    }
   }
   track();
 }
 void DIArgList::track() {
   for (ValueAsMetadata *&VAM : Args)
     if (VAM)
       MetadataTracking::track(&VAM, *VAM, *this);
 }
 void DIArgList::untrack() {

llvm/lib/IR/DebugProgramInstruction.cpp

+//======-- DebugProgramInstruction.cpp - Implement DPValues/DPMarkers --======//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "llvm/IR/DebugProgramInstruction.h"
+#include "llvm/IR/DIBuilder.h"
+#include "llvm/IR/IntrinsicInst.h"
+
+namespace llvm {
+
+DPValue::DPValue(const DbgVariableIntrinsic *DVI)
+    : DebugValueUser(DVI->getRawLocation()), Variable(DVI->getVariable()),
+      Expression(DVI->getExpression()), DbgLoc(DVI->getDebugLoc()) {
+  switch (DVI->getIntrinsicID()) {
+  case Intrinsic::dbg_value:
+    Type = LocationType::Value;
+    break;
+  case Intrinsic::dbg_declare:
+    Type = LocationType::Declare;
+    break;
+  default:
+    llvm_unreachable(
+        "Trying to create a DPValue with an invalid intrinsic type!");
+  }
+}
+
+DPValue::DPValue(const DPValue &DPV)
+    : DebugValueUser(DPV.getRawLocation()), Type(DPV.getType()),
+      Variable(DPV.getVariable()), Expression(DPV.getExpression()),
+      DbgLoc(DPV.getDebugLoc()) {}
+
+DPValue::DPValue(Metadata *Location, DILocalVariable *DV, DIExpression *Expr,
+                 const DILocation *DI)
+    : DebugValueUser(Location), Variable(DV), Expression(Expr), DbgLoc(DI),
+      Type(LocationType::Value) {
+}
+
+void DPValue::deleteInstr() { delete this; }
+
+iterator_range<DPValue::location_op_iterator> DPValue::location_ops() const {
+  auto *MD = getRawLocation();
+  // If a Value has been deleted, the "location" for this DPValue will be
+  // replaced by nullptr. Return an empty range.
+  if (!MD)
+    return {location_op_iterator(static_cast<ValueAsMetadata *>(nullptr)),
+            location_op_iterator(static_cast<ValueAsMetadata *>(nullptr))};
+
+  // If operand is ValueAsMetadata, return a range over just that operand.
+  if (auto *VAM = dyn_cast<ValueAsMetadata>(MD))
+    return {location_op_iterator(VAM), location_op_iterator(VAM + 1)};
+
+  // If operand is DIArgList, return a range over its args.
+  if (auto *AL = dyn_cast<DIArgList>(MD))
+    return {location_op_iterator(AL->args_begin()),
+            location_op_iterator(AL->args_end())};
+
+  // Operand is an empty metadata tuple, so return empty iterator.
+  assert(cast<MDNode>(MD)->getNumOperands() == 0);
+  return {location_op_iterator(static_cast<ValueAsMetadata *>(nullptr)),
+          location_op_iterator(static_cast<ValueAsMetadata *>(nullptr))};
+}
+
+Value *DPValue::getVariableLocationOp(unsigned OpIdx) const {
+  auto *MD = getRawLocation();
+  if (!MD)
+    return nullptr;
+
+  if (auto *AL = dyn_cast<DIArgList>(MD))
+    return AL->getArgs()[OpIdx]->getValue();
+  if (isa<MDNode>(MD))
+    return nullptr;
+  assert(isa<ValueAsMetadata>(MD) &&
+         "Attempted to get location operand from DPValue with none.");
+  auto *V = cast<ValueAsMetadata>(MD);
+  assert(OpIdx == 0 && "Operand Index must be 0 for a debug intrinsic with a "
+                       "single location operand.");
+  return V->getValue();
+}
+
+static ValueAsMetadata *getAsMetadata(Value *V) {
+  return isa<MetadataAsValue>(V) ? dyn_cast<ValueAsMetadata>(
+                                       cast<MetadataAsValue>(V)->getMetadata())
+                                 : ValueAsMetadata::get(V);
+}
+
+void DPValue::replaceVariableLocationOp(Value *OldValue, Value *NewValue,
+                                        bool AllowEmpty) {
+  assert(NewValue && "Values must be non-null");
+  auto Locations = location_ops();
+  auto OldIt = find(Locations, OldValue);
+  if (OldIt == Locations.end()) {
+    if (AllowEmpty)
+      return;
+    llvm_unreachable("OldValue must be a current location");
+  }
+
+  if (!hasArgList()) {
+    // Set our location to be the MAV wrapping the new Value.
+    setRawLocation(isa<MetadataAsValue>(NewValue)
+                       ? cast<MetadataAsValue>(NewValue)->getMetadata()
+                       : ValueAsMetadata::get(NewValue));
+    return;
+  }
+
+  // We must be referring to a DIArgList, produce a new operands vector with the
+  // old value replaced, generate a new DIArgList and set it as our location.
+  SmallVector<ValueAsMetadata *, 4> MDs;
+  ValueAsMetadata *NewOperand = getAsMetadata(NewValue);
+  for (auto *VMD : Locations)
+    MDs.push_back(VMD == *OldIt ? NewOperand : getAsMetadata(VMD));
+  setRawLocation(DIArgList::get(getVariableLocationOp(0)->getContext(), MDs));
+}
+
+void DPValue::replaceVariableLocationOp(unsigned OpIdx, Value *NewValue) {
+  assert(OpIdx < getNumVariableLocationOps() && "Invalid Operand Index");
+
+  if (!hasArgList()) {
+    setRawLocation(isa<MetadataAsValue>(NewValue)
+                       ? cast<MetadataAsValue>(NewValue)->getMetadata()
+                       : ValueAsMetadata::get(NewValue));
+    return;
+  }
+
+  SmallVector<ValueAsMetadata *, 4> MDs;
+  ValueAsMetadata *NewOperand = getAsMetadata(NewValue);
+  for (unsigned Idx = 0; Idx < getNumVariableLocationOps(); ++Idx)
+    MDs.push_back(Idx == OpIdx ? NewOperand
+                               : getAsMetadata(getVariableLocationOp(Idx)));
+
+  setRawLocation(DIArgList::get(getVariableLocationOp(0)->getContext(), MDs));
+}
+
+void DPValue::addVariableLocationOps(ArrayRef<Value *> NewValues,
+                                     DIExpression *NewExpr) {
+  assert(NewExpr->hasAllLocationOps(getNumVariableLocationOps() +
+                                    NewValues.size()) &&
+         "NewExpr for debug variable intrinsic does not reference every "
+         "location operand.");
+  assert(!is_contained(NewValues, nullptr) && "New values must be non-null");
+  setExpression(NewExpr);
+  SmallVector<ValueAsMetadata *, 4> MDs;
+  for (auto *VMD : location_ops())
+    MDs.push_back(getAsMetadata(VMD));
+  for (auto *VMD : NewValues)
+    MDs.push_back(getAsMetadata(VMD));
+  setRawLocation(DIArgList::get(getVariableLocationOp(0)->getContext(), MDs));
+}
+
+std::optional<uint64_t> DPValue::getFragmentSizeInBits() const {
+  if (auto Fragment = getExpression()->getFragmentInfo())
+    return Fragment->SizeInBits;
+  return getVariable()->getSizeInBits();
+}
+
+DPValue *DPValue::clone() const { return new DPValue(*this); }
+
+DbgVariableIntrinsic *
+DPValue::createDebugIntrinsic(Module *M, Instruction *InsertBefore) const {
+  DICompileUnit *Unit =
+      getDebugLoc().get()->getScope()->getSubprogram()->getUnit();
+  assert(M && Unit &&
+         "Cannot clone from BasicBlock that is not part of a Module or "
+         "DICompileUnit!");
+  LLVMContext &Context = getDebugLoc()->getContext();
+  Value *Args[] = {MetadataAsValue::get(Context, getRawLocation()),
+                   MetadataAsValue::get(Context, getVariable()),
+                   MetadataAsValue::get(Context, getExpression())};
+  Function *IntrinsicFn;
+
+  // Work out what sort of intrinsic we're going to produce.
+  switch (getType()) {
+  case DPValue::LocationType::Declare:
+    IntrinsicFn = Intrinsic::getDeclaration(M, Intrinsic::dbg_declare);
+    break;
+  case DPValue::LocationType::Value:
+    IntrinsicFn = Intrinsic::getDeclaration(M, Intrinsic::dbg_value);
+    break;
+  }
+
+  // Create the intrinsic from this DPValue's information, optionally insert
+  // into the target location.
+  DbgVariableIntrinsic *DVI = cast<DbgVariableIntrinsic>(
+      CallInst::Create(IntrinsicFn->getFunctionType(), IntrinsicFn, Args));
+  DVI->setDebugLoc(getDebugLoc());
+  if (InsertBefore)
+    DVI->insertBefore(InsertBefore);
+
+  return DVI;
+}
+
+void DPValue::handleChangedLocation(Metadata *NewLocation) {
+  resetDebugValue(NewLocation);
+}
+
+const BasicBlock *DPValue::getParent() const {
+  return Marker->MarkedInstr->getParent();
+}
+
+BasicBlock *DPValue::getParent() { return Marker->MarkedInstr->getParent(); }
+
+BasicBlock *DPValue::getBlock() { return Marker->getParent(); }
+
+const BasicBlock *DPValue::getBlock() const { return Marker->getParent(); }
+
+Function *DPValue::getFunction() { return getBlock()->getParent(); }
+
+const Function *DPValue::getFunction() const { return getBlock()->getParent(); }
+
+Module *DPValue::getModule() { return getFunction()->getParent(); }
+
+const Module *DPValue::getModule() const { return getFunction()->getParent(); }
+
+LLVMContext &DPValue::getContext() { return getBlock()->getContext(); }
+
+const LLVMContext &DPValue::getContext() const {
+  return getBlock()->getContext();
+}
+
+void DPMarker::dropDPValues() {
+  while (!StoredDPValues.empty()) {
+    auto It = StoredDPValues.begin();
+    DPValue *DPV = &*It;
+    StoredDPValues.erase(It);
+    DPV->deleteInstr();
+  }
+}
+
+void DPMarker::dropOneDPValue(DPValue *DPV) {
+  assert(DPV->getMarker() == this);
+  StoredDPValues.erase(DPV->getIterator());
+  DPV->deleteInstr();
+}
+
+const BasicBlock *DPMarker::getParent() const {
+  return MarkedInstr->getParent();
+}
+
+BasicBlock *DPMarker::getParent() { return MarkedInstr->getParent(); }
+
+void DPMarker::removeMarker() {
+  // Are there any DPValues in this DPMarker? If not, nothing to preserve.
+  Instruction *Owner = MarkedInstr;
+  if (StoredDPValues.empty()) {
+    eraseFromParent();
+    Owner->DbgMarker = nullptr;
+    return;
+  }
+
+  // The attached DPValues need to be preserved; attach them to the next
+  // instruction. If there isn't a next instruction, put them on the
+  // "trailing" list.
+  // (This logic gets refactored in a future patch, needed to break some
+  //  dependencies here).
+  BasicBlock::iterator NextInst = std::next(Owner->getIterator());
+  DPMarker *NextMarker;
+  if (NextInst == Owner->getParent()->end())
+    NextMarker = &Owner->getParent()->TrailingDPValues;
+  else
+    NextMarker = NextInst->DbgMarker;
+  NextMarker->absorbDebugValues(*this, true);
+
+  eraseFromParent();
+}
+
+void DPMarker::removeFromParent() {
+  MarkedInstr->DbgMarker = nullptr;
+  MarkedInstr = nullptr;
+}
+
+void DPMarker::eraseFromParent() {
+  if (MarkedInstr)
+    removeFromParent();
+  dropDPValues();
+  delete this;
+}
+
+iterator_range<DPValue::self_iterator> DPMarker::getDbgValueRange() {
+  return make_range(StoredDPValues.begin(), StoredDPValues.end());
+}
+
+void DPValue::removeFromParent() {
+  getMarker()->StoredDPValues.erase(getIterator());
+}
+
+void DPValue::eraseFromParent() {
+  removeFromParent();
+  deleteInstr();
+}
+
+void DPMarker::insertDPValue(DPValue *New, bool InsertAtHead) {
+  auto It = InsertAtHead ? StoredDPValues.begin() : StoredDPValues.end();
+  StoredDPValues.insert(It, *New);
+  New->setMarker(this);
+}
+
+void DPMarker::absorbDebugValues(DPMarker &Src, bool InsertAtHead) {
+  auto It = InsertAtHead ? StoredDPValues.begin() : StoredDPValues.end();
+  for (DPValue &DPV : Src.StoredDPValues)
+    DPV.setMarker(this);
+
+  StoredDPValues.splice(It, Src.StoredDPValues);
+}
+
+iterator_range<simple_ilist<DPValue>::iterator> DPMarker::cloneDebugInfoFrom(
+    DPMarker *From, std::optional<simple_ilist<DPValue>::iterator> from_here,
+    bool InsertAtHead) {
+  DPValue *First = nullptr;
+  // Work out what range of DPValues to clone: normally all the contents of the
+  // "From" marker, optionally we can start from the from_here position down to
+  // end().
+  auto Range =
+      make_range(From->StoredDPValues.begin(), From->StoredDPValues.end());
+  if (from_here.has_value())
+    Range = make_range(*from_here, From->StoredDPValues.end());
+
+  // Clone each DPValue and insert into StoreDPValues; optionally place them at
+  // the start or the end of the list.
+  if (InsertAtHead) {
+    for (DPValue &DPV : reverse(Range)) {
+      DPValue *New = DPV.clone();
+      New->setMarker(this);
+      StoredDPValues.insert(StoredDPValues.begin(), *New);
+      if (!First)
+        First = New;
+    }
+  } else {
+    for (DPValue &DPV : Range) {
+      DPValue *New = DPV.clone();
+      New->setMarker(this);
+      StoredDPValues.insert(StoredDPValues.end(), *New);
+      if (!First)
+        First = New;
+    }
+  }
+  if (!First)
+    return {StoredDPValues.end(), StoredDPValues.end()};
+
+  return {First->getIterator(), StoredDPValues.end()};
+}
+
+} // end namespace llvm
+

llvm/lib/IR/Metadata.cpp

if (MD)
     MetadataTracking::track(&MD, *MD, *this);
 }
 
 void MetadataAsValue::untrack() {
   if (MD)
     MetadataTracking::untrack(MD);
 }
 
+DPValue *DebugValueUser::getUser() { return static_cast<DPValue *>(this); }
+const DPValue *DebugValueUser::getUser() const {
+  return static_cast<const DPValue *>(this);
+}
+void DebugValueUser::handleChangedValue(Metadata *NewMD) {
+  getUser()->handleChangedLocation(NewMD);
+}
+
+void DebugValueUser::trackDebugValue() {
+  if (DebugValue)
+    MetadataTracking::track(&DebugValue, *DebugValue, *this);
+}
+
+void DebugValueUser::untrackDebugValue() {
+  if (DebugValue)
+    MetadataTracking::untrack(DebugValue);
+}
+
+void DebugValueUser::retrackDebugValue(DebugValueUser &X) {
+  assert(DebugValue == X.DebugValue && "Expected values to match");
+  if (X.DebugValue) {
+    MetadataTracking::retrack(X.DebugValue, DebugValue);
+    X.DebugValue = nullptr;
+  }
+}
+
 bool MetadataTracking::track(void *Ref, Metadata &MD, OwnerTy Owner) {
   assert(Ref && "Expected live reference");
   assert((Owner || *static_cast<Metadata **>(Ref) == &MD) &&
          "Reference without owner must be direct");
   if (auto *R = ReplaceableMetadataImpl::getOrCreate(MD)) {
     R->addRef(Ref, Owner);
     return true;
   }

 bool MetadataTracking::isReplaceable(const Metadata &MD) {
   return ReplaceableMetadataImpl::isReplaceable(MD);
 }
 
 SmallVector<Metadata *> ReplaceableMetadataImpl::getAllArgListUsers() {
   SmallVector<std::pair<OwnerTy, uint64_t> *> MDUsersWithID;
   for (auto Pair : UseMap) {
     OwnerTy Owner = Pair.second.first;
+    if (Owner.isNull())
+      continue;
     if (!isa<Metadata *>(Owner))
       continue;
     Metadata *OwnerMD = cast<Metadata *>(Owner);
     if (OwnerMD->getMetadataID() == Metadata::DIArgListKind)
       MDUsersWithID.push_back(&UseMap[Pair.first]);
   }
   llvm::sort(MDUsersWithID, [](auto UserA, auto UserB) {
     return UserA->second < UserB->second;
   });
   SmallVector<Metadata *> MDUsers;
   for (auto *UserWithID : MDUsersWithID)
     MDUsers.push_back(cast<Metadata *>(UserWithID->first));
   return MDUsers;
 }
 
+SmallVector<DPValue *> ReplaceableMetadataImpl::getAllDPValueUsers() {
+  SmallVector<std::pair<OwnerTy, uint64_t> *> DPVUsersWithID;
+  for (auto Pair : UseMap) {
+    OwnerTy Owner = Pair.second.first;
+    if (Owner.isNull())
+      continue;
+    if (!Owner.is<DebugValueUser *>())
+      continue;
+    DPVUsersWithID.push_back(&UseMap[Pair.first]);
+  }
+  llvm::sort(DPVUsersWithID, [](auto UserA, auto UserB) {
+    return UserA->second < UserB->second;
+  });
+  SmallVector<DPValue *> DPVUsers;
+  for (auto UserWithID : DPVUsersWithID)
+    DPVUsers.push_back(UserWithID->first.get<DebugValueUser *>()->getUser());
+  return DPVUsers;
+}
+
 void ReplaceableMetadataImpl::addRef(void *Ref, OwnerTy Owner) {
   bool WasInserted =
       UseMap.insert(std::make_pair(Ref, std::make_pair(Owner, NextIndex)))
           .second;
   (void)WasInserted;
   assert(WasInserted && "Expected to add a reference");
 
   ++NextIndex;
for (const auto &Pair : Uses) {
     }
 
     // Check for MetadataAsValue.
     if (isa<MetadataAsValue *>(Owner)) {
       cast<MetadataAsValue *>(Owner)->handleChangedMetadata(MD);
       continue;
     }
 
+    if (Owner.is<DebugValueUser *>()) {
+      Owner.get<DebugValueUser *>()->getUser()->handleChangedLocation(MD);
+      continue;
+    }
+
     // There's a Metadata owner -- dispatch.
     Metadata *OwnerMD = cast<Metadata *>(Owner);
     switch (OwnerMD->getMetadataID()) {
 #define HANDLE_METADATA_LEAF(CLASS)                                            \
   case Metadata::CLASS##Kind:                                                  \
     cast<CLASS>(OwnerMD)->handleChangedOperand(Pair.first, MD);                \
     continue;
 #include "llvm/IR/Metadata.def"
void ReplaceableMetadataImpl::resolveAllUses(bool ResolveUsers) {
   llvm::sort(Uses, [](const UseTy &L, const UseTy &R) {
     return L.second.second < R.second.second;
   });
   UseMap.clear();
   for (const auto &Pair : Uses) {
     auto Owner = Pair.second.first;
     if (!Owner)
       continue;
-    if (isa<MetadataAsValue *>(Owner))
+    if (!Owner.is<Metadata *>())
       continue;
 
     // Resolve MDNodes that point at this.
     auto *OwnerMD = dyn_cast_if_present<MDNode>(cast<Metadata *>(Owner));
     if (!OwnerMD)
       continue;
     if (OwnerMD->isResolved())
       continue;
     OwnerMD->decrementUnresolvedOperandCount();
   }
 }
 
 ReplaceableMetadataImpl *ReplaceableMetadataImpl::getOrCreate(Metadata &MD) {
+  if (auto ArgList = dyn_cast<DIArgList>(&MD))
+    return ArgList->Context.getOrCreateReplaceableUses();
   if (auto *N = dyn_cast<MDNode>(&MD))
     return N->isResolved() ? nullptr : N->Context.getOrCreateReplaceableUses();
   return dyn_cast<ValueAsMetadata>(&MD);
 }
 
 ReplaceableMetadataImpl *ReplaceableMetadataImpl::getIfExists(Metadata &MD) {
+  if (auto ArgList = dyn_cast<DIArgList>(&MD)) {
+    return ArgList->Context.getOrCreateReplaceableUses();
+  }
   if (auto *N = dyn_cast<MDNode>(&MD))
     return N->isResolved() ? nullptr : N->Context.getReplaceableUses();
   return dyn_cast<ValueAsMetadata>(&MD);
 }
 
 bool ReplaceableMetadataImpl::isReplaceable(const Metadata &MD) {
+  if (isa<DIArgList>(&MD))
+    return true;
   if (auto *N = dyn_cast<MDNode>(&MD))
     return !N->isResolved();
   return isa<ValueAsMetadata>(&MD);
 }
 
 static DISubprogram *getLocalFunctionMetadata(Value *V) {
   assert(V && "Expected value");
   if (auto *A = dyn_cast<Argument>(V)) {

llvm/unittests/IR/DebugInfoTest.cpp

TEST(AssignmentTrackingTest, InstrMethods) {
   // store0 !x        store0 !x
   {
     Stores[0]->dropUnknownNonDebugMetadata();
     Metadata *NewID0 = Stores[0]->getMetadata(LLVMContext::MD_DIAssignID);
     EXPECT_NE(NewID0, nullptr);
   }
 }
 
+// Test some very straight-forward operations on DPValues -- these are
+// dbg.values that have been converted to a non-instruction format.
+TEST(MetadataTest, ConvertDbgToDPValue) {
+  LLVMContext C;
+  std::unique_ptr<Module> M = parseIR(C, R"(
+    define i16 @f(i16 %a) !dbg !6 {
+      call void @llvm.dbg.value(metadata i16 %a, metadata !9, metadata !DIExpression()), !dbg !11
+      %b = add i16 %a, 1, !dbg !11
+      call void @llvm.dbg.value(metadata i16 %b, metadata !9, metadata !DIExpression()), !dbg !11
+      ret i16 0, !dbg !11
+
+    exit:
+      %c = add i16 %b, 1, !dbg !11
+      ret i16 0, !dbg !11
+    }
+    declare void @llvm.dbg.value(metadata, metadata, metadata) #0
+    attributes #0 = { nounwind readnone speculatable willreturn }
+
+    !llvm.dbg.cu = !{!0}
+    !llvm.module.flags = !{!5}
+
+    !0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
+    !1 = !DIFile(filename: "t.ll", directory: "/")
+    !2 = !{}
+    !5 = !{i32 2, !"Debug Info Version", i32 3}
+    !6 = distinct !DISubprogram(name: "foo", linkageName: "foo", scope: null, file: !1, line: 1, type: !7, scopeLine: 1, spFlags: DISPFlagDefinition | DISPFlagOptimized, unit: !0, retainedNodes: !8)
+    !7 = !DISubroutineType(types: !2)
+    !8 = !{!9}
+    !9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
+    !10 = !DIBasicType(name: "ty16", size: 16, encoding: DW_ATE_unsigned)
+    !11 = !DILocation(line: 1, column: 1, scope: !6)
+)");
+
+  // Find the first dbg.value,
+  Instruction &I = *M->getFunction("f")->getEntryBlock().getFirstNonPHI();
+  const DILocalVariable *Var = nullptr;
+  const DIExpression *Expr = nullptr;
+  const DILocation *Loc = nullptr;
+  const Metadata *MLoc = nullptr;
+  DPValue *DPV1 = nullptr;
+  {
+    DbgValueInst *DPI = dyn_cast<DbgValueInst>(&I);
+    ASSERT_TRUE(DPI);
+    Var = DPI->getVariable();
+    Expr = DPI->getExpression();
+    Loc = DPI->getDebugLoc().get();
+    MLoc = DPI->getRawLocation();
+
+    // Test the creation of a DPValue and it's conversion back to a dbg.value.
+    DPV1 = new DPValue(DPI);
+    EXPECT_EQ(DPV1->getVariable(), Var);
+    EXPECT_EQ(DPV1->getExpression(), Expr);
+    EXPECT_EQ(DPV1->getDebugLoc().get(), Loc);
+    EXPECT_EQ(DPV1->getRawLocation(), MLoc);
+
+    // Erase dbg.value,
+    DPI->eraseFromParent();
+    // Re-create from DPV1, inserting at front.
+    DPV1->createDebugIntrinsic(&*M,
+                               &M->getFunction("f")->getEntryBlock().front());
+
+    Instruction *NewDPI = &M->getFunction("f")->getEntryBlock().front();
+    DbgValueInst *DPI2 = dyn_cast<DbgValueInst>(NewDPI);
+    ASSERT_TRUE(DPI2);
+    EXPECT_EQ(DPI2->getVariable(), Var);
+    EXPECT_EQ(DPI2->getExpression(), Expr);
+    EXPECT_EQ(DPI2->getDebugLoc().get(), Loc);
+    EXPECT_EQ(DPI2->getRawLocation(), MLoc);
+  }
+
+  // Fetch the second dbg.value, convert it to a DPValue,
+  BasicBlock::iterator It = M->getFunction("f")->getEntryBlock().begin();
+  It = std::next(std::next(It));
+  DbgValueInst *DPI3 = dyn_cast<DbgValueInst>(It);
+  ASSERT_TRUE(DPI3);
+  DPValue *DPV2 = new DPValue(DPI3);
+
+  // These dbg.values are supposed to refer to different values.
+  EXPECT_NE(DPV1->getRawLocation(), DPV2->getRawLocation());
+
+  // Try manipulating DPValues and markers in the exit block.
+  BasicBlock *ExitBlock = &*std::next(M->getFunction("f")->getEntryBlock().getIterator());
+  Instruction *FirstInst = &ExitBlock->front();
+  Instruction *RetInst = &*std::next(FirstInst->getIterator());
+
+  // Set-up DPMarkers in this block.
+  FirstInst->DbgMarker = new DPMarker();
+  FirstInst->DbgMarker->MarkedInstr = FirstInst;
+  RetInst->DbgMarker = new DPMarker();
+  RetInst->DbgMarker->MarkedInstr = RetInst;
+
+  // Insert DPValues into markers, order should come out DPV2, DPV1.
+  FirstInst->DbgMarker->insertDPValue(DPV1, false);
+  FirstInst->DbgMarker->insertDPValue(DPV2, true);
+  unsigned int ItCount = 0;
+  for (DPValue &Item : FirstInst->DbgMarker->getDbgValueRange()) {
+    EXPECT_TRUE((&Item == DPV2 && ItCount == 0) ||
+              (&Item == DPV1 && ItCount == 1));
+    EXPECT_EQ(Item.getMarker(), FirstInst->DbgMarker);
+    ++ItCount;
+  }
+
+  // Clone them onto the second marker -- should allocate new DPVs.
+  RetInst->DbgMarker->cloneDebugInfoFrom(FirstInst->DbgMarker, std::nullopt, false);
+  EXPECT_EQ(RetInst->DbgMarker->StoredDPValues.size(), 2);
+  ItCount = 0;
+  // Check these things store the same information; but that they're not the same
+  // objects.
+  for (DPValue &Item : RetInst->DbgMarker->getDbgValueRange()) {
+    EXPECT_TRUE((Item.getRawLocation() == DPV2->getRawLocation() && ItCount == 0) ||
+                (Item.getRawLocation() == DPV1->getRawLocation() && ItCount == 1));
+    
+    EXPECT_EQ(Item.getMarker(), RetInst->DbgMarker);
+    EXPECT_NE(&Item, DPV1);
+    EXPECT_NE(&Item, DPV2);
+    ++ItCount;
+  }
+
+  RetInst->DbgMarker->dropDPValues();
+  EXPECT_EQ(RetInst->DbgMarker->StoredDPValues.size(), 0);
+
+  // Try cloning one single DPValue.
+  auto DIIt = std::next(FirstInst->DbgMarker->getDbgValueRange().begin());
+  RetInst->DbgMarker->cloneDebugInfoFrom(FirstInst->DbgMarker, DIIt, false);
+  EXPECT_EQ(RetInst->DbgMarker->StoredDPValues.size(), 1);
+  // The second DPValue should have been cloned; it should have the same values
+  // as DPV1.
+  EXPECT_EQ(RetInst->DbgMarker->StoredDPValues.begin()->getRawLocation(),
+            DPV1->getRawLocation());
+  // We should be able to drop individual DPValues.
+  RetInst->DbgMarker->dropOneDPValue(&*RetInst->DbgMarker->StoredDPValues.begin());
+
+  // "Aborb" a DPMarker: this means pretend that the instruction it's attached
+  // to is disappearing so it needs to be transferred into "this" marker.
+  RetInst->DbgMarker->absorbDebugValues(*FirstInst->DbgMarker, true);
+  EXPECT_EQ(RetInst->DbgMarker->StoredDPValues.size(), 2);
+  // Should be the DPV1 and DPV2 objects.
+  ItCount = 0;
+  for (DPValue &Item : RetInst->DbgMarker->getDbgValueRange()) {
+    EXPECT_TRUE((&Item == DPV2 && ItCount == 0) ||
+              (&Item == DPV1 && ItCount == 1));
+    EXPECT_EQ(Item.getMarker(), RetInst->DbgMarker);
+    ++ItCount;
+  }
+
+  // Finally -- there are two DPValues left over. If we remove evrything in the
+  // basic block, then they should sink down into the "TrailingDPValues"
+  // container for dangling debug-info. Future facilities will restore them
+  // back when a terminator is inserted.
+  FirstInst->DbgMarker->removeMarker();
+  FirstInst->eraseFromParent();
+  RetInst->DbgMarker->removeMarker();
+  RetInst->eraseFromParent();
+
+  EXPECT_EQ(ExitBlock->TrailingDPValues.StoredDPValues.size(), 2);
+  // Test again that it's those two DPValues, DPV1 and DPV2.
+  ItCount = 0;
+  for (DPValue &Item : ExitBlock->TrailingDPValues.getDbgValueRange()) {
+    EXPECT_TRUE((&Item == DPV2 && ItCount == 0) ||
+              (&Item == DPV1 && ItCount == 1));
+    EXPECT_EQ(Item.getMarker(), &ExitBlock->TrailingDPValues);
+    ++ItCount;
+  }
+}
+
 } // end namespace

llvm/unittests/Transforms/Utils/LocalTest.cpp

TEST(Local, CanReplaceOperandWithVariable) {
   CallInst *GCRoot = B.CreateIntrinsic(Intrinsic::gcroot, {},
     {Alloca, Constant::getNullValue(PtrPtr)});
   EXPECT_TRUE(canReplaceOperandWithVariable(GCRoot, 0)); // Alloca
   EXPECT_FALSE(canReplaceOperandWithVariable(GCRoot, 1));
   EXPECT_FALSE(canReplaceOperandWithVariable(GCRoot, 2));
 
   BB0->dropAllReferences();
 }
+
+TEST(Local, ReplaceDPValue) {
+  LLVMContext C;
+
+  // Test that RAUW also replaces the operands of DPValue objects, i.e.
+  // non-instruction stored debugging information.
+  std::unique_ptr<Module> M = parseIR(C,
+                                      R"(
+      declare void @llvm.dbg.value(metadata, metadata, metadata)
+      define void @f(i32 %a) !dbg !8 {
+      entry:
+        %foo = add i32 %a, 1, !dbg !13
+        %bar = add i32 %foo, 0, !dbg !13
+        call void @llvm.dbg.value(metadata i32 %bar, metadata !11, metadata !DIExpression()), !dbg !13
+        ret void, !dbg !14
+      }
+      !llvm.dbg.cu = !{!0}
+      !llvm.module.flags = !{!3, !4}
+      !0 = distinct !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang version 6.0.0", isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
+      !1 = !DIFile(filename: "t2.c", directory: "foo")
+      !2 = !{}
+      !3 = !{i32 2, !"Dwarf Version", i32 4}
+      !4 = !{i32 2, !"Debug Info Version", i32 3}
+      !8 = distinct !DISubprogram(name: "f", scope: !1, file: !1, line: 1, type: !9, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, unit: !0, retainedNodes: !2)
+      !9 = !DISubroutineType(types: !10)
+      !10 = !{null}
+      !11 = !DILocalVariable(name: "x", scope: !8, file: !1, line: 2, type: !12)
+      !12 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)
+      !13 = !DILocation(line: 2, column: 7, scope: !8)
+      !14 = !DILocation(line: 3, column: 1, scope: !8)
+      )");
+  auto *GV = M->getNamedValue("f");
+  ASSERT_TRUE(GV);
+  auto *F = dyn_cast<Function>(GV);
+  ASSERT_TRUE(F);
+  BasicBlock::iterator It = F->front().begin();
+  Instruction *FooInst = &*It;
+  It = std::next(It);
+  Instruction *BarInst = &*It;
+  It = std::next(It);
+  DbgValueInst *DVI = dyn_cast<DbgValueInst>(It);
+  ASSERT_TRUE(DVI);
+  It = std::next(It);
+  Instruction *RetInst = &*It;
+
+  // Convert DVI into a DPValue.
+  RetInst->DbgMarker = new DPMarker();
+  RetInst->DbgMarker->MarkedInstr = RetInst;
+  DPValue *DPV = new DPValue(DVI);
+  RetInst->DbgMarker->insertDPValue(DPV, false);
+  // ... and erase the dbg.value.
+  DVI->eraseFromParent();
+
+  // DPV should originally refer to %bar,
+  EXPECT_EQ(DPV->getVariableLocationOp(0), BarInst);
+
+  // Now try to replace the computation of %bar with %foo -- this should cause
+  // the DPValue's to have it's operand updated beneath it.
+  BarInst->replaceAllUsesWith(FooInst);
+  // Check DPV now points at %foo.
+  EXPECT_EQ(DPV->getVariableLocationOp(0), FooInst);
+
+  // Teardown.
+  RetInst->DbgMarker->eraseFromParent();
+}
+

llvm/utils/gn/secondary/llvm/lib/IR/BUILD.gn

sources = [
     "Constants.cpp",
     "ConvergenceVerifier.cpp",
     "Core.cpp",
     "CycleInfo.cpp",
     "DIBuilder.cpp",
     "DataLayout.cpp",
     "DebugInfo.cpp",
     "DebugInfoMetadata.cpp",
+    "DebugProgramInstruction.cpp",
     "DebugLoc.cpp",
     "DiagnosticHandler.cpp",
     "DiagnosticInfo.cpp",
     "DiagnosticPrinter.cpp",
     "Dominators.cpp",
     "EHPersonalities.cpp",
     "FPEnv.cpp",
     "Function.cpp",