1//===-- SPIRVNonSemanticDebugHandler.h - NSDI AsmPrinter handler -*- C++
2//-*-===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9//
10// This file declares SPIRVNonSemanticDebugHandler, a DebugHandlerBase subclass
11// that emits NonSemantic.Shader.DebugInfo.100 instructions in the SPIR-V
12// AsmPrinter. It replaces SPIRVEmitNonSemanticDI, which was a
13// MachineFunctionPass, with a handler that controls instruction placement
14// directly instead of routing through SPIRVModuleAnalysis.
15//
16//===----------------------------------------------------------------------===//
17
18#ifndef LLVM_LIB_TARGET_SPIRV_SPIRVNONSEMANTICDEBUGHANDLER_H
19#define LLVM_LIB_TARGET_SPIRV_SPIRVNONSEMANTICDEBUGHANDLER_H
20
21#include "MCTargetDesc/SPIRVBaseInfo.h"
22#include "SPIRVModuleAnalysis.h"
23#include "llvm/ADT/DenseMap.h"
24#include "llvm/ADT/DenseSet.h"
25#include "llvm/ADT/SetVector.h"
26#include "llvm/ADT/SmallPtrSet.h"
27#include "llvm/ADT/SmallString.h"
28#include "llvm/ADT/SmallVector.h"
29#include "llvm/ADT/StringMap.h"
30#include "llvm/CodeGen/DebugHandlerBase.h"
31#include "llvm/IR/DebugInfoMetadata.h"
32#include "llvm/MC/MCInst.h"
33#include "llvm/MC/MCRegister.h"
34#include <optional>
35#include <type_traits>
36#include <utility>
37
38namespace llvm {
39
40class GlobalVariable;
41struct SPIRVOptions;
42class MachineDominatorTree;
43class SPIRVSubtarget;
44
45/// AsmPrinter handler that emits NonSemantic.Shader.DebugInfo.100 (NSDI)
46/// instructions for the SPIR-V backend. Registered with SPIRVAsmPrinter when
47/// the module contains debug info (llvm.dbg.cu).
48///
49/// Call sequence:
50/// - beginModule() collects compile-unit metadata.
51/// - prepareModuleOutput() adds the extension and ext-inst set to MAI.
52/// - emitNonSemanticDebugStrings() emits NSDI OpStrings in section 7.
53/// - emitNonSemanticGlobalDebugInfo() emits module-scope NSDI and sets
54/// GlobalNSDIEnabled.
55/// - beginFunctionImpl() prepares per-function DebugFunctionDefinition state
56/// and runs analyzeDebugRecords() over the whole function.
57/// - endInstruction() emits DebugFunctionDefinition after the last function-
58/// level OpVariable; SPIRVAsmPrinter calls notifyEntryLabelEmitted() after
59/// the synthesized entry OpLabel when there are no OpVariables.
60/// - beginInstruction() emits the DebugScope and DebugLine for the instruction
61/// being printed, and the DebugDeclare and DebugValue anchored on it.
62/// - endFunctionImpl() resets per-function state.
63class SPIRVNonSemanticDebugHandler : public DebugHandlerBase {
64 const SPIRVOptions &CLOpts;
65
66 static constexpr unsigned NSSet = static_cast<unsigned>(
67 SPIRV::InstructionSet::NonSemantic_Shader_DebugInfo_100);
68
69 struct CompileUnitInfo {
70 const DICompileUnit *TheCU = nullptr;
71 SmallString<128> FilePath;
72 unsigned SpirvSourceLanguage = 0; // NonSemantic.Shader.DebugInfo.100 source
73 // language code (section 4.3)
74 };
75 SmallVector<CompileUnitInfo> CompileUnits;
76 int64_t DwarfVersion = 0;
77
78 SmallVector<const DIType *> DebugTypes;
79
80 // Compile unit whose enums list names each enum. DIBuilder gives a file-scope
81 // enum a null scope, so this list is the only record of its unit.
82 DenseMap<const DICompositeType *, const DICompileUnit *> EnumCompileUnits;
83
84 // NonSemantic debug instruction result id per emitted scope.
85 DenseMap<const DIScope *, MCRegister> DebugScopeRegs;
86
87 enum class EmitStatus {
88 Emitted,
89 Unsupported,
90 InProgress,
91 };
92
93 // One scope instruction, built but not yet emitted. getOrCreateDebugScope
94 // is the only place that emits it.
95 struct PreparedScope {
96 SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode{};
97 SmallVector<MCRegister, 8> Operands;
98
99 PreparedScope() = default;
100 PreparedScope(SPIRV::NonSemanticExtInst::NonSemanticExtInst Op,
101 ArrayRef<MCRegister> Ops)
102 : Opcode(Op), Operands(Ops.begin(), Ops.end()) {}
103 };
104
105 // Status plus a payload. Value is set only when the status is Emitted, so
106 // InProgress and Unsupported carry no id and no PreparedScope. The payload
107 // is an id for a scope that already exists, and a PreparedScope for an
108 // instruction that getOrCreateDebugScope has not emitted yet.
109 template <typename T> struct EmitResult {
110 EmitStatus Status = EmitStatus::Unsupported;
111 std::optional<T> Value;
112
113 static EmitResult emitted(T V) {
114 EmitResult R;
115 R.Status = EmitStatus::Emitted;
116 R.Value = std::move(V);
117 return R;
118 }
119 static EmitResult unsupported() { return {}; }
120 static EmitResult inProgress() {
121 EmitResult R;
122 R.Status = EmitStatus::InProgress;
123 return R;
124 }
125
126 template <typename U>
127 static EmitResult failure(const EmitResult<U> &Other) {
128 assert(!Other && "failure() requires a non-emitted result");
129 EmitResult R;
130 R.Status = Other.Status;
131 return R;
132 }
133
134 explicit operator bool() const {
135 assert(Value.has_value() == (Status == EmitStatus::Emitted) &&
136 "payload is set exactly when the result is emitted");
137 if constexpr (std::is_same_v<T, MCRegister>)
138 assert(!Value || Value->isValid());
139 return Status == EmitStatus::Emitted;
140 }
141 };
142
143 // Used to track which scopes are in progress, and which operands are used by
144 // a forward references. Operands must be later defined even if the scope
145 // fails to emit.
146 struct InProgressScope {
147 MCRegister Id;
148 bool ForwardReferenced = false;
149 };
150
151 // Types and scopes whose instruction is currently being built.
152 SmallDenseMap<const DIScope *, InProgressScope, 8> ScopesInProgress;
153
154 // True when -spirv-debug-scope-forward-refs is set and prepareModuleOutput
155 // saw SPV_KHR_relaxed_extended_instruction.
156 bool HasRelaxedExtInst = false;
157
158 // Types and scopes that are not supported.
159 SmallPtrSet<const DIScope *, 8> FailedScopes;
160
161 // DISubprogram nodes collected in beginModule().
162 SmallVector<const DISubprogram *> Subprograms;
163
164 // Distinct DILocations from instruction !dbg attachments and debug program
165 // records (#dbg_declare, #dbg_value, #dbg_assign, #dbg_label).
166 SetVector<const DILocation *> UniqueDebugLocations;
167
168 struct GlobalVariableDebugInfo {
169 const DIExpression *Expr = nullptr;
170 const GlobalVariable *LLVMGV = nullptr;
171 };
172 MapVector<const DIGlobalVariable *, GlobalVariableDebugInfo>
173 GlobalVariableDebugInfoMap;
174
175 // Distinct DILocalVariable nodes collected in beginModule() from dbg records
176 // and from DISubprogram retained nodes.
177 SetVector<const DILocalVariable *> LocalVariables;
178
179 // DebugLocalVariable result id per variable that module-scope emission
180 // actually emitted. DebugDeclare needs it for its Local Variable operand; a
181 // variable missing here (skipped type or scope) gets no declare.
182 DenseMap<const DILocalVariable *, MCRegister> DebugLocalVariableRegs;
183
184 // DebugExpression result id per DIExpression that could be lowered. An
185 // expression missing here uses operations with no NonSemantic counterpart,
186 // so declares referencing it are skipped rather than described wrongly.
187 DenseMap<const DIExpression *, MCRegister> DebugExpressionRegs;
188
189 // Distinct DILexicalBlock, DINamespace, and DILexicalBlockFile scopes,
190 // parent-before-child order, collected in beginModule().
191 SetVector<const DIScope *> LexicalBlocks;
192
193 // DebugInlinedAt result id per DILocation used as an inlined-at chain link.
194 DenseMap<const DILocation *, MCRegister> DebugInlinedAtRegs;
195
196 // Path \c OpString result id per \c DIScope (CU, \c DIFile, declaration
197 // \c DISubprogram, …). Filled during \c emitNonSemanticDebugStrings() using
198 // \c getDebugFullPath + \c emitOpStringIfNew; section 10 uses it for
199 // \c DebugSource without recomputing path text.
200 DenseMap<const DIScope *, MCRegister> ScopeToPathOpStringReg;
201
202 // DebugSource result id keyed by path \c OpString id (\c MCRegister::id()),
203 // deduplicating when the same file string is reused.
204 DenseMap<unsigned, MCRegister> DebugSourceRegByFileStr;
205
206 // Maps OpString contents to result id. Populated only by emitOpStringIfNew()
207 // during section 7; section 10 uses getCachedOpStringReg() (lookup only).
208 StringMap<MCRegister> OpStringContentCache;
209
210#ifndef NDEBUG // Only declare the variable for debugging purposes.
211 // True after emitNonSemanticDebugStrings() emitted the NSDI OpStrings for
212 // this module. SPIRVAsmPrinter calls that before
213 // emitNonSemanticGlobalDebugInfo().
214 bool NonSemanticOpStringsSectionEmitted = false;
215#endif
216
217 MCRegister CachedEmptyStringReg;
218
219 MCRegister CachedDebugInfoNoneReg;
220
221 MCRegister CachedOpTypeVoidReg;
222
223 MCRegister CachedOpTypeInt32Reg;
224
225 // Result id per SPIR-V scalar type this handler needed, keyed by opcode and
226 // width. MB_TypeConstVars holds only what module analysis collected, so a
227 // type emitted here has to be remembered separately to stay unique.
228 DenseMap<std::pair<unsigned, int64_t>, MCRegister> ScalarTypeCache;
229
230 // Result id per scalar constant, keyed by its type's id and its bits. Keying
231 // on the type lets two DIBasicTypes describing it share a constant.
232 DenseMap<std::pair<unsigned, uint64_t>, MCRegister> ScalarConstantCache;
233
234 // Result id per collected constant, keyed by its type and bits. Filled
235 // during module-scope emission, since an OpConstant has to precede every
236 // function body that names it.
237 DenseMap<std::pair<const DIBasicType *, uint64_t>, MCRegister>
238 ConstantValueRegs;
239
240 // Cache of already-emitted DebugOperation instructions, keyed by NonSemantic
241 // opcode followed by the 32-bit operation arguments. Inline size 3 is the
242 // spec maximum (opcode plus at most two operands: BitPiece, Fragment).
243 DenseMap<SmallVector<uint32_t, 3>, MCRegister> DebugOperationCache;
244
245 // Cache of already-emitted DebugExpression instructions, keyed by the
246 // DebugOperation result ids in operand order. Useful for debug values
247 // and global-variable init expressions.
248 DenseMap<SmallVector<MCRegister>, MCRegister> DebugExpressionCache;
249
250 // True once emitNonSemanticGlobalDebugInfo() has run. Both
251 // SPIRVAsmPrinter::emitFunctionHeader() and emitEndOfAsmFile() may call
252 // outputModuleSections(), each guarded by ModuleSectionsEmitted, so only
253 // one fires. This flag provides a secondary guard in case the call sites
254 // change.
255 bool GlobalDIEmitted = false;
256
257 // True when emitNonSemanticGlobalDebugInfo() completed module-scope NSDI
258 // emission for this module.
259 bool GlobalNSDIEnabled = false;
260
261 SPIRV::ModuleAnalysisInfo *CurrentMAI = nullptr;
262
263 const MachineFunction *CurrentMF = nullptr;
264
265 const MachineInstr *LastFunctionOpVariable = nullptr;
266
267 bool DebugFunctionDefinitionEmitted = false;
268
269 // Instruction that opened the DebugLine / DebugScope region currently in
270 // effect, or nullptr when no region is open. The two are tracked separately
271 // because a DebugScope region usually spans several DebugLine regions, and
272 // either one can skip emission on a cache miss.
273 const MachineInstr *LastLineMI = nullptr;
274 const MachineInstr *LastScopeMI = nullptr;
275
276 // Result ids in MB_TypeConstVars, which precedes every function body. Filled
277 // once per module in prepareModuleOutput().
278 DenseSet<MCRegister> ModuleScopeIds;
279
280 /// A DebugDeclare or DebugValue waiting for its anchor to be printed.
281 struct DebugRecord {
282 const MachineInstr *MI; ///< The DBG_VALUE this came from.
283 SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode;
284 MCRegister LocationReg; ///< The Variable or Value operand.
285 };
286
287 // Records to emit before their anchor is printed, built once per function by
288 // analyzeDebugRecords() and only read afterwards.
289 DenseMap<const MachineInstr *, SmallVector<DebugRecord>> Records;
290
291public:
292 explicit SPIRVNonSemanticDebugHandler(AsmPrinter &AP);
293
294 /// Collect compile-unit metadata from the module. Called by
295 /// AsmPrinter::doInitialization() via the handler list. No emission.
296 void beginModule(Module *M) override;
297
298 /// Emit OpString instructions for all NSDI file paths and basic type names
299 /// into the debug section (section 7 of the SPIR-V module layout). Must be
300 /// called from SPIRVAsmPrinter::outputDebugSourceAndStrings(), after
301 /// prepareModuleOutput() has registered the ext inst set. Registers are
302 /// stored in \c OpStringContentCache and \c ScopeToPathOpStringReg;
303 /// \c emitNonSemanticGlobalDebugInfo() resolves them via
304 /// \c getCachedOpStringReg() and path maps.
305 void emitNonSemanticDebugStrings(SPIRV::ModuleAnalysisInfo &MAI);
306
307 /// Add SPV_KHR_non_semantic_info extension and
308 /// NonSemantic.Shader.DebugInfo.100 ext inst set entry to MAI. Must be called
309 /// before outputGlobalRequirements() and outputOpExtInstImports() in
310 /// SPIRVAsmPrinter::outputModuleSections().
311 void prepareModuleOutput(const SPIRVSubtarget &ST,
312 SPIRV::ModuleAnalysisInfo &MAI);
313
314 /// Emit module-scope NSDI instructions (DebugSource, DebugCompilationUnit,
315 /// DebugTypeBasic, DebugTypePointer, DebugTypeFunction,
316 /// DebugFunctionDeclaration, DebugFunction). Called by
317 /// SPIRVAsmPrinter::outputModuleSections() at section 10 in place of
318 /// outputModuleSection(MB_NonSemanticGlobalDI). Requires
319 /// emitNonSemanticDebugStrings() to have run first when NSDI strings apply.
320 /// Sets \c GlobalNSDIEnabled when module-scope NSDI emission completes.
321 void emitNonSemanticGlobalDebugInfo(SPIRV::ModuleAnalysisInfo &MAI);
322
323 /// Called after the synthesized entry \c OpLabel has been emitted.
324 void notifyEntryLabelEmitted(const MachineFunction &MF);
325
326protected:
327 // All module-level output is driven by emitNonSemanticGlobalDebugInfo(),
328 // called explicitly from SPIRVAsmPrinter::outputModuleSections(). Nothing
329 // needs to happen in the AsmPrinterHandler::endModule() callback.
330 void endModule() override {}
331
332 // DebugHandlerBase stores MMI as a pointer copy from Asm->MMI at construction
333 // time (DebugHandlerBase.cpp: `MMI(Asm->MMI)`). The handler is constructed
334 // before AsmPrinter::doInitialization() runs, so Asm->MMI is null at that
335 // point and MMI remains null for this handler's entire lifetime. Do not call
336 // the base-class beginInstruction/endInstruction — they dereference MMI to
337 // create temp symbols for label tracking and would crash.
338 // Future local NSDI that needs MCContext must use
339 // Asm->OutStreamer->getContext() rather than MMI->getContext().
340 void beginInstruction(const MachineInstr *MI) override;
341 void endInstruction() override;
342
343 // Override beginFunctionImpl(), not beginFunction():
344 // DebugHandlerBase::beginFunction() populates LScopes and DbgValues needed
345 // for future DebugLine emission.
346 void beginFunctionImpl(const MachineFunction *MF) override;
347 void endFunctionImpl(const MachineFunction *MF) override;
348
349private:
350 void emitDebugFunctionDefinition(MCRegister DebugFunctionReg,
351 MCRegister OpFunctionReg,
352 SPIRV::ModuleAnalysisInfo &MAI);
353
354 void resetPerFunctionDebugState();
355
356 /// Resolve the instruction that a per-instruction DebugLine/DebugScope
357 /// update should attach to: \p MI adjusted forward past a merge
358 /// instruction to its terminator, or \c std::nullopt if \p MI is not a
359 /// valid attachment point (skip-emission, or one of the structural opcodes
360 /// that can never carry DebugLine/DebugScope: OpFunction,
361 /// OpFunctionParameter, OpFunctionEnd, OpLabel, OpPhi).
362 std::optional<const MachineInstr *>
363 resolveDebugLocTarget(const MachineInstr *MI);
364
365 /// Open the DebugScope region \p MI belongs to, closing the previous one.
366 ///
367 /// \returns False when \p MI's scope has no \c DebugScope, or its chain no
368 /// \c DebugInlinedAt, leaving the open region someone else's.
369 bool emitDebugScopeForInstruction(const MachineInstr *MI);
370 void emitDebugLineForInstruction(const MachineInstr *MI);
371 void preparePerFunctionDebug(const MachineFunction *MF);
372 void tryEmitDebugFunctionDefinition(SPIRV::ModuleAnalysisInfo &MAI);
373
374 void emitMCInst(MCInst &Inst);
375 MCRegister emitOpString(StringRef S, SPIRV::ModuleAnalysisInfo &MAI);
376
377 /// Section 7 only: emit OpString and cache it if not already present. Must
378 /// not be called after NonSemanticOpStringsSectionEmitted is set. Returns
379 /// the path (or string) \c OpString result id.
380 MCRegister emitOpStringIfNew(StringRef S, SPIRV::ModuleAnalysisInfo &MAI);
381
382 /// Section 10 only: lookup OpString id from cache; asserts if missing or if
383 /// section 7 did not complete.
384 MCRegister getCachedOpStringReg(StringRef S);
385
386 /// Section 7 only: emit the path \c OpString for \p Scope and cache it under
387 /// \p Scope. Returns the \c OpString result id. A \p Scope already seen
388 /// returns the cached id without rebuilding the path. A null \p Scope maps to
389 /// the empty path and is cached like any other, though section 10 reads it
390 /// through \c getCachedScopePathOpStringReg, which handles null separately.
391 MCRegister emitAndCacheScopePathOpStringReg(const DIScope *Scope,
392 SPIRV::ModuleAnalysisInfo &MAI);
393
394 /// Section 10 only: lookup path \c OpString id for \p Scope from
395 /// \c ScopeToPathOpStringReg; asserts if missing or invalid. When
396 /// \p UseEmptyPathIfNullScope is true and \p Scope is null, returns
397 /// \c CachedEmptyStringReg instead.
398 MCRegister
399 getCachedScopePathOpStringReg(const DIScope *Scope,
400 bool UseEmptyPathIfNullScope = false);
401 MCRegister emitOpConstantI32(uint32_t Value, MCRegister I32TypeReg,
402 SPIRV::ModuleAnalysisInfo &MAI);
403
404 /// Mark in-progress scopes named by \p Operands. Return true when any
405 /// operand is such an id. A marked id needs a definition if that scope fails.
406 bool markForwardReferencedOperands(ArrayRef<MCRegister> Operands);
407
408 MCRegister emitExtInst(SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode,
409 MCRegister VoidTypeReg, MCRegister ExtInstSetReg,
410 ArrayRef<MCRegister> Operands,
411 SPIRV::ModuleAnalysisInfo &MAI,
412 std::optional<MCRegister> ResultReg = std::nullopt);
413
414 /// Return OpTypeVoid id for this module (lazy lookup / emit, then cache).
415 MCRegister getOrEmitOpTypeVoidReg(SPIRV::ModuleAnalysisInfo &MAI);
416
417 /// Return OpTypeInt 32 0 id for this module (lazy lookup / emit, then cache).
418 MCRegister getOrEmitOpTypeInt32Reg(SPIRV::ModuleAnalysisInfo &MAI);
419
420 /// Find OpTypeVoid in the already-emitted TypeConstVars section, or emit one
421 /// if the module does not contain it (e.g. no void-returning functions).
422 MCRegister findOrEmitOpTypeVoid(SPIRV::ModuleAnalysisInfo &MAI);
423
424 /// Find OpTypeInt 32 0 in the already-emitted TypeConstVars section, or emit
425 /// one if the module does not contain it.
426 MCRegister findOrEmitOpTypeInt32(SPIRV::ModuleAnalysisInfo &MAI);
427
428 /// Return the id for the type or scope \p S, emitting it and the types and
429 /// scopes it names first. One already in \c DebugScopeRegs is Emitted. A null
430 /// \p S or one in \c FailedScopes is Unsupported. Entering a scope reserves
431 /// its result id. A back edge (\p S already in \c ScopesInProgress) returns
432 /// that id when \c HasRelaxedExtInst is set, and InProgress otherwise. If
433 /// emission fails after an emitted instruction used that id, it is defined as
434 /// DebugInfoNone. An id that nothing named stays undefined. An Unsupported
435 /// result is recorded in \c FailedScopes; an InProgress one is not, so a
436 /// later walk can retry it.
437 EmitResult<MCRegister> getOrCreateDebugScope(const DIScope *S);
438
439 /// Like \c getOrCreateDebugScope, but a null \p Ty (e.g. the base of a
440 /// \c void*) is Emitted as \c DebugInfoNone.
441 EmitResult<MCRegister> getOrCreateDebugTypeOrNone(const DIType *Ty);
442
443 /// Build the instruction for \p S. Only \c getOrCreateDebugScope calls this
444 /// and emits it.
445 EmitResult<PreparedScope> emitDebugScope(const DIScope *S);
446
447 /// Build the \c DebugType* instruction for \p CT, picked by its tag.
448 EmitResult<PreparedScope> emitDebugTypeForCompositeType(
449 const DICompositeType *CT, MCRegister VoidTypeReg, MCRegister I32TypeReg,
450 MCRegister ExtInstSetReg, SPIRV::ModuleAnalysisInfo &MAI);
451
452 /// Build the \c DebugType* instruction for \p DT, picked by its tag.
453 EmitResult<PreparedScope>
454 emitDebugTypeForDerivedType(const DIDerivedType *DT, MCRegister VoidTypeReg,
455 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
456 SPIRV::ModuleAnalysisInfo &MAI);
457
458 /// Build \c DebugTypeBasic for \p BT. Unsupported when the size does not fit
459 /// in 32 bits.
460 EmitResult<PreparedScope> emitDebugTypeBasic(const DIBasicType *BT,
461 MCRegister I32TypeReg,
462 SPIRV::ModuleAnalysisInfo &MAI);
463
464 /// Build \c DebugTypePointer for \p PT. Unsupported without a DWARF address
465 /// space, which gives the storage class.
466 EmitResult<PreparedScope>
467 emitDebugTypePointer(const DIDerivedType *PT, SPIRV::ModuleAnalysisInfo &MAI);
468
469 /// Build \c DebugTypeQualifier with Type Qualifier value \p Qualifier for
470 /// the qualified type \p QT. Uses \c DebugInfoNone as Base Type when \p QT
471 /// has none.
472 ///
473 /// \returns The base's status if it fails.
474 EmitResult<PreparedScope>
475 emitDebugTypeQualifier(const DIDerivedType *QT, uint32_t Qualifier,
476 SPIRV::ModuleAnalysisInfo &MAI);
477
478 /// Build one DebugTypeFunction for ST when every DI operand maps to a debug
479 /// type id; otherwise build nothing and return the first failing slot's
480 /// status.
481 EmitResult<PreparedScope>
482 emitDebugTypeFunctionForSubroutineType(const DISubroutineType *ST,
483 SPIRV::ModuleAnalysisInfo &MAI);
484
485 /// Build \c DebugFunctionDeclaration for the non-defining subprogram \p SP.
486 EmitResult<PreparedScope>
487 emitDebugFunctionDeclaration(const DISubprogram *SP, MCRegister VoidTypeReg,
488 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
489 SPIRV::ModuleAnalysisInfo &MAI);
490
491 /// Build \c DebugFunction for the defining subprogram \p SP.
492 EmitResult<PreparedScope> emitDebugFunction(const DISubprogram *SP,
493 MCRegister VoidTypeReg,
494 MCRegister I32TypeReg,
495 MCRegister ExtInstSetReg,
496 SPIRV::ModuleAnalysisInfo &MAI);
497
498 /// Emit \c DebugLocalVariable for the source local variable \p LV:
499 /// Name, Type, Source, Line, Column, Parent, Flags, and an optional Arg
500 /// Number. Line, Column, Flags, and Arg Number are emitted as \c OpConstant
501 /// ids as required for non-semantic debug info. Column is always 0:
502 /// \c DILocalVariable has no column field.
503 ///
504 /// Arg Number is appended when \p LV is a parameter.
505 ///
506 /// \returns The result id register on success. Returns \c std::nullopt and
507 /// emits nothing if \p LV's scope is not an emitted local scope,
508 /// if a non-null type was not emitted in \c DebugScopeRegs, or if
509 /// \c resolveScope returns no id for the Parent operand.
510 std::optional<MCRegister>
511 emitDebugLocalVariable(const DILocalVariable *LV, MCRegister VoidTypeReg,
512 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
513 SPIRV::ModuleAnalysisInfo &MAI);
514
515 /// Emit \c DebugGlobalVariable for the source global variable \p GV.
516 ///
517 /// (\c SPIRVDebug::Operand::GlobalVariable): Name, Type, Source, Line,
518 /// Column, Parent, Linkage Name, Variable, Flags, and an optional Static
519 /// Member Declaration. Line, Column, and Flags are emitted as \c OpConstant
520 /// ids as required for non-semantic debug info.
521 ///
522 /// \c DebugInfoNone is used for two operands when LLVM has no value to
523 /// supply:
524 /// \c Type when \p GV is a declaration with no DI type (e.g. \c extern void;
525 /// valid IR, \c isDefinition: false); \c Variable when no \c
526 /// llvm::GlobalVariable in this module carries \p GV in its \c !dbg metadata.
527 ///
528 /// \returns The result id register on success. Returns \c std::nullopt and
529 /// emits nothing if a non-null \p GV type was not emitted in \c
530 /// DebugScopeRegs, or \p GV has a static data member declaration that was not
531 /// emitted in \c DebugScopeRegs.
532 std::optional<MCRegister> emitDebugGlobalVariable(
533 const DIGlobalVariable *GV, const GlobalVariableDebugInfo &Info,
534 MCRegister VoidTypeReg, MCRegister I32TypeReg, MCRegister ExtInstSetReg,
535 SPIRV::ModuleAnalysisInfo &MAI);
536
537 /// Collect the \c DIExpression of every debug value in the module
538 /// (\c DBG_VALUE, \c DBG_VALUE_LIST, \c DBG_INSTR_REF), in MIR order.
539 ///
540 /// Reads MIR rather than IR because only MIR shows which debug values
541 /// survived codegen and in what form, and because an expression synthesized
542 /// during lowering never appears in the IR at all. Must be called from
543 /// module-scope emission, which is where the resulting \c DebugExpression
544 /// instructions have to be emitted. The debug values come from
545 /// \c SPIRVModuleAnalysis, which sees every \c MachineFunction.
546 ///
547 /// Deliberately independent of what the consumers can currently emit, so
548 /// that adding an instruction that needs an expression (\c DebugValue) needs
549 /// no change here. The cost is a \c DebugExpression that nothing references
550 /// yet, for a debug value no instruction is emitted for.
551 void collectDebugExpressions(const SPIRV::ModuleAnalysisInfo &MAI,
552 SetVector<const DIExpression *> &Out) const;
553
554 /// Emit one \c DebugOperation for \p Op, reusing a cached result id when the
555 /// same opcode and arguments were already emitted.
556 ///
557 /// \returns The result id register on success. Returns \c std::nullopt and
558 /// emits nothing if \p Op has no NonSemantic counterpart, or carries an
559 /// argument too large for the 32-bit \c OpConstant operands this set
560 /// requires.
561 std::optional<MCRegister>
562 emitDebugOperation(const DIExpression::ExprOperand &Op,
563 MCRegister VoidTypeReg, MCRegister I32TypeReg,
564 MCRegister ExtInstSetReg, SPIRV::ModuleAnalysisInfo &MAI);
565
566 /// Emit one \c DebugOperation per element of \p Expr followed by the
567 /// \c DebugExpression that lists them. Reuses a cached \c DebugExpression
568 /// when that sequence of \c DebugOperation ids was already emitted. An
569 /// empty \p Expr yields a \c DebugExpression with no operands, which is
570 /// what a plain \c !DIExpression() means.
571 ///
572 /// Must be called from module-scope emission only: \c DebugExpression and
573 /// \c DebugOperation are not in the spec's list of instructions allowed
574 /// inside a function, and forward references were removed in Rev 2.
575 ///
576 /// \returns The result id register on success. Returns \c std::nullopt and
577 /// does not emit the \c DebugExpression if any element has no NonSemantic
578 /// counterpart, or carries an argument too large for the 32-bit \c OpConstant
579 /// operands this set requires.
580 std::optional<MCRegister> emitDebugExpression(const DIExpression *Expr,
581 MCRegister VoidTypeReg,
582 MCRegister I32TypeReg,
583 MCRegister ExtInstSetReg,
584 SPIRV::ModuleAnalysisInfo &MAI);
585
586 /// Fill \c Records from the debug records in \p MF.
587 ///
588 /// Where a record may legally sit is a property of the whole function, and
589 /// emission is unbuffered, so it is settled here rather than while printing.
590 void analyzeDebugRecords(const MachineFunction &MF);
591
592 /// Place the single record \p MI. \p LastEmitted is the nearest preceding
593 /// instruction in this block that reaches the output, or null when there is
594 /// none.
595 ///
596 /// Places nothing when this backend cannot name the record: an unavailable
597 /// location, a declare whose storage is not an \c OpVariable, a constant
598 /// with no module-scope id, a physical register, a variadic value, an
599 /// instruction reference, or a definition that does not dominate \p MI.
600 void resolveDebugRecord(const MachineInstr &MI,
601 const MachineInstr *LastEmitted,
602 const MachineDominatorTree &DomTree);
603
604 /// Store \p MI on \p Anchor, to emit before \p Anchor is printed.
605 void placeRecord(SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode,
606 const MachineInstr &MI, MCRegister LocationReg,
607 const MachineInstr *Anchor);
608
609 void emitAnalyzedRecords(const MachineInstr *Anchor);
610
611 /// The \c OpConstant id for the constant \p MI assigns, or \c std::nullopt
612 /// when \p MI assigns no constant this backend emitted.
613 std::optional<MCRegister> getConstantValueReg(const MachineInstr &MI) const;
614
615 /// Result id of the constant \p Opcode of type \p TypeReg holding
616 /// \p Value in \c MB_TypeConstVars, or an invalid register when the module
617 /// does not already define it.
618 MCRegister findModuleConstant(unsigned Opcode, MCRegister TypeReg,
619 uint64_t Value, bool IsBool, bool IsWide,
620 SPIRV::ModuleAnalysisInfo &MAI);
621
622 /// Result id of the SPIR-V type for \p BT, reusing one from
623 /// \c MB_TypeConstVars when the module already defines it. Invalid when
624 /// declaring it would require a capability the module does not have, since
625 /// debug info must not change what the module requires.
626 MCRegister findOrEmitScalarType(const DIBasicType *BT,
627 SPIRV::ModuleAnalysisInfo &MAI);
628
629 /// Result id of the constant \p Value, with \p BT giving both the SPIR-V
630 /// type and the opcode. Invalid when the type may not be created.
631 MCRegister findOrEmitScalarConstant(const DIBasicType *BT, uint64_t Value,
632 SPIRV::ModuleAnalysisInfo &MAI);
633
634 /// Result id of the constant \p Value of type \p TypeReg, reusing one from
635 /// \c MB_TypeConstVars or from an earlier call when either already has it.
636 MCRegister findOrEmitConstant(unsigned Opcode, MCRegister TypeReg,
637 uint64_t Value, unsigned Width,
638 SPIRV::ModuleAnalysisInfo &MAI);
639
640 /// Emit \p Opcode naming \p MI's variable, \p LocationReg and \p MI's
641 /// expression, after \p MI's own \c DebugScope and \c DebugLine. Emits
642 /// nothing when \p MI's variable has no \c DebugLocalVariable, its
643 /// expression no \c DebugExpression, or its scope no id.
644 void emitDebugBinding(SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode,
645 const MachineInstr *MI, MCRegister LocationReg);
646
647 /// Build \c DebugTypeVector for the vector composite type \p VT.
648 ///
649 /// \returns Emitted when the operands are ready. Unsupported, building
650 /// nothing, if \p VT has no \c DIBasicType base type, if \p VT has more than
651 /// one \c DISubrange element, or if the component count is not a
652 /// compile-time constant. If the base cannot be emitted, returns its status.
653 EmitResult<PreparedScope> emitDebugTypeVector(const DICompositeType *VT,
654 SPIRV::ModuleAnalysisInfo &MAI);
655
656 /// Build \c DebugTypeArray for the array composite type \p AT.
657 ///
658 /// Operands are the element (base) type id followed by one Component Count
659 /// per \c DISubrange, in DWARF subrange order. A count that is not a
660 /// compile-time constant is 0, matching \c OpTypeRuntimeArray. A matrix
661 /// arrives here as a multi-subrange array and is built with one count per
662 /// dimension.
663 ///
664 /// \returns Emitted when the operands are ready. If \p AT's element type
665 /// cannot be emitted, builds nothing and returns the element's status.
666 EmitResult<PreparedScope> emitDebugTypeArray(const DICompositeType *AT,
667 SPIRV::ModuleAnalysisInfo &MAI);
668
669 /// Build \c DebugTypeMember for the data member \p M (a \c DIDerivedType with
670 /// \c DW_TAG_member). Operands: Name, Type, Source, Line, Column, Offset,
671 /// Size, Flags. NonSemantic \c DebugTypeMember carries no Parent operand: the
672 /// enclosing \c DebugTypeComposite references its members, not the reverse.
673 ///
674 /// \returns Emitted when the operands are ready. Returns the base's status
675 /// and builds nothing if \p M's type cannot be emitted.
676 EmitResult<PreparedScope> emitDebugTypeMember(const DIDerivedType *M,
677 MCRegister VoidTypeReg,
678 MCRegister I32TypeReg,
679 MCRegister ExtInstSetReg,
680 SPIRV::ModuleAnalysisInfo &MAI);
681
682 /// Build \c DebugTypeComposite for the struct, class, or union \p CT, after a
683 /// \c DebugTypeMember for each data member whose type can be emitted. A
684 /// forward declaration uses \c DebugInfoNone for Size and no members.
685 ///
686 /// \returns Emitted when the operands are ready. Builds nothing and returns
687 /// the parent's status if the Parent scope cannot be resolved, or
688 /// Unsupported if the size does not fit in 32 bits. Both are checked before
689 /// any member is streamed. A member whose type fails is dropped, whatever
690 /// the reason, and does not fail the composite.
691 EmitResult<PreparedScope>
692 emitDebugTypeComposite(const DICompositeType *CT, MCRegister VoidTypeReg,
693 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
694 SPIRV::ModuleAnalysisInfo &MAI);
695
696 /// Build \c DebugTypeEnum for the enumeration type \p ET. Operands: Name,
697 /// Underlying Type, Source, Line, Column, Parent, Size, Flags, then a Value
698 /// and Name pair per enumerator. Uses \c DebugInfoNone for Underlying Type
699 /// when \p ET has no base type, and drops an enumerator whose value does not
700 /// fit in a 32-bit integer.
701 ///
702 /// \returns An Emitted result when the operands are ready. An Unsupported
703 /// result, building nothing, if the size is 0 or does not fit in 32 bits.
704 /// If the base or Parent fail, it returns code for the one that failed.
705 EmitResult<PreparedScope> emitDebugTypeEnum(const DICompositeType *ET,
706 MCRegister VoidTypeReg,
707 MCRegister I32TypeReg,
708 MCRegister ExtInstSetReg,
709 SPIRV::ModuleAnalysisInfo &MAI);
710
711 /// Build \c DebugTypedef for the typedef derived type \p TD (a \c
712 /// DIDerivedType with \c DW_TAG_typedef). Operands: Name, Base Type, Source,
713 /// Line, Column, Parent. Parent is the enclosing type when \c TD->getScope()
714 /// is an emitted \c DIType, otherwise the first module \c
715 /// DebugCompilationUnit.
716 ///
717 /// \returns The base's or Parent's status if either fails.
718 EmitResult<PreparedScope> emitDebugTypedef(const DIDerivedType *TD,
719 MCRegister VoidTypeReg,
720 MCRegister I32TypeReg,
721 MCRegister ExtInstSetReg,
722 SPIRV::ModuleAnalysisInfo &MAI);
723
724 /// Map a subroutine type element to a \c DebugTypeFunction operand. A null
725 /// return type is void, so it maps to \p VoidTypeReg.
726 EmitResult<MCRegister> mapDISignatureTypeToReg(const DIType *Ty,
727 MCRegister VoidTypeReg,
728 bool ReturnType);
729
730 /// Map a DWARF source language code to a NonSemantic.Shader.DebugInfo.100
731 /// source language code.
732 static unsigned toNSDISrcLang(unsigned DwarfSrcLang);
733
734 /// Build a full path from debug \p Scope for OpString / DebugSource, matching
735 /// SPIRV-LLVM-Translator \c getFullPath (OCLUtil.h): \c DIScope::getFilename,
736 /// \c getDirectory, and \c sys::path::Style::native. Works for any \c DIScope
737 /// that carries file path fields (e.g. \c DIFile, \c DISubprogram,
738 /// \c DICompileUnit). Returns an empty path when \p Scope is null.
739 SmallString<128> getDebugFullPath(const DIScope *Scope) const;
740
741 /// Return an existing \c DebugSource id for file path \c OpString \p
742 /// FileStrReg or emit \c DebugSource and cache it (keyed by \p FileStrReg
743 /// id).
744 MCRegister getOrEmitDebugSourceForFileStrReg(MCRegister FileStrReg,
745 MCRegister VoidTypeReg,
746 MCRegister ExtInstSetReg,
747 SPIRV::ModuleAnalysisInfo &MAI);
748
749 /// Map \p Scope to the NonSemantic debug id used as a \c Parent operand.
750 ///
751 /// A \c DIType, \c DILexicalBlock, \c DINamespace, or \c DISubprogram scope
752 /// is created through \c getOrCreateDebugScope. When
753 /// \c -spirv-debug-lexical-block-discriminator-scope is enabled, a
754 /// \c DILexicalBlockFile is also created this way, becoming a
755 /// \c DebugLexicalBlockDiscriminator; otherwise it is unwrapped to its
756 /// enclosing scope first. When \p Scope is null, a \c DIFile, or another
757 /// scope without a dedicated debug instruction, it falls back to
758 /// \p FallbackCU or the first module \c DebugCompilationUnit recorded in
759 /// \c DebugScopeRegs; no such compile unit is Unsupported.
760 EmitResult<MCRegister>
761 resolveScope(const DIScope *Scope, const DICompileUnit *FallbackCU = nullptr);
762
763 /// Build \c DebugLexicalBlock for \p S, which must be a \c DILexicalBlock or
764 /// a \c DINamespace. A \c DILexicalBlock supplies Line/Column
765 /// from \c getLine()/getColumn(); a \c DINamespace has neither, so both are
766 /// 0, and its Name is appended as an extra \c OpString operand.
767 ///
768 /// \returns Emitted when the operands are ready. If \c resolveScope cannot
769 /// emit \c S->getScope(), builds nothing and returns that status.
770 EmitResult<PreparedScope>
771 emitDebugLexicalBlock(const DIScope *S, MCRegister VoidTypeReg,
772 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
773 SPIRV::ModuleAnalysisInfo &MAI);
774
775 /// Build \c DebugLexicalBlockDiscriminator for \p LBF.
776 /// Operands are Source, Discriminator, and Parent (\c LBF->getScope()).
777 EmitResult<PreparedScope> emitDebugLexicalBlockDiscriminator(
778 const DILexicalBlockFile *LBF, MCRegister VoidTypeReg,
779 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
780 SPIRV::ModuleAnalysisInfo &MAI);
781
782 /// Return a cached \c DebugInlinedAt id for \p IA, or emit one (recursing
783 /// into \c IA->getInlinedAt() first for the optional Inlined operand, so
784 /// outer frames are always emitted before the inner frame that references
785 /// them). Must run after \c DebugScopeRegs is populated, since the Scope
786 /// operand is resolved through \c resolveScope. \c DebugInlinedAt is not in
787 /// the spec's in-block instruction list, so this is only ever called from
788 /// module-scope emission (\c emitNonSemanticGlobalDebugInfo), never from
789 /// per-instruction emission.
790 ///
791 /// \returns An invalid (default-constructed) \c MCRegister, and emits
792 /// nothing, if \p IA's Scope does not resolve.
793 MCRegister getOrEmitDebugInlinedAt(const DILocation *IA,
794 MCRegister VoidTypeReg,
795 MCRegister I32TypeReg,
796 MCRegister ExtInstSetReg,
797 SPIRV::ModuleAnalysisInfo &MAI);
798};
799
800} // namespace llvm
801
802#endif // LLVM_LIB_TARGET_SPIRV_SPIRVNONSEMANTICDEBUGHANDLER_H
803