xref: /freebsd/contrib/llvm-project/llvm/include/llvm/IR/DebugProgramInstruction.h (revision 0fca6ea1d4eea4c934cfff25ac9ee8ad6fe95583)
1  //===-- llvm/DebugProgramInstruction.h - Stream of debug info ---*- C++ -*-===//
2  //
3  // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4  // See https://llvm.org/LICENSE.txt for license information.
5  // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6  //
7  //===----------------------------------------------------------------------===//
8  //
9  // Data structures for storing variable assignment information in LLVM. In the
10  // dbg.value design, a dbg.value intrinsic specifies the position in a block
11  // a source variable take on an LLVM Value:
12  //
13  //    %foo = add i32 1, %0
14  //    dbg.value(metadata i32 %foo, ...)
15  //    %bar = void call @ext(%foo);
16  //
17  // and all information is stored in the Value / Metadata hierachy defined
18  // elsewhere in LLVM. In the "DbgRecord" design, each instruction /may/ have a
19  // connection with a DbgMarker, which identifies a position immediately before
20  // the instruction, and each DbgMarker /may/ then have connections to DbgRecords
21  // which record the variable assignment information. To illustrate:
22  //
23  //    %foo = add i32 1, %0
24  //       ; foo->DebugMarker == nullptr
25  //       ;; There are no variable assignments / debug records "in front" of
26  //       ;; the instruction for %foo, therefore it has no DebugMarker.
27  //    %bar = void call @ext(%foo)
28  //       ; bar->DebugMarker = {
29  //       ;   StoredDbgRecords = {
30  //       ;     DbgVariableRecord(metadata i32 %foo, ...)
31  //       ;   }
32  //       ; }
33  //       ;; There is a debug-info record in front of the %bar instruction,
34  //       ;; thus it points at a DbgMarker object. That DbgMarker contains a
35  //       ;; DbgVariableRecord in its ilist, storing the equivalent information
36  //       ;; to the dbg.value above: the Value, DILocalVariable, etc.
37  //
38  // This structure separates the two concerns of the position of the debug-info
39  // in the function, and the Value that it refers to. It also creates a new
40  // "place" in-between the Value / Metadata hierachy where we can customise
41  // storage and allocation techniques to better suite debug-info workloads.
42  // NB: as of the initial prototype, none of that has actually been attempted
43  // yet.
44  //
45  //===----------------------------------------------------------------------===//
46  
47  #ifndef LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
48  #define LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
49  
50  #include "llvm/ADT/ilist.h"
51  #include "llvm/ADT/ilist_node.h"
52  #include "llvm/ADT/iterator.h"
53  #include "llvm/IR/DbgVariableFragmentInfo.h"
54  #include "llvm/IR/DebugLoc.h"
55  #include "llvm/IR/Instruction.h"
56  #include "llvm/IR/SymbolTableListTraits.h"
57  #include "llvm/Support/Casting.h"
58  
59  namespace llvm {
60  
61  class Instruction;
62  class BasicBlock;
63  class MDNode;
64  class Module;
65  class DbgVariableIntrinsic;
66  class DbgInfoIntrinsic;
67  class DbgLabelInst;
68  class DIAssignID;
69  class DbgMarker;
70  class DbgVariableRecord;
71  class raw_ostream;
72  
73  /// A typed tracking MDNode reference that does not require a definition for its
74  /// parameter type. Necessary to avoid including DebugInfoMetadata.h, which has
75  /// a significant impact on compile times if included in this file.
76  template <typename T> class DbgRecordParamRef {
77    TrackingMDNodeRef Ref;
78  
79  public:
80  public:
81    DbgRecordParamRef() = default;
82  
83    /// Construct from the templated type.
84    DbgRecordParamRef(const T *Param);
85  
86    /// Construct from an \a MDNode.
87    ///
88    /// Note: if \c Param does not have the template type, a verifier check will
89    /// fail, and accessors will crash.  However, construction from other nodes
90    /// is supported in order to handle forward references when reading textual
91    /// IR.
92    explicit DbgRecordParamRef(const MDNode *Param);
93  
94    /// Get the underlying type.
95    ///
96    /// \pre !*this or \c isa<T>(getAsMDNode()).
97    /// @{
98    T *get() const;
99    operator T *() const { return get(); }
100    T *operator->() const { return get(); }
101    T &operator*() const { return *get(); }
102    /// @}
103  
104    /// Check for null.
105    ///
106    /// Check for null in a way that is safe with broken debug info.
107    explicit operator bool() const { return Ref; }
108  
109    /// Return \c this as a \a MDNode.
getAsMDNode()110    MDNode *getAsMDNode() const { return Ref; }
111  
112    bool operator==(const DbgRecordParamRef &Other) const {
113      return Ref == Other.Ref;
114    }
115    bool operator!=(const DbgRecordParamRef &Other) const {
116      return Ref != Other.Ref;
117    }
118  };
119  
120  /// Base class for non-instruction debug metadata records that have positions
121  /// within IR. Features various methods copied across from the Instruction
122  /// class to aid ease-of-use. DbgRecords should always be linked into a
123  /// DbgMarker's StoredDbgRecords list. The marker connects a DbgRecord back to
124  /// its position in the BasicBlock.
125  ///
126  /// We need a discriminator for dyn/isa casts. In order to avoid paying for a
127  /// vtable for "virtual" functions too, subclasses must add a new discriminator
128  /// value (RecordKind) and cases to a few functions in the base class:
129  ///   deleteRecord
130  ///   clone
131  ///   isIdenticalToWhenDefined
132  ///   both print methods
133  ///   createDebugIntrinsic
134  class DbgRecord : public ilist_node<DbgRecord> {
135  public:
136    /// Marker that this DbgRecord is linked into.
137    DbgMarker *Marker = nullptr;
138    /// Subclass discriminator.
139    enum Kind : uint8_t { ValueKind, LabelKind };
140  
141  protected:
142    DebugLoc DbgLoc;
143    Kind RecordKind; ///< Subclass discriminator.
144  
145  public:
DbgRecord(Kind RecordKind,DebugLoc DL)146    DbgRecord(Kind RecordKind, DebugLoc DL)
147        : DbgLoc(DL), RecordKind(RecordKind) {}
148  
149    /// Methods that dispatch to subclass implementations. These need to be
150    /// manually updated when a new subclass is added.
151    ///@{
152    void deleteRecord();
153    DbgRecord *clone() const;
154    void print(raw_ostream &O, bool IsForDebug = false) const;
155    void print(raw_ostream &O, ModuleSlotTracker &MST, bool IsForDebug) const;
156    bool isIdenticalToWhenDefined(const DbgRecord &R) const;
157    /// Convert this DbgRecord back into an appropriate llvm.dbg.* intrinsic.
158    /// \p InsertBefore Optional position to insert this intrinsic.
159    /// \returns A new llvm.dbg.* intrinsic representiung this DbgRecord.
160    DbgInfoIntrinsic *createDebugIntrinsic(Module *M,
161                                           Instruction *InsertBefore) const;
162    ///@}
163  
164    /// Same as isIdenticalToWhenDefined but checks DebugLoc too.
165    bool isEquivalentTo(const DbgRecord &R) const;
166  
getRecordKind()167    Kind getRecordKind() const { return RecordKind; }
168  
setMarker(DbgMarker * M)169    void setMarker(DbgMarker *M) { Marker = M; }
170  
getMarker()171    DbgMarker *getMarker() { return Marker; }
getMarker()172    const DbgMarker *getMarker() const { return Marker; }
173  
174    BasicBlock *getBlock();
175    const BasicBlock *getBlock() const;
176  
177    Function *getFunction();
178    const Function *getFunction() const;
179  
180    Module *getModule();
181    const Module *getModule() const;
182  
183    LLVMContext &getContext();
184    const LLVMContext &getContext() const;
185  
186    const Instruction *getInstruction() const;
187    const BasicBlock *getParent() const;
188    BasicBlock *getParent();
189  
190    void removeFromParent();
191    void eraseFromParent();
192  
getNextNode()193    DbgRecord *getNextNode() { return &*std::next(getIterator()); }
getPrevNode()194    DbgRecord *getPrevNode() { return &*std::prev(getIterator()); }
195    void insertBefore(DbgRecord *InsertBefore);
196    void insertAfter(DbgRecord *InsertAfter);
197    void moveBefore(DbgRecord *MoveBefore);
198    void moveAfter(DbgRecord *MoveAfter);
199  
getDebugLoc()200    DebugLoc getDebugLoc() const { return DbgLoc; }
setDebugLoc(DebugLoc Loc)201    void setDebugLoc(DebugLoc Loc) { DbgLoc = std::move(Loc); }
202  
203    void dump() const;
204  
205    using self_iterator = simple_ilist<DbgRecord>::iterator;
206    using const_self_iterator = simple_ilist<DbgRecord>::const_iterator;
207  
208  protected:
209    /// Similarly to Value, we avoid paying the cost of a vtable
210    /// by protecting the dtor and having deleteRecord dispatch
211    /// cleanup.
212    /// Use deleteRecord to delete a generic record.
213    ~DbgRecord() = default;
214  };
215  
216  inline raw_ostream &operator<<(raw_ostream &OS, const DbgRecord &R) {
217    R.print(OS);
218    return OS;
219  }
220  
221  /// Records a position in IR for a source label (DILabel). Corresponds to the
222  /// llvm.dbg.label intrinsic.
223  class DbgLabelRecord : public DbgRecord {
224    DbgRecordParamRef<DILabel> Label;
225  
226    /// This constructor intentionally left private, so that it is only called via
227    /// "createUnresolvedDbgLabelRecord", which clearly expresses that it is for
228    /// parsing only.
229    DbgLabelRecord(MDNode *Label, MDNode *DL);
230  
231  public:
232    DbgLabelRecord(DILabel *Label, DebugLoc DL);
233  
234    /// For use during parsing; creates a DbgLabelRecord from as-of-yet unresolved
235    /// MDNodes. Trying to access the resulting DbgLabelRecord's fields before
236    /// they are resolved, or if they resolve to the wrong type, will result in a
237    /// crash.
238    static DbgLabelRecord *createUnresolvedDbgLabelRecord(MDNode *Label,
239                                                          MDNode *DL);
240  
241    DbgLabelRecord *clone() const;
242    void print(raw_ostream &O, bool IsForDebug = false) const;
243    void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
244    DbgLabelInst *createDebugIntrinsic(Module *M,
245                                       Instruction *InsertBefore) const;
246  
setLabel(DILabel * NewLabel)247    void setLabel(DILabel *NewLabel) { Label = NewLabel; }
getLabel()248    DILabel *getLabel() const { return Label.get(); }
getRawLabel()249    MDNode *getRawLabel() const { return Label.getAsMDNode(); };
250  
251    /// Support type inquiry through isa, cast, and dyn_cast.
classof(const DbgRecord * E)252    static bool classof(const DbgRecord *E) {
253      return E->getRecordKind() == LabelKind;
254    }
255  };
256  
257  /// Record of a variable value-assignment, aka a non instruction representation
258  /// of the dbg.value intrinsic.
259  ///
260  /// This class inherits from DebugValueUser to allow LLVM's metadata facilities
261  /// to update our references to metadata beneath our feet.
262  class DbgVariableRecord : public DbgRecord, protected DebugValueUser {
263    friend class DebugValueUser;
264  
265  public:
266    enum class LocationType : uint8_t {
267      Declare,
268      Value,
269      Assign,
270  
271      End, ///< Marks the end of the concrete types.
272      Any, ///< To indicate all LocationTypes in searches.
273    };
274    /// Classification of the debug-info record that this DbgVariableRecord
275    /// represents. Essentially, "does this correspond to a dbg.value,
276    /// dbg.declare, or dbg.assign?".
277    /// FIXME: We could use spare padding bits from DbgRecord for this.
278    LocationType Type;
279  
280    // NB: there is no explicit "Value" field in this class, it's effectively the
281    // DebugValueUser superclass instead. The referred to Value can either be a
282    // ValueAsMetadata or a DIArgList.
283  
284    DbgRecordParamRef<DILocalVariable> Variable;
285    DbgRecordParamRef<DIExpression> Expression;
286    DbgRecordParamRef<DIExpression> AddressExpression;
287  
288  public:
289    /// Create a new DbgVariableRecord representing the intrinsic \p DVI, for
290    /// example the assignment represented by a dbg.value.
291    DbgVariableRecord(const DbgVariableIntrinsic *DVI);
292    DbgVariableRecord(const DbgVariableRecord &DVR);
293    /// Directly construct a new DbgVariableRecord representing a dbg.value
294    /// intrinsic assigning \p Location to the DV / Expr / DI variable.
295    DbgVariableRecord(Metadata *Location, DILocalVariable *DV, DIExpression *Expr,
296                      const DILocation *DI,
297                      LocationType Type = LocationType::Value);
298    DbgVariableRecord(Metadata *Value, DILocalVariable *Variable,
299                      DIExpression *Expression, DIAssignID *AssignID,
300                      Metadata *Address, DIExpression *AddressExpression,
301                      const DILocation *DI);
302  
303  private:
304    /// Private constructor for creating new instances during parsing only. Only
305    /// called through `createUnresolvedDbgVariableRecord` below, which makes
306    /// clear that this is used for parsing only, and will later return a subclass
307    /// depending on which Type is passed.
308    DbgVariableRecord(LocationType Type, Metadata *Val, MDNode *Variable,
309                      MDNode *Expression, MDNode *AssignID, Metadata *Address,
310                      MDNode *AddressExpression, MDNode *DI);
311  
312  public:
313    /// Used to create DbgVariableRecords during parsing, where some metadata
314    /// references may still be unresolved. Although for some fields a generic
315    /// `Metadata*` argument is accepted for forward type-references, the verifier
316    /// and accessors will reject incorrect types later on. The function is used
317    /// for all types of DbgVariableRecords for simplicity while parsing, but
318    /// asserts if any necessary fields are empty or unused fields are not empty,
319    /// i.e. if the #dbg_assign fields are used for a non-dbg-assign type.
320    static DbgVariableRecord *
321    createUnresolvedDbgVariableRecord(LocationType Type, Metadata *Val,
322                                      MDNode *Variable, MDNode *Expression,
323                                      MDNode *AssignID, Metadata *Address,
324                                      MDNode *AddressExpression, MDNode *DI);
325  
326    static DbgVariableRecord *
327    createDVRAssign(Value *Val, DILocalVariable *Variable,
328                    DIExpression *Expression, DIAssignID *AssignID,
329                    Value *Address, DIExpression *AddressExpression,
330                    const DILocation *DI);
331    static DbgVariableRecord *
332    createLinkedDVRAssign(Instruction *LinkedInstr, Value *Val,
333                          DILocalVariable *Variable, DIExpression *Expression,
334                          Value *Address, DIExpression *AddressExpression,
335                          const DILocation *DI);
336  
337    static DbgVariableRecord *createDbgVariableRecord(Value *Location,
338                                                      DILocalVariable *DV,
339                                                      DIExpression *Expr,
340                                                      const DILocation *DI);
341    static DbgVariableRecord *
342    createDbgVariableRecord(Value *Location, DILocalVariable *DV,
343                            DIExpression *Expr, const DILocation *DI,
344                            DbgVariableRecord &InsertBefore);
345    static DbgVariableRecord *createDVRDeclare(Value *Address,
346                                               DILocalVariable *DV,
347                                               DIExpression *Expr,
348                                               const DILocation *DI);
349    static DbgVariableRecord *
350    createDVRDeclare(Value *Address, DILocalVariable *DV, DIExpression *Expr,
351                     const DILocation *DI, DbgVariableRecord &InsertBefore);
352  
353    /// Iterator for ValueAsMetadata that internally uses direct pointer iteration
354    /// over either a ValueAsMetadata* or a ValueAsMetadata**, dereferencing to the
355    /// ValueAsMetadata .
356    class location_op_iterator
357        : public iterator_facade_base<location_op_iterator,
358                                      std::bidirectional_iterator_tag, Value *> {
359      PointerUnion<ValueAsMetadata *, ValueAsMetadata **> I;
360  
361    public:
location_op_iterator(ValueAsMetadata * SingleIter)362      location_op_iterator(ValueAsMetadata *SingleIter) : I(SingleIter) {}
location_op_iterator(ValueAsMetadata ** MultiIter)363      location_op_iterator(ValueAsMetadata **MultiIter) : I(MultiIter) {}
364  
location_op_iterator(const location_op_iterator & R)365      location_op_iterator(const location_op_iterator &R) : I(R.I) {}
366      location_op_iterator &operator=(const location_op_iterator &R) {
367        I = R.I;
368        return *this;
369      }
370      bool operator==(const location_op_iterator &RHS) const {
371        return I == RHS.I;
372      }
373      const Value *operator*() const {
374        ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
375                                   ? I.get<ValueAsMetadata *>()
376                                   : *I.get<ValueAsMetadata **>();
377        return VAM->getValue();
378      };
379      Value *operator*() {
380        ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
381                                   ? I.get<ValueAsMetadata *>()
382                                   : *I.get<ValueAsMetadata **>();
383        return VAM->getValue();
384      }
385      location_op_iterator &operator++() {
386        if (I.is<ValueAsMetadata *>())
387          I = I.get<ValueAsMetadata *>() + 1;
388        else
389          I = I.get<ValueAsMetadata **>() + 1;
390        return *this;
391      }
392      location_op_iterator &operator--() {
393        if (I.is<ValueAsMetadata *>())
394          I = I.get<ValueAsMetadata *>() - 1;
395        else
396          I = I.get<ValueAsMetadata **>() - 1;
397        return *this;
398      }
399    };
400  
isDbgDeclare()401    bool isDbgDeclare() { return Type == LocationType::Declare; }
isDbgValue()402    bool isDbgValue() { return Type == LocationType::Value; }
403  
404    /// Get the locations corresponding to the variable referenced by the debug
405    /// info intrinsic.  Depending on the intrinsic, this could be the
406    /// variable's value or its address.
407    iterator_range<location_op_iterator> location_ops() const;
408  
409    Value *getVariableLocationOp(unsigned OpIdx) const;
410  
411    void replaceVariableLocationOp(Value *OldValue, Value *NewValue,
412                                   bool AllowEmpty = false);
413    void replaceVariableLocationOp(unsigned OpIdx, Value *NewValue);
414    /// Adding a new location operand will always result in this intrinsic using
415    /// an ArgList, and must always be accompanied by a new expression that uses
416    /// the new operand.
417    void addVariableLocationOps(ArrayRef<Value *> NewValues,
418                                DIExpression *NewExpr);
419  
420    unsigned getNumVariableLocationOps() const;
421  
hasArgList()422    bool hasArgList() const { return isa<DIArgList>(getRawLocation()); }
423    /// Returns true if this DbgVariableRecord has no empty MDNodes in its
424    /// location list.
hasValidLocation()425    bool hasValidLocation() const { return getVariableLocationOp(0) != nullptr; }
426  
427    /// Does this describe the address of a local variable. True for dbg.addr
428    /// and dbg.declare, but not dbg.value, which describes its value.
isAddressOfVariable()429    bool isAddressOfVariable() const { return Type == LocationType::Declare; }
getType()430    LocationType getType() const { return Type; }
431  
432    void setKillLocation();
433    bool isKillLocation() const;
434  
setVariable(DILocalVariable * NewVar)435    void setVariable(DILocalVariable *NewVar) { Variable = NewVar; }
getVariable()436    DILocalVariable *getVariable() const { return Variable.get(); };
getRawVariable()437    MDNode *getRawVariable() const { return Variable.getAsMDNode(); }
438  
setExpression(DIExpression * NewExpr)439    void setExpression(DIExpression *NewExpr) { Expression = NewExpr; }
getExpression()440    DIExpression *getExpression() const { return Expression.get(); }
getRawExpression()441    MDNode *getRawExpression() const { return Expression.getAsMDNode(); }
442  
443    /// Returns the metadata operand for the first location description. i.e.,
444    /// dbg intrinsic dbg.value,declare operand and dbg.assign 1st location
445    /// operand (the "value componenet"). Note the operand (singular) may be
446    /// a DIArgList which is a list of values.
getRawLocation()447    Metadata *getRawLocation() const { return DebugValues[0]; }
448  
449    Value *getValue(unsigned OpIdx = 0) const {
450      return getVariableLocationOp(OpIdx);
451    }
452  
453    /// Use of this should generally be avoided; instead,
454    /// replaceVariableLocationOp and addVariableLocationOps should be used where
455    /// possible to avoid creating invalid state.
setRawLocation(Metadata * NewLocation)456    void setRawLocation(Metadata *NewLocation) {
457      assert((isa<ValueAsMetadata>(NewLocation) || isa<DIArgList>(NewLocation) ||
458              isa<MDNode>(NewLocation)) &&
459             "Location for a DbgVariableRecord must be either ValueAsMetadata or "
460             "DIArgList");
461      resetDebugValue(0, NewLocation);
462    }
463  
464    std::optional<DbgVariableFragmentInfo> getFragment() const;
465    /// Get the FragmentInfo for the variable if it exists, otherwise return a
466    /// FragmentInfo that covers the entire variable if the variable size is
467    /// known, otherwise return a zero-sized fragment.
getFragmentOrEntireVariable()468    DbgVariableFragmentInfo getFragmentOrEntireVariable() const {
469      if (auto Frag = getFragment())
470        return *Frag;
471      if (auto Sz = getFragmentSizeInBits())
472        return {*Sz, 0};
473      return {0, 0};
474    }
475    /// Get the size (in bits) of the variable, or fragment of the variable that
476    /// is described.
477    std::optional<uint64_t> getFragmentSizeInBits() const;
478  
isEquivalentTo(const DbgVariableRecord & Other)479    bool isEquivalentTo(const DbgVariableRecord &Other) const {
480      return DbgLoc == Other.DbgLoc && isIdenticalToWhenDefined(Other);
481    }
482    // Matches the definition of the Instruction version, equivalent to above but
483    // without checking DbgLoc.
isIdenticalToWhenDefined(const DbgVariableRecord & Other)484    bool isIdenticalToWhenDefined(const DbgVariableRecord &Other) const {
485      return std::tie(Type, DebugValues, Variable, Expression,
486                      AddressExpression) ==
487             std::tie(Other.Type, Other.DebugValues, Other.Variable,
488                      Other.Expression, Other.AddressExpression);
489    }
490  
491    /// @name DbgAssign Methods
492    /// @{
isDbgAssign()493    bool isDbgAssign() const { return getType() == LocationType::Assign; }
494  
495    Value *getAddress() const;
getRawAddress()496    Metadata *getRawAddress() const {
497      return isDbgAssign() ? DebugValues[1] : DebugValues[0];
498    }
getRawAssignID()499    Metadata *getRawAssignID() const { return DebugValues[2]; }
500    DIAssignID *getAssignID() const;
getAddressExpression()501    DIExpression *getAddressExpression() const { return AddressExpression.get(); }
getRawAddressExpression()502    MDNode *getRawAddressExpression() const {
503      return AddressExpression.getAsMDNode();
504    }
setAddressExpression(DIExpression * NewExpr)505    void setAddressExpression(DIExpression *NewExpr) {
506      AddressExpression = NewExpr;
507    }
508    void setAssignId(DIAssignID *New);
setAddress(Value * V)509    void setAddress(Value *V) { resetDebugValue(1, ValueAsMetadata::get(V)); }
510    /// Kill the address component.
511    void setKillAddress();
512    /// Check whether this kills the address component. This doesn't take into
513    /// account the position of the intrinsic, therefore a returned value of false
514    /// does not guarentee the address is a valid location for the variable at the
515    /// intrinsic's position in IR.
516    bool isKillAddress() const;
517  
518    /// @}
519  
520    DbgVariableRecord *clone() const;
521    /// Convert this DbgVariableRecord back into a dbg.value intrinsic.
522    /// \p InsertBefore Optional position to insert this intrinsic.
523    /// \returns A new dbg.value intrinsic representiung this DbgVariableRecord.
524    DbgVariableIntrinsic *createDebugIntrinsic(Module *M,
525                                               Instruction *InsertBefore) const;
526  
527    /// Handle changes to the location of the Value(s) that we refer to happening
528    /// "under our feet".
529    void handleChangedLocation(Metadata *NewLocation);
530  
531    void print(raw_ostream &O, bool IsForDebug = false) const;
532    void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
533  
534    /// Support type inquiry through isa, cast, and dyn_cast.
classof(const DbgRecord * E)535    static bool classof(const DbgRecord *E) {
536      return E->getRecordKind() == ValueKind;
537    }
538  };
539  
540  /// Filter the DbgRecord range to DbgVariableRecord types only and downcast.
541  static inline auto
filterDbgVars(iterator_range<simple_ilist<DbgRecord>::iterator> R)542  filterDbgVars(iterator_range<simple_ilist<DbgRecord>::iterator> R) {
543    return map_range(
544        make_filter_range(R,
545                          [](DbgRecord &E) { return isa<DbgVariableRecord>(E); }),
546        [](DbgRecord &E) { return std::ref(cast<DbgVariableRecord>(E)); });
547  }
548  
549  /// Per-instruction record of debug-info. If an Instruction is the position of
550  /// some debugging information, it points at a DbgMarker storing that info. Each
551  /// marker points back at the instruction that owns it. Various utilities are
552  /// provided for manipulating the DbgRecords contained within this marker.
553  ///
554  /// This class has a rough surface area, because it's needed to preserve the
555  /// one arefact that we can't yet eliminate from the intrinsic / dbg.value
556  /// debug-info design: the order of records is significant, and duplicates can
557  /// exist. Thus, if one has a run of debug-info records such as:
558  ///    dbg.value(...
559  ///    %foo = barinst
560  ///    dbg.value(...
561  /// and remove barinst, then the dbg.values must be preserved in the correct
562  /// order. Hence, the use of iterators to select positions to insert things
563  /// into, or the occasional InsertAtHead parameter indicating that new records
564  /// should go at the start of the list.
565  ///
566  /// There are only five or six places in LLVM that truly rely on this ordering,
567  /// which we can improve in the future. Additionally, many improvements in the
568  /// way that debug-info is stored can be achieved in this class, at a future
569  /// date.
570  class DbgMarker {
571  public:
DbgMarker()572    DbgMarker() {}
573    /// Link back to the Instruction that owns this marker. Can be null during
574    /// operations that move a marker from one instruction to another.
575    Instruction *MarkedInstr = nullptr;
576  
577    /// List of DbgRecords, the non-instruction equivalent of llvm.dbg.*
578    /// intrinsics. There is a one-to-one relationship between each debug
579    /// intrinsic in a block and each DbgRecord once the representation has been
580    /// converted, and the ordering is meaningful in the same way.
581    simple_ilist<DbgRecord> StoredDbgRecords;
empty()582    bool empty() const { return StoredDbgRecords.empty(); }
583  
584    const BasicBlock *getParent() const;
585    BasicBlock *getParent();
586  
587    /// Handle the removal of a marker: the position of debug-info has gone away,
588    /// but the stored debug records should not. Drop them onto the next
589    /// instruction, or otherwise work out what to do with them.
590    void removeMarker();
591    void dump() const;
592  
593    void removeFromParent();
594    void eraseFromParent();
595  
596    /// Implement operator<< on DbgMarker.
597    void print(raw_ostream &O, bool IsForDebug = false) const;
598    void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
599  
600    /// Produce a range over all the DbgRecords in this Marker.
601    iterator_range<simple_ilist<DbgRecord>::iterator> getDbgRecordRange();
602    iterator_range<simple_ilist<DbgRecord>::const_iterator>
603    getDbgRecordRange() const;
604    /// Transfer any DbgRecords from \p Src into this DbgMarker. If \p
605    /// InsertAtHead is true, place them before existing DbgRecords, otherwise
606    /// afterwards.
607    void absorbDebugValues(DbgMarker &Src, bool InsertAtHead);
608    /// Transfer the DbgRecords in \p Range from \p Src into this DbgMarker. If
609    /// \p InsertAtHead is true, place them before existing DbgRecords, otherwise
610    // afterwards.
611    void absorbDebugValues(iterator_range<DbgRecord::self_iterator> Range,
612                           DbgMarker &Src, bool InsertAtHead);
613    /// Insert a DbgRecord into this DbgMarker, at the end of the list. If
614    /// \p InsertAtHead is true, at the start.
615    void insertDbgRecord(DbgRecord *New, bool InsertAtHead);
616    /// Insert a DbgRecord prior to a DbgRecord contained within this marker.
617    void insertDbgRecord(DbgRecord *New, DbgRecord *InsertBefore);
618    /// Insert a DbgRecord after a DbgRecord contained within this marker.
619    void insertDbgRecordAfter(DbgRecord *New, DbgRecord *InsertAfter);
620    /// Clone all DbgMarkers from \p From into this marker. There are numerous
621    /// options to customise the source/destination, due to gnarliness, see class
622    /// comment.
623    /// \p FromHere If non-null, copy from FromHere to the end of From's
624    /// DbgRecords
625    /// \p InsertAtHead Place the cloned DbgRecords at the start of
626    /// StoredDbgRecords
627    /// \returns Range over all the newly cloned DbgRecords
628    iterator_range<simple_ilist<DbgRecord>::iterator>
629    cloneDebugInfoFrom(DbgMarker *From,
630                       std::optional<simple_ilist<DbgRecord>::iterator> FromHere,
631                       bool InsertAtHead = false);
632    /// Erase all DbgRecords in this DbgMarker.
633    void dropDbgRecords();
634    /// Erase a single DbgRecord from this marker. In an ideal future, we would
635    /// never erase an assignment in this way, but it's the equivalent to
636    /// erasing a debug intrinsic from a block.
637    void dropOneDbgRecord(DbgRecord *DR);
638  
639    /// We generally act like all llvm Instructions have a range of DbgRecords
640    /// attached to them, but in reality sometimes we don't allocate the DbgMarker
641    /// to save time and memory, but still have to return ranges of DbgRecords.
642    /// When we need to describe such an unallocated DbgRecord range, use this
643    /// static markers range instead. This will bite us if someone tries to insert
644    /// a DbgRecord in that range, but they should be using the Official (TM) API
645    /// for that.
646    static DbgMarker EmptyDbgMarker;
647    static iterator_range<simple_ilist<DbgRecord>::iterator>
getEmptyDbgRecordRange()648    getEmptyDbgRecordRange() {
649      return make_range(EmptyDbgMarker.StoredDbgRecords.end(),
650                        EmptyDbgMarker.StoredDbgRecords.end());
651    }
652  };
653  
654  inline raw_ostream &operator<<(raw_ostream &OS, const DbgMarker &Marker) {
655    Marker.print(OS);
656    return OS;
657  }
658  
659  /// Inline helper to return a range of DbgRecords attached to a marker. It needs
660  /// to be inlined as it's frequently called, but also come after the declaration
661  /// of DbgMarker. Thus: it's pre-declared by users like Instruction, then an
662  /// inlineable body defined here.
663  inline iterator_range<simple_ilist<DbgRecord>::iterator>
getDbgRecordRange(DbgMarker * DebugMarker)664  getDbgRecordRange(DbgMarker *DebugMarker) {
665    if (!DebugMarker)
666      return DbgMarker::getEmptyDbgRecordRange();
667    return DebugMarker->getDbgRecordRange();
668  }
669  
DEFINE_ISA_CONVERSION_FUNCTIONS(DbgRecord,LLVMDbgRecordRef)670  DEFINE_ISA_CONVERSION_FUNCTIONS(DbgRecord, LLVMDbgRecordRef)
671  
672  /// Used to temporarily set the debug info format of a function, module, or
673  /// basic block for the duration of this object's lifetime, after which the
674  /// prior state will be restored.
675  template <typename T> class ScopedDbgInfoFormatSetter {
676    T &Obj;
677    bool OldState;
678  
679  public:
680    ScopedDbgInfoFormatSetter(T &Obj, bool NewState)
681        : Obj(Obj), OldState(Obj.IsNewDbgInfoFormat) {
682      Obj.setIsNewDbgInfoFormat(NewState);
683    }
684    ~ScopedDbgInfoFormatSetter() { Obj.setIsNewDbgInfoFormat(OldState); }
685  };
686  
687  template <typename T>
688  ScopedDbgInfoFormatSetter(T &Obj,
689                            bool NewState) -> ScopedDbgInfoFormatSetter<T>;
690  
691  } // namespace llvm
692  
693  #endif // LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
694