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 it's ilist, storing the equivalent information
36// to the
37// ;; dbg.value above: the Value, DILocalVariable, etc.
38//
39// This structure separates the two concerns of the position of the debug-info
40// in the function, and the Value that it refers to. It also creates a new
41// "place" in-between the Value / Metadata hierachy where we can customise
42// storage and allocation techniques to better suite debug-info workloads.
43// NB: as of the initial prototype, none of that has actually been attempted
44// yet.
45//
46//===----------------------------------------------------------------------===//
47
48#ifndef LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
49#define LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
50
51#include "llvm/ADT/ilist.h"
52#include "llvm/ADT/ilist_node.h"
53#include "llvm/ADT/iterator.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
59namespace llvm {
60
61class Instruction;
62class BasicBlock;
63class MDNode;
64class Module;
65class DbgVariableIntrinsic;
66class DbgInfoIntrinsic;
67class DbgLabelInst;
68class DIAssignID;
69class DbgMarker;
70class DbgVariableRecord;
71class 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.
76template <typename T> class DbgRecordParamRef {
77 TrackingMDNodeRef Ref;
78
79public:
80public:
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.
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/// it's 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
134class DbgRecord : public ilist_node<DbgRecord> {
135public:
136 /// Marker that this DbgRecord is linked into.
137 DbgMarker *Marker = nullptr;
138 /// Subclass discriminator.
139 enum Kind : uint8_t { ValueKind, LabelKind };
140
141protected:
142 DebugLoc DbgLoc;
143 Kind RecordKind; ///< Subclass discriminator.
144
145public:
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
167 Kind getRecordKind() const { return RecordKind; }
168
169 void setMarker(DbgMarker *M) { Marker = M; }
170
171 DbgMarker *getMarker() { return Marker; }
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
193 DbgRecord *getNextNode() { return &*std::next(x: getIterator()); }
194 DbgRecord *getPrevNode() { return &*std::prev(x: getIterator()); }
195 void insertBefore(DbgRecord *InsertBefore);
196 void insertAfter(DbgRecord *InsertAfter);
197 void moveBefore(DbgRecord *MoveBefore);
198 void moveAfter(DbgRecord *MoveAfter);
199
200 DebugLoc getDebugLoc() const { return DbgLoc; }
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
208protected:
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
216inline raw_ostream &operator<<(raw_ostream &OS, const DbgRecord &R) {
217 R.print(O&: 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.
223class 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
231public:
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
247 void setLabel(DILabel *NewLabel) { Label = NewLabel; }
248 DILabel *getLabel() const { return Label.get(); }
249 MDNode *getRawLabel() const { return Label.getAsMDNode(); };
250
251 /// Support type inquiry through isa, cast, and dyn_cast.
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.
262class DbgVariableRecord : public DbgRecord, protected DebugValueUser {
263 friend class DebugValueUser;
264
265public:
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, "is this a dbg.value or dbg.declare?".
276 /// dbg.declares are not currently supported, but it would be trivial to do
277 /// so.
278 /// FIXME: We could use spare padding bits from DbgRecord for this.
279 LocationType Type;
280
281 // NB: there is no explicit "Value" field in this class, it's effectively the
282 // DebugValueUser superclass instead. The referred to Value can either be a
283 // ValueAsMetadata or a DIArgList.
284
285 DbgRecordParamRef<DILocalVariable> Variable;
286 DbgRecordParamRef<DIExpression> Expression;
287 DbgRecordParamRef<DIExpression> AddressExpression;
288
289public:
290 /// Create a new DbgVariableRecord representing the intrinsic \p DVI, for
291 /// example the assignment represented by a dbg.value.
292 DbgVariableRecord(const DbgVariableIntrinsic *DVI);
293 DbgVariableRecord(const DbgVariableRecord &DVR);
294 /// Directly construct a new DbgVariableRecord representing a dbg.value
295 /// intrinsic assigning \p Location to the DV / Expr / DI variable.
296 DbgVariableRecord(Metadata *Location, DILocalVariable *DV, DIExpression *Expr,
297 const DILocation *DI,
298 LocationType Type = LocationType::Value);
299 DbgVariableRecord(Metadata *Value, DILocalVariable *Variable,
300 DIExpression *Expression, DIAssignID *AssignID,
301 Metadata *Address, DIExpression *AddressExpression,
302 const DILocation *DI);
303
304private:
305 /// Private constructor for creating new instances during parsing only. Only
306 /// called through `createUnresolvedDbgVariableRecord` below, which makes
307 /// clear that this is used for parsing only, and will later return a subclass
308 /// depending on which Type is passed.
309 DbgVariableRecord(LocationType Type, Metadata *Val, MDNode *Variable,
310 MDNode *Expression, MDNode *AssignID, Metadata *Address,
311 MDNode *AddressExpression, MDNode *DI);
312
313public:
314 /// Used to create DbgVariableRecords during parsing, where some metadata
315 /// references may still be unresolved. Although for some fields a generic
316 /// `Metadata*` argument is accepted for forward type-references, the verifier
317 /// and accessors will reject incorrect types later on. The function is used
318 /// for all types of DbgVariableRecords for simplicity while parsing, but
319 /// asserts if any necessary fields are empty or unused fields are not empty,
320 /// i.e. if the #dbg_assign fields are used for a non-dbg-assign type.
321 static DbgVariableRecord *
322 createUnresolvedDbgVariableRecord(LocationType Type, Metadata *Val,
323 MDNode *Variable, MDNode *Expression,
324 MDNode *AssignID, Metadata *Address,
325 MDNode *AddressExpression, MDNode *DI);
326
327 static DbgVariableRecord *
328 createDVRAssign(Value *Val, DILocalVariable *Variable,
329 DIExpression *Expression, DIAssignID *AssignID,
330 Value *Address, DIExpression *AddressExpression,
331 const DILocation *DI);
332 static DbgVariableRecord *
333 createLinkedDVRAssign(Instruction *LinkedInstr, Value *Val,
334 DILocalVariable *Variable, DIExpression *Expression,
335 Value *Address, DIExpression *AddressExpression,
336 const DILocation *DI);
337
338 static DbgVariableRecord *createDbgVariableRecord(Value *Location,
339 DILocalVariable *DV,
340 DIExpression *Expr,
341 const DILocation *DI);
342 static DbgVariableRecord *
343 createDbgVariableRecord(Value *Location, DILocalVariable *DV,
344 DIExpression *Expr, const DILocation *DI,
345 DbgVariableRecord &InsertBefore);
346 static DbgVariableRecord *createDVRDeclare(Value *Address,
347 DILocalVariable *DV,
348 DIExpression *Expr,
349 const DILocation *DI);
350 static DbgVariableRecord *
351 createDVRDeclare(Value *Address, DILocalVariable *DV, DIExpression *Expr,
352 const DILocation *DI, DbgVariableRecord &InsertBefore);
353
354 /// Iterator for ValueAsMetadata that internally uses direct pointer iteration
355 /// over either a ValueAsMetadata* or a ValueAsMetadata**, dereferencing to the
356 /// ValueAsMetadata .
357 class location_op_iterator
358 : public iterator_facade_base<location_op_iterator,
359 std::bidirectional_iterator_tag, Value *> {
360 PointerUnion<ValueAsMetadata *, ValueAsMetadata **> I;
361
362 public:
363 location_op_iterator(ValueAsMetadata *SingleIter) : I(SingleIter) {}
364 location_op_iterator(ValueAsMetadata **MultiIter) : I(MultiIter) {}
365
366 location_op_iterator(const location_op_iterator &R) : I(R.I) {}
367 location_op_iterator &operator=(const location_op_iterator &R) {
368 I = R.I;
369 return *this;
370 }
371 bool operator==(const location_op_iterator &RHS) const {
372 return I == RHS.I;
373 }
374 const Value *operator*() const {
375 ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
376 ? I.get<ValueAsMetadata *>()
377 : *I.get<ValueAsMetadata **>();
378 return VAM->getValue();
379 };
380 Value *operator*() {
381 ValueAsMetadata *VAM = I.is<ValueAsMetadata *>()
382 ? I.get<ValueAsMetadata *>()
383 : *I.get<ValueAsMetadata **>();
384 return VAM->getValue();
385 }
386 location_op_iterator &operator++() {
387 if (I.is<ValueAsMetadata *>())
388 I = I.get<ValueAsMetadata *>() + 1;
389 else
390 I = I.get<ValueAsMetadata **>() + 1;
391 return *this;
392 }
393 location_op_iterator &operator--() {
394 if (I.is<ValueAsMetadata *>())
395 I = I.get<ValueAsMetadata *>() - 1;
396 else
397 I = I.get<ValueAsMetadata **>() - 1;
398 return *this;
399 }
400 };
401
402 bool isDbgDeclare() { return Type == LocationType::Declare; }
403 bool isDbgValue() { return Type == LocationType::Value; }
404
405 /// Get the locations corresponding to the variable referenced by the debug
406 /// info intrinsic. Depending on the intrinsic, this could be the
407 /// variable's value or its address.
408 iterator_range<location_op_iterator> location_ops() const;
409
410 Value *getVariableLocationOp(unsigned OpIdx) const;
411
412 void replaceVariableLocationOp(Value *OldValue, Value *NewValue,
413 bool AllowEmpty = false);
414 void replaceVariableLocationOp(unsigned OpIdx, Value *NewValue);
415 /// Adding a new location operand will always result in this intrinsic using
416 /// an ArgList, and must always be accompanied by a new expression that uses
417 /// the new operand.
418 void addVariableLocationOps(ArrayRef<Value *> NewValues,
419 DIExpression *NewExpr);
420
421 unsigned getNumVariableLocationOps() const;
422
423 bool hasArgList() const { return isa<DIArgList>(Val: getRawLocation()); }
424 /// Returns true if this DbgVariableRecord has no empty MDNodes in its
425 /// location list.
426 bool hasValidLocation() const { return getVariableLocationOp(OpIdx: 0) != nullptr; }
427
428 /// Does this describe the address of a local variable. True for dbg.addr
429 /// and dbg.declare, but not dbg.value, which describes its value.
430 bool isAddressOfVariable() const { return Type == LocationType::Declare; }
431 LocationType getType() const { return Type; }
432
433 void setKillLocation();
434 bool isKillLocation() const;
435
436 void setVariable(DILocalVariable *NewVar) { Variable = NewVar; }
437 DILocalVariable *getVariable() const { return Variable.get(); };
438 MDNode *getRawVariable() const { return Variable.getAsMDNode(); }
439
440 void setExpression(DIExpression *NewExpr) { Expression = NewExpr; }
441 DIExpression *getExpression() const { return Expression.get(); }
442 MDNode *getRawExpression() const { return Expression.getAsMDNode(); }
443
444 /// Returns the metadata operand for the first location description. i.e.,
445 /// dbg intrinsic dbg.value,declare operand and dbg.assign 1st location
446 /// operand (the "value componenet"). Note the operand (singular) may be
447 /// a DIArgList which is a list of values.
448 Metadata *getRawLocation() const { return DebugValues[0]; }
449
450 Value *getValue(unsigned OpIdx = 0) const {
451 return getVariableLocationOp(OpIdx);
452 }
453
454 /// Use of this should generally be avoided; instead,
455 /// replaceVariableLocationOp and addVariableLocationOps should be used where
456 /// possible to avoid creating invalid state.
457 void setRawLocation(Metadata *NewLocation) {
458 assert((isa<ValueAsMetadata>(NewLocation) || isa<DIArgList>(NewLocation) ||
459 isa<MDNode>(NewLocation)) &&
460 "Location for a DbgVariableRecord must be either ValueAsMetadata or "
461 "DIArgList");
462 resetDebugValue(Idx: 0, DebugValue: NewLocation);
463 }
464
465 /// Get the size (in bits) of the variable, or fragment of the variable that
466 /// is described.
467 std::optional<uint64_t> getFragmentSizeInBits() const;
468
469 bool isEquivalentTo(const DbgVariableRecord &Other) const {
470 return DbgLoc == Other.DbgLoc && isIdenticalToWhenDefined(Other);
471 }
472 // Matches the definition of the Instruction version, equivalent to above but
473 // without checking DbgLoc.
474 bool isIdenticalToWhenDefined(const DbgVariableRecord &Other) const {
475 return std::tie(args: Type, args: DebugValues, args: Variable, args: Expression,
476 args: AddressExpression) ==
477 std::tie(args: Other.Type, args: Other.DebugValues, args: Other.Variable,
478 args: Other.Expression, args: Other.AddressExpression);
479 }
480
481 /// @name DbgAssign Methods
482 /// @{
483 bool isDbgAssign() const { return getType() == LocationType::Assign; }
484
485 Value *getAddress() const;
486 Metadata *getRawAddress() const {
487 return isDbgAssign() ? DebugValues[1] : DebugValues[0];
488 }
489 Metadata *getRawAssignID() const { return DebugValues[2]; }
490 DIAssignID *getAssignID() const;
491 DIExpression *getAddressExpression() const { return AddressExpression.get(); }
492 MDNode *getRawAddressExpression() const {
493 return AddressExpression.getAsMDNode();
494 }
495 void setAddressExpression(DIExpression *NewExpr) {
496 AddressExpression = NewExpr;
497 }
498 void setAssignId(DIAssignID *New);
499 void setAddress(Value *V) { resetDebugValue(Idx: 1, DebugValue: ValueAsMetadata::get(V)); }
500 /// Kill the address component.
501 void setKillAddress();
502 /// Check whether this kills the address component. This doesn't take into
503 /// account the position of the intrinsic, therefore a returned value of false
504 /// does not guarentee the address is a valid location for the variable at the
505 /// intrinsic's position in IR.
506 bool isKillAddress() const;
507
508 /// @}
509
510 DbgVariableRecord *clone() const;
511 /// Convert this DbgVariableRecord back into a dbg.value intrinsic.
512 /// \p InsertBefore Optional position to insert this intrinsic.
513 /// \returns A new dbg.value intrinsic representiung this DbgVariableRecord.
514 DbgVariableIntrinsic *createDebugIntrinsic(Module *M,
515 Instruction *InsertBefore) const;
516
517 /// Handle changes to the location of the Value(s) that we refer to happening
518 /// "under our feet".
519 void handleChangedLocation(Metadata *NewLocation);
520
521 void print(raw_ostream &O, bool IsForDebug = false) const;
522 void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
523
524 /// Support type inquiry through isa, cast, and dyn_cast.
525 static bool classof(const DbgRecord *E) {
526 return E->getRecordKind() == ValueKind;
527 }
528};
529
530/// Filter the DbgRecord range to DbgVariableRecord types only and downcast.
531static inline auto
532filterDbgVars(iterator_range<simple_ilist<DbgRecord>::iterator> R) {
533 return map_range(
534 C: make_filter_range(Range&: R,
535 Pred: [](DbgRecord &E) { return isa<DbgVariableRecord>(Val: E); }),
536 F: [](DbgRecord &E) { return std::ref(t&: cast<DbgVariableRecord>(Val&: E)); });
537}
538
539/// Per-instruction record of debug-info. If an Instruction is the position of
540/// some debugging information, it points at a DbgMarker storing that info. Each
541/// marker points back at the instruction that owns it. Various utilities are
542/// provided for manipulating the DbgRecords contained within this marker.
543///
544/// This class has a rough surface area, because it's needed to preserve the
545/// one arefact that we can't yet eliminate from the intrinsic / dbg.value
546/// debug-info design: the order of records is significant, and duplicates can
547/// exist. Thus, if one has a run of debug-info records such as:
548/// dbg.value(...
549/// %foo = barinst
550/// dbg.value(...
551/// and remove barinst, then the dbg.values must be preserved in the correct
552/// order. Hence, the use of iterators to select positions to insert things
553/// into, or the occasional InsertAtHead parameter indicating that new records
554/// should go at the start of the list.
555///
556/// There are only five or six places in LLVM that truly rely on this ordering,
557/// which we can improve in the future. Additionally, many improvements in the
558/// way that debug-info is stored can be achieved in this class, at a future
559/// date.
560class DbgMarker {
561public:
562 DbgMarker() {}
563 /// Link back to the Instruction that owns this marker. Can be null during
564 /// operations that move a marker from one instruction to another.
565 Instruction *MarkedInstr = nullptr;
566
567 /// List of DbgRecords, the non-instruction equivalent of llvm.dbg.*
568 /// intrinsics. There is a one-to-one relationship between each debug
569 /// intrinsic in a block and each DbgRecord once the representation has been
570 /// converted, and the ordering is meaningful in the same way.
571 simple_ilist<DbgRecord> StoredDbgRecords;
572 bool empty() const { return StoredDbgRecords.empty(); }
573
574 const BasicBlock *getParent() const;
575 BasicBlock *getParent();
576
577 /// Handle the removal of a marker: the position of debug-info has gone away,
578 /// but the stored debug records should not. Drop them onto the next
579 /// instruction, or otherwise work out what to do with them.
580 void removeMarker();
581 void dump() const;
582
583 void removeFromParent();
584 void eraseFromParent();
585
586 /// Implement operator<< on DbgMarker.
587 void print(raw_ostream &O, bool IsForDebug = false) const;
588 void print(raw_ostream &ROS, ModuleSlotTracker &MST, bool IsForDebug) const;
589
590 /// Produce a range over all the DbgRecords in this Marker.
591 iterator_range<simple_ilist<DbgRecord>::iterator> getDbgRecordRange();
592 iterator_range<simple_ilist<DbgRecord>::const_iterator>
593 getDbgRecordRange() const;
594 /// Transfer any DbgRecords from \p Src into this DbgMarker. If \p
595 /// InsertAtHead is true, place them before existing DbgRecords, otherwise
596 /// afterwards.
597 void absorbDebugValues(DbgMarker &Src, bool InsertAtHead);
598 /// Transfer the DbgRecords in \p Range from \p Src into this DbgMarker. If
599 /// \p InsertAtHead is true, place them before existing DbgRecords, otherwise
600 // afterwards.
601 void absorbDebugValues(iterator_range<DbgRecord::self_iterator> Range,
602 DbgMarker &Src, bool InsertAtHead);
603 /// Insert a DbgRecord into this DbgMarker, at the end of the list. If
604 /// \p InsertAtHead is true, at the start.
605 void insertDbgRecord(DbgRecord *New, bool InsertAtHead);
606 /// Insert a DbgRecord prior to a DbgRecord contained within this marker.
607 void insertDbgRecord(DbgRecord *New, DbgRecord *InsertBefore);
608 /// Insert a DbgRecord after a DbgRecord contained within this marker.
609 void insertDbgRecordAfter(DbgRecord *New, DbgRecord *InsertAfter);
610 /// Clone all DbgMarkers from \p From into this marker. There are numerous
611 /// options to customise the source/destination, due to gnarliness, see class
612 /// comment.
613 /// \p FromHere If non-null, copy from FromHere to the end of From's
614 /// DbgRecords
615 /// \p InsertAtHead Place the cloned DbgRecords at the start of
616 /// StoredDbgRecords
617 /// \returns Range over all the newly cloned DbgRecords
618 iterator_range<simple_ilist<DbgRecord>::iterator>
619 cloneDebugInfoFrom(DbgMarker *From,
620 std::optional<simple_ilist<DbgRecord>::iterator> FromHere,
621 bool InsertAtHead = false);
622 /// Erase all DbgRecords in this DbgMarker.
623 void dropDbgRecords();
624 /// Erase a single DbgRecord from this marker. In an ideal future, we would
625 /// never erase an assignment in this way, but it's the equivalent to
626 /// erasing a debug intrinsic from a block.
627 void dropOneDbgRecord(DbgRecord *DR);
628
629 /// We generally act like all llvm Instructions have a range of DbgRecords
630 /// attached to them, but in reality sometimes we don't allocate the DbgMarker
631 /// to save time and memory, but still have to return ranges of DbgRecords.
632 /// When we need to describe such an unallocated DbgRecord range, use this
633 /// static markers range instead. This will bite us if someone tries to insert
634 /// a DbgRecord in that range, but they should be using the Official (TM) API
635 /// for that.
636 static DbgMarker EmptyDbgMarker;
637 static iterator_range<simple_ilist<DbgRecord>::iterator>
638 getEmptyDbgRecordRange() {
639 return make_range(x: EmptyDbgMarker.StoredDbgRecords.end(),
640 y: EmptyDbgMarker.StoredDbgRecords.end());
641 }
642};
643
644inline raw_ostream &operator<<(raw_ostream &OS, const DbgMarker &Marker) {
645 Marker.print(O&: OS);
646 return OS;
647}
648
649/// Inline helper to return a range of DbgRecords attached to a marker. It needs
650/// to be inlined as it's frequently called, but also come after the declaration
651/// of DbgMarker. Thus: it's pre-declared by users like Instruction, then an
652/// inlineable body defined here.
653inline iterator_range<simple_ilist<DbgRecord>::iterator>
654getDbgRecordRange(DbgMarker *DebugMarker) {
655 if (!DebugMarker)
656 return DbgMarker::getEmptyDbgRecordRange();
657 return DebugMarker->getDbgRecordRange();
658}
659
660DEFINE_ISA_CONVERSION_FUNCTIONS(DbgRecord, LLVMDbgRecordRef)
661
662/// Used to temporarily set the debug info format of a function, module, or
663/// basic block for the duration of this object's lifetime, after which the
664/// prior state will be restored.
665template <typename T> class ScopedDbgInfoFormatSetter {
666 T &Obj;
667 bool OldState;
668
669public:
670 ScopedDbgInfoFormatSetter(T &Obj, bool NewState)
671 : Obj(Obj), OldState(Obj.IsNewDbgInfoFormat) {
672 Obj.setIsNewDbgInfoFormat(NewState);
673 }
674 ~ScopedDbgInfoFormatSetter() { Obj.setIsNewDbgInfoFormat(OldState); }
675};
676
677template <typename T>
678ScopedDbgInfoFormatSetter(T &Obj,
679 bool NewState) -> ScopedDbgInfoFormatSetter<T>;
680
681} // namespace llvm
682
683#endif // LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
684

source code of llvm/include/llvm/IR/DebugProgramInstruction.h