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

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