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

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