1//===- DebugInfo.h - Debug Information Helpers ------------------*- 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// This file defines a bunch of datatypes that are useful for creating and
10// walking debug info in LLVM IR form. They essentially provide wrappers around
11// the information in the global variables that's needed when constructing the
12// DWARF information.
13//
14//===----------------------------------------------------------------------===//
15
16#ifndef LLVM_IR_DEBUGINFO_H
17#define LLVM_IR_DEBUGINFO_H
18
19#include "llvm/ADT/DenseMapInfo.h"
20#include "llvm/ADT/STLExtras.h"
21#include "llvm/ADT/SetVector.h"
22#include "llvm/ADT/SmallPtrSet.h"
23#include "llvm/ADT/SmallSet.h"
24#include "llvm/ADT/SmallVector.h"
25#include "llvm/ADT/TinyPtrVector.h"
26#include "llvm/ADT/iterator_range.h"
27#include "llvm/IR/DataLayout.h"
28#include "llvm/IR/IntrinsicInst.h"
29#include "llvm/IR/PassManager.h"
30#include "llvm/Support/Compiler.h"
31#include <optional>
32
33namespace llvm {
34
35class DbgDeclareInst;
36class DbgValueInst;
37class DbgVariableIntrinsic;
38class DbgVariableRecord;
39class Instruction;
40class Module;
41
42/// Finds dbg.declare intrinsics declaring local variables as living in the
43/// memory that 'V' points to.
44LLVM_ABI TinyPtrVector<DbgDeclareInst *> findDbgDeclares(Value *V);
45/// As above, for DVRDeclares.
46LLVM_ABI TinyPtrVector<DbgVariableRecord *> findDVRDeclares(Value *V);
47/// As above, for DVRValues.
48LLVM_ABI TinyPtrVector<DbgVariableRecord *> findDVRValues(Value *V);
49
50/// Finds the llvm.dbg.value intrinsics describing a value.
51LLVM_ABI void findDbgValues(
52 SmallVectorImpl<DbgValueInst *> &DbgValues, Value *V,
53 SmallVectorImpl<DbgVariableRecord *> *DbgVariableRecords = nullptr);
54
55/// Finds the debug info intrinsics describing a value.
56LLVM_ABI void findDbgUsers(
57 SmallVectorImpl<DbgVariableIntrinsic *> &DbgInsts, Value *V,
58 SmallVectorImpl<DbgVariableRecord *> *DbgVariableRecords = nullptr);
59
60/// Find subprogram that is enclosing this scope.
61LLVM_ABI DISubprogram *getDISubprogram(const MDNode *Scope);
62
63/// Produce a DebugLoc to use for each dbg.declare that is promoted to a
64/// dbg.value.
65LLVM_ABI DebugLoc getDebugValueLoc(DbgVariableIntrinsic *DII);
66LLVM_ABI DebugLoc getDebugValueLoc(DbgVariableRecord *DVR);
67
68/// Strip debug info in the module if it exists.
69///
70/// To do this, we remove all calls to the debugger intrinsics and any named
71/// metadata for debugging. We also remove debug locations for instructions.
72/// Return true if module is modified.
73LLVM_ABI bool StripDebugInfo(Module &M);
74LLVM_ABI bool stripDebugInfo(Function &F);
75
76/// Downgrade the debug info in a module to contain only line table information.
77///
78/// In order to convert debug info to what -gline-tables-only would have
79/// created, this does the following:
80/// 1) Delete all debug intrinsics.
81/// 2) Delete all non-CU named metadata debug info nodes.
82/// 3) Create new DebugLocs for each instruction.
83/// 4) Create a new CU debug info, and similarly for every metadata node
84/// that's reachable from the CU debug info.
85/// All debug type metadata nodes are unreachable and garbage collected.
86LLVM_ABI bool stripNonLineTableDebugInfo(Module &M);
87
88/// Update the debug locations contained within the MD_loop metadata attached
89/// to the instruction \p I, if one exists. \p Updater is applied to Metadata
90/// operand in the MD_loop metadata: the returned value is included in the
91/// updated loop metadata node if it is non-null.
92LLVM_ABI void
93updateLoopMetadataDebugLocations(Instruction &I,
94 function_ref<Metadata *(Metadata *)> Updater);
95
96/// Return Debug Info Metadata Version by checking module flags.
97LLVM_ABI unsigned getDebugMetadataVersionFromModule(const Module &M);
98
99/// Utility to find all debug info in a module.
100///
101/// DebugInfoFinder tries to list all debug info MDNodes used in a module. To
102/// list debug info MDNodes used by an instruction, DebugInfoFinder uses
103/// processDeclare, processValue and processLocation to handle DbgDeclareInst,
104/// DbgValueInst and DbgLoc attached to instructions. processModule will go
105/// through all DICompileUnits in llvm.dbg.cu and list debug info MDNodes
106/// used by the CUs.
107class DebugInfoFinder {
108public:
109 /// Process entire module and collect debug info anchors.
110 LLVM_ABI void processModule(const Module &M);
111 /// Process a single instruction and collect debug info anchors.
112 LLVM_ABI void processInstruction(const Module &M, const Instruction &I);
113
114 /// Process a DILocalVariable.
115 LLVM_ABI void processVariable(DILocalVariable *DVI);
116 /// Process debug info location.
117 LLVM_ABI void processLocation(const Module &M, const DILocation *Loc);
118 /// Process a DbgRecord (e.g, treat a DbgVariableRecord like a
119 /// DbgVariableIntrinsic).
120 LLVM_ABI void processDbgRecord(const Module &M, const DbgRecord &DR);
121
122 /// Process subprogram.
123 LLVM_ABI void processSubprogram(DISubprogram *SP);
124
125 /// Clear all lists.
126 LLVM_ABI void reset();
127
128private:
129 void processCompileUnit(DICompileUnit *CU);
130 void processScope(DIScope *Scope);
131 void processType(DIType *DT);
132 void processImportedEntity(DIImportedEntity *Import);
133 bool addCompileUnit(DICompileUnit *CU);
134 bool addGlobalVariable(DIGlobalVariableExpression *DIG);
135 bool addScope(DIScope *Scope);
136 bool addSubprogram(DISubprogram *SP);
137 bool addType(DIType *DT);
138
139public:
140 using compile_unit_iterator =
141 SmallVectorImpl<DICompileUnit *>::const_iterator;
142 using subprogram_iterator = SmallVectorImpl<DISubprogram *>::const_iterator;
143 using global_variable_expression_iterator =
144 SmallVectorImpl<DIGlobalVariableExpression *>::const_iterator;
145 using type_iterator = SmallVectorImpl<DIType *>::const_iterator;
146 using scope_iterator = SmallVectorImpl<DIScope *>::const_iterator;
147
148 iterator_range<compile_unit_iterator> compile_units() const {
149 return make_range(x: CUs.begin(), y: CUs.end());
150 }
151
152 iterator_range<subprogram_iterator> subprograms() const {
153 return make_range(x: SPs.begin(), y: SPs.end());
154 }
155
156 iterator_range<global_variable_expression_iterator> global_variables() const {
157 return make_range(x: GVs.begin(), y: GVs.end());
158 }
159
160 iterator_range<type_iterator> types() const {
161 return make_range(x: TYs.begin(), y: TYs.end());
162 }
163
164 iterator_range<scope_iterator> scopes() const {
165 return make_range(x: Scopes.begin(), y: Scopes.end());
166 }
167
168 unsigned compile_unit_count() const { return CUs.size(); }
169 unsigned global_variable_count() const { return GVs.size(); }
170 unsigned subprogram_count() const { return SPs.size(); }
171 unsigned type_count() const { return TYs.size(); }
172 unsigned scope_count() const { return Scopes.size(); }
173
174private:
175 SmallVector<DICompileUnit *, 8> CUs;
176 SmallVector<DISubprogram *, 8> SPs;
177 SmallVector<DIGlobalVariableExpression *, 8> GVs;
178 SmallVector<DIType *, 8> TYs;
179 SmallVector<DIScope *, 8> Scopes;
180 SmallPtrSet<const MDNode *, 32> NodesSeen;
181};
182
183/// Assignment Tracking (at).
184namespace at {
185//
186// Utilities for enumerating storing instructions from an assignment ID.
187//
188/// A range of instructions.
189using AssignmentInstRange =
190 iterator_range<SmallVectorImpl<Instruction *>::iterator>;
191/// Return a range of instructions (typically just one) that have \p ID
192/// as an attachment.
193/// Iterators invalidated by adding or removing DIAssignID metadata to/from any
194/// instruction (including by deleting or cloning instructions).
195LLVM_ABI AssignmentInstRange getAssignmentInsts(DIAssignID *ID);
196/// Return a range of instructions (typically just one) that perform the
197/// assignment that \p DAI encodes.
198/// Iterators invalidated by adding or removing DIAssignID metadata to/from any
199/// instruction (including by deleting or cloning instructions).
200inline AssignmentInstRange getAssignmentInsts(const DbgAssignIntrinsic *DAI) {
201 return getAssignmentInsts(ID: DAI->getAssignID());
202}
203
204inline AssignmentInstRange getAssignmentInsts(const DbgVariableRecord *DVR) {
205 assert(DVR->isDbgAssign() &&
206 "Can't get assignment instructions for non-assign DVR!");
207 return getAssignmentInsts(ID: DVR->getAssignID());
208}
209
210//
211// Utilities for enumerating llvm.dbg.assign intrinsic from an assignment ID.
212//
213/// High level: this is an iterator for llvm.dbg.assign intrinsics.
214/// Implementation details: this is a wrapper around Value's User iterator that
215/// dereferences to a DbgAssignIntrinsic ptr rather than a User ptr.
216class DbgAssignIt
217 : public iterator_adaptor_base<DbgAssignIt, Value::user_iterator,
218 typename std::iterator_traits<
219 Value::user_iterator>::iterator_category,
220 DbgAssignIntrinsic *, std::ptrdiff_t,
221 DbgAssignIntrinsic **,
222 DbgAssignIntrinsic *&> {
223public:
224 DbgAssignIt(Value::user_iterator It) : iterator_adaptor_base(It) {}
225 DbgAssignIntrinsic *operator*() const { return cast<DbgAssignIntrinsic>(Val: *I); }
226};
227/// A range of llvm.dbg.assign intrinsics.
228using AssignmentMarkerRange = iterator_range<DbgAssignIt>;
229/// Return a range of dbg.assign intrinsics which use \ID as an operand.
230/// Iterators invalidated by deleting an intrinsic contained in this range.
231LLVM_ABI AssignmentMarkerRange getAssignmentMarkers(DIAssignID *ID);
232/// Return a range of dbg.assign intrinsics for which \p Inst performs the
233/// assignment they encode.
234/// Iterators invalidated by deleting an intrinsic contained in this range.
235inline AssignmentMarkerRange getAssignmentMarkers(const Instruction *Inst) {
236 if (auto *ID = Inst->getMetadata(KindID: LLVMContext::MD_DIAssignID))
237 return getAssignmentMarkers(ID: cast<DIAssignID>(Val: ID));
238 else
239 return make_range(x: Value::user_iterator(), y: Value::user_iterator());
240}
241
242inline SmallVector<DbgVariableRecord *>
243getDVRAssignmentMarkers(const Instruction *Inst) {
244 if (auto *ID = Inst->getMetadata(KindID: LLVMContext::MD_DIAssignID))
245 return cast<DIAssignID>(Val: ID)->getAllDbgVariableRecordUsers();
246 return {};
247}
248
249/// Delete the llvm.dbg.assign intrinsics linked to \p Inst.
250LLVM_ABI void deleteAssignmentMarkers(const Instruction *Inst);
251
252/// Replace all uses (and attachments) of \p Old with \p New.
253LLVM_ABI void RAUW(DIAssignID *Old, DIAssignID *New);
254
255/// Remove all Assignment Tracking related intrinsics and metadata from \p F.
256LLVM_ABI void deleteAll(Function *F);
257
258/// Calculate the fragment of the variable in \p DAI covered
259/// from (Dest + SliceOffsetInBits) to
260/// to (Dest + SliceOffsetInBits + SliceSizeInBits)
261///
262/// Return false if it can't be calculated for any reason.
263/// Result is set to nullopt if the intersect equals the variable fragment (or
264/// variable size) in DAI.
265///
266/// Result contains a zero-sized fragment if there's no intersect.
267LLVM_ABI bool
268calculateFragmentIntersect(const DataLayout &DL, const Value *Dest,
269 uint64_t SliceOffsetInBits, uint64_t SliceSizeInBits,
270 const DbgAssignIntrinsic *DbgAssign,
271 std::optional<DIExpression::FragmentInfo> &Result);
272LLVM_ABI bool
273calculateFragmentIntersect(const DataLayout &DL, const Value *Dest,
274 uint64_t SliceOffsetInBits, uint64_t SliceSizeInBits,
275 const DbgVariableRecord *DVRAssign,
276 std::optional<DIExpression::FragmentInfo> &Result);
277
278/// Replace DIAssignID uses and attachments with IDs from \p Map.
279/// If an ID is unmapped a new ID is generated and added to \p Map.
280LLVM_ABI void remapAssignID(DenseMap<DIAssignID *, DIAssignID *> &Map,
281 Instruction &I);
282
283/// Helper struct for trackAssignments, below. We don't use the similar
284/// DebugVariable class because trackAssignments doesn't (yet?) understand
285/// partial variables (fragment info) as input and want to make that clear and
286/// explicit using types. In addition, eventually we will want to understand
287/// expressions that modify the base address too, which a DebugVariable doesn't
288/// capture.
289struct VarRecord {
290 DILocalVariable *Var;
291 DILocation *DL;
292
293 VarRecord(DbgVariableIntrinsic *DVI)
294 : Var(DVI->getVariable()), DL(getDebugValueLoc(DII: DVI)) {}
295 VarRecord(DbgVariableRecord *DVR)
296 : Var(DVR->getVariable()), DL(getDebugValueLoc(DVR)) {}
297 VarRecord(DILocalVariable *Var, DILocation *DL) : Var(Var), DL(DL) {}
298 friend bool operator<(const VarRecord &LHS, const VarRecord &RHS) {
299 return std::tie(args: LHS.Var, args: LHS.DL) < std::tie(args: RHS.Var, args: RHS.DL);
300 }
301 friend bool operator==(const VarRecord &LHS, const VarRecord &RHS) {
302 return std::tie(args: LHS.Var, args: LHS.DL) == std::tie(args: RHS.Var, args: RHS.DL);
303 }
304};
305
306} // namespace at
307
308template <> struct DenseMapInfo<at::VarRecord> {
309 static inline at::VarRecord getEmptyKey() {
310 return at::VarRecord(DenseMapInfo<DILocalVariable *>::getEmptyKey(),
311 DenseMapInfo<DILocation *>::getEmptyKey());
312 }
313
314 static inline at::VarRecord getTombstoneKey() {
315 return at::VarRecord(DenseMapInfo<DILocalVariable *>::getTombstoneKey(),
316 DenseMapInfo<DILocation *>::getTombstoneKey());
317 }
318
319 static unsigned getHashValue(const at::VarRecord &Var) {
320 return hash_combine(args: Var.Var, args: Var.DL);
321 }
322
323 static bool isEqual(const at::VarRecord &A, const at::VarRecord &B) {
324 return A == B;
325 }
326};
327
328namespace at {
329/// Map of backing storage to a set of variables that are stored to it.
330/// TODO: Backing storage shouldn't be limited to allocas only. Some local
331/// variables have their storage allocated by the calling function (addresses
332/// passed in with sret & byval parameters).
333using StorageToVarsMap =
334 DenseMap<const AllocaInst *, SmallSetVector<VarRecord, 2>>;
335
336/// Track assignments to \p Vars between \p Start and \p End.
337
338LLVM_ABI void trackAssignments(Function::iterator Start, Function::iterator End,
339 const StorageToVarsMap &Vars,
340 const DataLayout &DL, bool DebugPrints = false);
341
342/// Describes properties of a store that has a static size and offset into a
343/// some base storage. Used by the getAssignmentInfo functions.
344struct AssignmentInfo {
345 AllocaInst const *Base; ///< Base storage.
346 uint64_t OffsetInBits; ///< Offset into Base.
347 uint64_t SizeInBits; ///< Number of bits stored.
348 bool StoreToWholeAlloca; ///< SizeInBits equals the size of the base storage.
349
350 AssignmentInfo(const DataLayout &DL, AllocaInst const *Base,
351 uint64_t OffsetInBits, uint64_t SizeInBits)
352 : Base(Base), OffsetInBits(OffsetInBits), SizeInBits(SizeInBits),
353 StoreToWholeAlloca(
354 OffsetInBits == 0 &&
355 SizeInBits == DL.getTypeSizeInBits(Ty: Base->getAllocatedType())) {}
356};
357
358LLVM_ABI std::optional<AssignmentInfo> getAssignmentInfo(const DataLayout &DL,
359 const MemIntrinsic *I);
360LLVM_ABI std::optional<AssignmentInfo> getAssignmentInfo(const DataLayout &DL,
361 const StoreInst *SI);
362LLVM_ABI std::optional<AssignmentInfo> getAssignmentInfo(const DataLayout &DL,
363 const AllocaInst *AI);
364
365} // end namespace at
366
367/// Convert @llvm.dbg.declare intrinsics into sets of @llvm.dbg.assign
368/// intrinsics by treating stores to the dbg.declare'd address as assignments
369/// to the variable. Not all kinds of variables are supported yet; those will
370/// be left with their dbg.declare intrinsics.
371/// The pass sets the debug-info-assignment-tracking module flag to true to
372/// indicate assignment tracking has been enabled.
373class AssignmentTrackingPass : public PassInfoMixin<AssignmentTrackingPass> {
374 /// Note: this method does not set the debug-info-assignment-tracking module
375 /// flag.
376 bool runOnFunction(Function &F);
377
378public:
379 LLVM_ABI PreservedAnalyses run(Function &F, FunctionAnalysisManager &AM);
380 LLVM_ABI PreservedAnalyses run(Module &M, ModuleAnalysisManager &AM);
381};
382
383/// Return true if assignment tracking is enabled for module \p M.
384LLVM_ABI bool isAssignmentTrackingEnabled(const Module &M);
385
386} // end namespace llvm
387
388#endif // LLVM_IR_DEBUGINFO_H
389