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
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/// 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
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, "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
288public:
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
303private:
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
312public:
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:
362 location_op_iterator(ValueAsMetadata *SingleIter) : I(SingleIter) {}
363 location_op_iterator(ValueAsMetadata **MultiIter) : I(MultiIter) {}
364
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
401 bool isDbgDeclare() { return Type == LocationType::Declare; }
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
422 bool hasArgList() const { return isa<DIArgList>(Val: getRawLocation()); }
423 /// Returns true if this DbgVariableRecord has no empty MDNodes in its
424 /// location list.
425 bool hasValidLocation() const { return getVariableLocationOp(OpIdx: 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.
429 bool isAddressOfVariable() const { return Type == LocationType::Declare; }
430 LocationType getType() const { return Type; }
431
432 void setKillLocation();
433 bool isKillLocation() const;
434
435 void setVariable(DILocalVariable *NewVar) { Variable = NewVar; }
436 DILocalVariable *getVariable() const { return Variable.get(); };
437 MDNode *getRawVariable() const { return Variable.getAsMDNode(); }
438
439 void setExpression(DIExpression *NewExpr) { Expression = NewExpr; }
440 DIExpression *getExpression() const { return Expression.get(); }
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.
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.
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(Idx: 0, DebugValue: 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.
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
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.
484 bool isIdenticalToWhenDefined(const DbgVariableRecord &Other) const {
485 return std::tie(args: Type, args: DebugValues, args: Variable, args: Expression,
486 args: AddressExpression) ==
487 std::tie(args: Other.Type, args: Other.DebugValues, args: Other.Variable,
488 args: Other.Expression, args: Other.AddressExpression);
489 }
490
491 /// @name DbgAssign Methods
492 /// @{
493 bool isDbgAssign() const { return getType() == LocationType::Assign; }
494
495 Value *getAddress() const;
496 Metadata *getRawAddress() const {
497 return isDbgAssign() ? DebugValues[1] : DebugValues[0];
498 }
499 Metadata *getRawAssignID() const { return DebugValues[2]; }
500 DIAssignID *getAssignID() const;
501 DIExpression *getAddressExpression() const { return AddressExpression.get(); }
502 MDNode *getRawAddressExpression() const {
503 return AddressExpression.getAsMDNode();
504 }
505 void setAddressExpression(DIExpression *NewExpr) {
506 AddressExpression = NewExpr;
507 }
508 void setAssignId(DIAssignID *New);
509 void setAddress(Value *V) { resetDebugValue(Idx: 1, DebugValue: 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.
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.
541static inline auto
542filterDbgVars(iterator_range<simple_ilist<DbgRecord>::iterator> R) {
543 return map_range(
544 C: make_filter_range(Range&: R,
545 Pred: [](DbgRecord &E) { return isa<DbgVariableRecord>(Val: E); }),
546 F: [](DbgRecord &E) { return std::ref(t&: cast<DbgVariableRecord>(Val&: 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.
570class DbgMarker {
571public:
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;
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>
648 getEmptyDbgRecordRange() {
649 return make_range(x: EmptyDbgMarker.StoredDbgRecords.end(),
650 y: EmptyDbgMarker.StoredDbgRecords.end());
651 }
652};
653
654inline raw_ostream &operator<<(raw_ostream &OS, const DbgMarker &Marker) {
655 Marker.print(O&: 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.
663inline iterator_range<simple_ilist<DbgRecord>::iterator>
664getDbgRecordRange(DbgMarker *DebugMarker) {
665 if (!DebugMarker)
666 return DbgMarker::getEmptyDbgRecordRange();
667 return DebugMarker->getDbgRecordRange();
668}
669
670DEFINE_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.
675template <typename T> class ScopedDbgInfoFormatSetter {
676 T &Obj;
677 bool OldState;
678
679public:
680 ScopedDbgInfoFormatSetter(T &Obj, bool NewState)
681 : Obj(Obj), OldState(Obj.IsNewDbgInfoFormat) {
682 Obj.setIsNewDbgInfoFormat(NewState);
683 }
684 ~ScopedDbgInfoFormatSetter() { Obj.setIsNewDbgInfoFormat(OldState); }
685};
686
687template <typename T>
688ScopedDbgInfoFormatSetter(T &Obj,
689 bool NewState) -> ScopedDbgInfoFormatSetter<T>;
690
691} // namespace llvm
692
693#endif // LLVM_IR_DEBUGPROGRAMINSTRUCTION_H
694