Skip to content

Commit a8e03ae

Browse files
SLTozerSLTozer
authored
[DebugInfo][RemoveDIs] Add documentation for updating code to handle debug records (#93562)
Although the patch that enables debug records by default has been temporarily reverted, it will (eventually) be reverted and everyone's code will be subjected to the new debug info format. Although this is broadly a good thing, it is important that the documentation has enough information to guide users through the update; this patch adds what should hopefully be enough detail for most users to either find the answers, or find out how to find those answers.
1 parent 32546bd commit a8e03ae

File tree

1 file changed

+200
-13
lines changed

1 file changed

+200
-13
lines changed

‎llvm/docs/RemoveDIsDebugInfo.md

Lines changed: 200 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,16 @@ The debug records are not instructions, do not appear in the instruction list, a
2424

2525
# Great, what do I need to do!
2626

27-
Approximately nothing -- we've already instrumented all of LLVM to handle these new records ("`DbgRecords`") and behave identically to past LLVM behaviour. We plan on turning this on by default some time soon, with IR converted to the intrinsic form of debug info at terminals (textual IR, bitcode) for a short while, before then changing the textual IR and bitcode formats.
27+
Very little -- we've already instrumented all of LLVM to handle these new records ("`DbgRecords`") and behave identically to past LLVM behaviour. This is currently being turned on by default, so that `DbgRecords` will be used by default in memory, IR, and bitcode.
28+
29+
## API Changes
2830

2931
There are two significant changes to be aware of. Firstly, we're adding a single bit of debug relevant data to the `BasicBlock::iterator` class (it's so that we can determine whether ranges intend on including debug info at the beginning of a block or not). That means when writing passes that insert LLVM IR instructions, you need to identify positions with `BasicBlock::iterator` rather than just a bare `Instruction *`. Most of the time this means that after identifying where you intend on inserting something, you must also call `getIterator` on the instruction position -- however when inserting at the start of a block you _must_ use `getFirstInsertionPt`, `getFirstNonPHIIt` or `begin` and use that iterator to insert, rather than just fetching a pointer to the first instruction.
3032

3133
The second matter is that if you transfer sequences of instructions from one place to another manually, i.e. repeatedly using `moveBefore` where you might have used `splice`, then you should instead use the method `moveBeforePreserving`. `moveBeforePreserving` will transfer debug info records with the instruction they're attached to. This is something that happens automatically today -- if you use `moveBefore` on every element of an instruction sequence, then debug intrinsics will be moved in the normal course of your code, but we lose this behaviour with non-instruction debug info.
3234

35+
For a more in-depth overview of how to update existing code to support debug records, see [the guide below](#how-to-update-existing-code).
36+
3337
# C-API changes
3438

3539
All the functions that have been added are temporary and will be deprecated in the future. The intention is that they'll help downstream projects adapt during the transition period.
@@ -58,13 +62,9 @@ LLVMDIBuilderInsertDbgValueBefore # Same as above.
5862
LLVMDIBuilderInsertDbgValueAtEnd # Same as above.
5963
```
6064

61-
# Anything else?
62-
63-
Not really, but here's an "old vs new" comparison of how to do certain things and quickstart for how this "new" debug info is structured.
65+
# The new "Debug Record" model
6466

65-
## Skipping debug records, ignoring debug-uses of Values, stably counting instructions...
66-
67-
This will all happen transparently without needing to think about it!
67+
Below is a brief overview of the new representation that replaces debug intrinsics; for an instructive guide on updating old code, see [here](#how-to-update-existing-code).
6868

6969
## What exactly have you replaced debug intrinsics with?
7070

@@ -106,21 +106,204 @@ Not shown are the links from DbgRecord to other parts of the `Value`/`Metadata`
106106

107107
The various kinds of debug intrinsic (value, declare, assign, label) are all stored in `DbgRecord` subclasses, with a "RecordKind" field distinguishing `DbgLabelRecord`s from `DbgVariableRecord`s, and a `LocationType` field in the `DbgVariableRecord` class further disambiguating the various debug variable intrinsics it can represent.
108108

109-
## Finding debug info records
109+
# How to update existing code
110+
111+
Any existing code that interacts with debug intrinsics in some way will need to be updated to interact with debug records in the same way. A few quick rules to keep in mind when updating code:
112+
113+
- Debug records will not be seen when iterating over instructions; to find the debug records that appear immediately before an instruction, you'll need to iterate over `Instruction::getDbgRecordRange()`.
114+
- Debug records have interfaces that are identical to those of debug intrinsics, meaning that any code that operates on debug intrinsics can be trivially applied to debug records as well. The exceptions for this are `Instruction` or `CallInst` methods that don't logically apply to debug records, and `isa`/`cast`/`dyn_cast` methods, are replaced by methods on the `DbgRecord` class itself.
115+
- Debug records cannot appear in a module that also contains debug intrinsics; the two are mutually exclusive. As debug records are the future format, handling records correctly should be prioritized in new code.
116+
- Until support for intrinsics is no longer present, a valid hotfix for code that only handles debug intrinsics and is non-trivial to update is to convert the module to the intrinsic format using `Module::setIsNewDbgInfoFormat`, and convert it back afterwards.
117+
- This can also be performed within a lexical scope for a module or an individual function using the class `ScopedDbgInfoFormatSetter`:
118+
```
119+
void handleModule(Module &M) {
120+
{
121+
ScopedDbgInfoFormatSetter FormatSetter(M, false);
122+
handleModuleWithDebugIntrinsics(M);
123+
}
124+
// Module returns to previous debug info format after exiting the above block.
125+
}
126+
```
127+
128+
Below is a rough guide on how existing code that currently supports debug intrinsics can be updated to support debug records.
129+
130+
## Creating debug records
131+
132+
Debug records will automatically be created by the `DIBuilder` class when the new format is enabled. As with instructions, it is also possible to call `DbgRecord::clone` to create an unattached copy of an existing record.
133+
134+
## Skipping debug records, ignoring debug-uses of `Values`, stably counting instructions, etc.
135+
136+
This will all happen transparently without needing to think about it!
137+
138+
```
139+
for (Instruction &I : BB) {
140+
// Old: Skips debug intrinsics
141+
if (isa<DbgInfoIntrinsic>(&I))
142+
continue;
143+
// New: No extra code needed, debug records are skipped by default.
144+
...
145+
}
146+
```
147+
148+
## Finding debug records
110149

111150
Utilities such as `findDbgUsers` and the like now have an optional argument that will return the set of `DbgVariableRecord` records that refer to a `Value`. You should be able to treat them the same as intrinsics.
112151

113-
## Examining debug info records at positions
152+
```
153+
// Old:
154+
SmallVector<DbgVariableIntrinsic *> DbgUsers;
155+
findDbgUsers(DbgUsers, V);
156+
for (auto *DVI : DbgUsers) {
157+
if (DVI->getParent() != BB)
158+
DVI->replaceVariableLocationOp(V, New);
159+
}
160+
// New:
161+
SmallVector<DbgVariableIntrinsic *> DbgUsers;
162+
SmallVector<DbgVariableRecord *> DVRUsers;
163+
findDbgUsers(DbgUsers, V, &DVRUsers);
164+
for (auto *DVI : DbgUsers)
165+
if (DVI->getParent() != BB)
166+
DVI->replaceVariableLocationOp(V, New);
167+
for (auto *DVR : DVRUsers)
168+
if (DVR->getParent() != BB)
169+
DVR->replaceVariableLocationOp(V, New);
170+
```
171+
172+
## Examining debug records at positions
114173

115174
Call `Instruction::getDbgRecordRange()` to get the range of `DbgRecord` objects that are attached to an instruction.
116175

117-
## Moving around, deleting
176+
```
177+
for (Instruction &I : BB) {
178+
// Old: Uses a data member of a debug intrinsic, and then skips to the next
179+
// instruction.
180+
if (DbgInfoIntrinsic *DII = dyn_cast<DbgInfoIntrinsic>(&I)) {
181+
recordDebugLocation(DII->getDebugLoc());
182+
continue;
183+
}
184+
// New: Iterates over the debug records that appear before `I`, and treats
185+
// them identically to the intrinsic block above.
186+
// NB: This should always appear at the top of the for-loop, so that we
187+
// process the debug records preceding `I` before `I` itself.
188+
for (DbgRecord &DR = I.getDbgRecordRange()) {
189+
recordDebugLocation(DR.getDebugLoc());
190+
}
191+
processInstruction(I);
192+
}
193+
```
194+
195+
This can also be passed through the function `filterDbgVars` to specifically
196+
iterate over DbgVariableRecords, which are more commonly used.
197+
198+
```
199+
for (Instruction &I : BB) {
200+
// Old: If `I` is a DbgVariableIntrinsic we record the variable, and apply
201+
// extra logic if it is an `llvm.dbg.declare`.
202+
if (DbgVariableIntrinsic *DVI = dyn_cast<DbgVariableIntrinsic>(&I)) {
203+
recordVariable(DVI->getVariable());
204+
if (DbgDeclareInst *DDI = dyn_cast<DbgDeclareInst>(DVI))
205+
recordDeclareAddress(DDI->getAddress());
206+
continue;
207+
}
208+
// New: `filterDbgVars` is used to iterate over only DbgVariableRecords.
209+
for (DbgVariableRecord &DVR = filterDbgVars(I.getDbgRecordRange())) {
210+
recordVariable(DVR.getVariable());
211+
// Debug variable records are not cast to subclasses; simply call the
212+
// appropriate `isDbgX()` check, and use the methods as normal.
213+
if (DVR.isDbgDeclare())
214+
recordDeclareAddress(DVR.getAddress());
215+
}
216+
// ...
217+
}
218+
```
219+
220+
## Processing individual debug records
221+
222+
In most cases, any code that operates on debug intrinsics can be extracted to a template function or auto lambda (if it is not already in one) that can be applied to both debug intrinsics and debug records - though keep in mind the main exception that `isa`/`cast`/`dyn_cast` do not apply to `DbgVariableRecord` types.
118223

119-
You can use `DbgRecord::removeFromParent` to unlink a `DbgRecord` from it's marker, and then `BasicBlock::insertDbgRecordBefore` or `BasicBlock::insertDbgRecordAfter` to re-insert the `DbgRecord` somewhere else. You cannot insert a `DbgRecord` at an arbitary point in a list of `DbgRecord`s (if you're doing this with `dbg.value`s then it's unlikely to be correct).
224+
```
225+
// Old: Function that operates on debug variable intrinsics in a BasicBlock, and
226+
// collects llvm.dbg.declares.
227+
void processDbgInfoInBlock(BasicBlock &BB,
228+
SmallVectorImpl<DbgDeclareInst*> &DeclareIntrinsics) {
229+
for (Instruction &I : BB) {
230+
if (DbgVariableIntrinsic *DVI = dyn_cast<DbgVariableIntrinsic>(&I)) {
231+
processVariableValue(DebugVariable(DVI), DVI->getValue());
232+
if (DbgDeclareInst *DDI = dyn_cast<DbgDeclareInst>(DVI))
233+
Declares.push_back(DDI);
234+
else if (!isa<Constant>(DVI->getValue()))
235+
DVI->setKillLocation();
236+
}
237+
}
238+
}
239+
240+
// New: Template function is used to deduplicate handling of intrinsics and
241+
// records.
242+
// An overloaded function is also used to handle isa/cast/dyn_cast operations
243+
// for intrinsics and records, since those functions cannot be directly applied
244+
// to DbgRecords.
245+
DbgDeclareInst *DynCastToDeclare(DbgVariableIntrinsic *DVI) {
246+
return dyn_cast<DbgDeclareInst>(DVI);
247+
}
248+
DbgVariableRecord *DynCastToDeclare(DbgVariableRecord *DVR) {
249+
return DVR->isDbgDeclare() ? DVR : nullptr;
250+
}
251+
252+
template<typename DbgVarTy, DbgDeclTy>
253+
void processDbgVariable(DbgVarTy *DbgVar,
254+
SmallVectorImpl<DbgDeclTy*> &Declares) {
255+
processVariableValue(DebugVariable(DbgVar), DbgVar->getValue());
256+
if (DbgDeclTy *DbgDeclare = DynCastToDeclare(DbgVar))
257+
Declares.push_back(DbgDeclare);
258+
else if (!isa<Constant>(DbgVar->getValue()))
259+
DbgVar->setKillLocation();
260+
};
261+
262+
void processDbgInfoInBlock(BasicBlock &BB,
263+
SmallVectorImpl<DbgDeclareInst*> &DeclareIntrinsics,
264+
SmallVectorImpl<DbgVariableRecord*> &DeclareRecords) {
265+
for (Instruction &I : BB) {
266+
if (DbgVariableIntrinsic *DVI = dyn_cast<DbgVariableIntrinsic>(&I))
267+
processDbgVariable(DVI, DeclareIntrinsics);
268+
for (DbgVariableRecord *DVR : filterDbgVars(I.getDbgRecordRange()))
269+
processDbgVariable(DVR, DeclareRecords);
270+
}
271+
}
272+
```
273+
274+
## Moving and deleting debug records
120275

121-
Erase `DbgRecord`s by calling `eraseFromParent` or `deleteInstr` if it's already been removed.
276+
You can use `DbgRecord::removeFromParent` to unlink a `DbgRecord` from it's marker, and then `BasicBlock::insertDbgRecordBefore` or `BasicBlock::insertDbgRecordAfter` to re-insert the `DbgRecord` somewhere else. You cannot insert a `DbgRecord` at an arbitary point in a list of `DbgRecord`s (if you're doing this with `llvm.dbg.value`s then it's unlikely to be correct).
122277

123-
## What about dangling `DbgRecord`s?
278+
Erase `DbgRecord`s by calling `eraseFromParent`.
279+
280+
```
281+
// Old: Move a debug intrinsic to the start of the block, and delete all other intrinsics for the same variable in the block.
282+
void moveDbgIntrinsicToStart(DbgVariableIntrinsic *DVI) {
283+
BasicBlock *ParentBB = DVI->getParent();
284+
DVI->removeFromParent();
285+
for (Instruction &I : ParentBB) {
286+
if (auto *BlockDVI = dyn_cast<DbgVariableIntrinsic>(&I))
287+
if (BlockDVI->getVariable() == DVI->getVariable())
288+
BlockDVI->eraseFromParent();
289+
}
290+
DVI->insertBefore(ParentBB->getFirstInsertionPt());
291+
}
292+
293+
// New: Perform the same operation, but for a debug record.
294+
void moveDbgRecordToStart(DbgVariableRecord *DVR) {
295+
BasicBlock *ParentBB = DVR->getParent();
296+
DVR->removeFromParent();
297+
for (Instruction &I : ParentBB) {
298+
for (auto &BlockDVR : filterDbgVars(I.getDbgRecordRange()))
299+
if (BlockDVR->getVariable() == DVR->getVariable())
300+
BlockDVR->eraseFromParent();
301+
}
302+
DVR->insertBefore(ParentBB->getFirstInsertionPt());
303+
}
304+
```
305+
306+
## What about dangling debug records?
124307

125308
If you have a block like so:
126309

@@ -134,3 +317,7 @@ If you have a block like so:
134317
your optimisation pass may wish to erase the terminator and then do something to the block. This is easy to do when debug info is kept in instructions, but with `DbgRecord`s there is no trailing instruction to attach the variable information to in the block above, once the terminator is erased. For such degenerate blocks, `DbgRecord`s are stored temporarily in a map in `LLVMContext`, and are re-inserted when a terminator is reinserted to the block or other instruction inserted at `end()`.
135318

136319
This can technically lead to trouble in the vanishingly rare scenario where an optimisation pass erases a terminator and then decides to erase the whole block. (We recommend not doing that).
320+
321+
## Anything else?
322+
323+
The above guide does not comprehensively cover every pattern that could apply to debug intrinsics; as mentioned at the [start of the guide](#how-to-update-existing-code), you can temporarily convert the target module from debug records to intrinsics as a stopgap measure. Most operations that can be performed on debug intrinsics have exact equivalents for debug records, but if you encounter any exceptions, reading the class docs (linked [here](#what-exactly-have-you-replaced-debug-intrinsics-with)) may give some insight, there may be examples in the existing codebase, and you can always ask for help on the [forums](https://discourse.llvm.org/tag/debuginfo).

0 commit comments

Comments
 (0)