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/SmallString.h"
25#include "llvm/ADT/SmallVector.h"
26#include "llvm/ADT/StringMap.h"
27#include "llvm/CodeGen/DebugHandlerBase.h"
28#include "llvm/IR/DebugInfoMetadata.h"
29#include "llvm/MC/MCInst.h"
30#include "llvm/MC/MCRegister.h"
31#include <optional>
32
33namespace llvm {
34
35class SPIRVSubtarget;
36
37/// AsmPrinter handler that emits NonSemantic.Shader.DebugInfo.100 (NSDI)
38/// instructions for the SPIR-V backend. Registered with SPIRVAsmPrinter when
39/// the module contains debug info (llvm.dbg.cu).
40///
41/// Call sequence:
42/// beginModule() -- collect compile-unit metadata.
43/// prepareModuleOutput() -- add extension + ext inst set to MAI.
44/// emitNonSemanticDebugStrings() -- OpString for NSDI strings (sec. 7).
45/// emitNonSemanticGlobalDebugInfo() -- emit DebugSource,
46/// DebugCompilationUnit, DebugTypeBasic,
47/// DebugTypePointer, DebugTypeFunction,
48/// DebugFunctionDeclaration.
49/// beginFunctionImpl() -- no-op (no per-function DI yet).
50/// endFunctionImpl() -- no-op.
51class SPIRVNonSemanticDebugHandler : public DebugHandlerBase {
52 struct CompileUnitInfo {
53 const DICompileUnit *TheCU = nullptr;
54 SmallString<128> FilePath;
55 unsigned SpirvSourceLanguage = 0; // NonSemantic.Shader.DebugInfo.100 source
56 // language code (section 4.3)
57 };
58 SmallVector<CompileUnitInfo> CompileUnits;
59 int64_t DwarfVersion = 0;
60
61 // DI types partitioned from DebugInfoFinder.types() in beginModule()
62 // (basics, pointers, vectors, subroutine types NSDI v1 may emit).
63 SmallVector<const DIBasicType *> BasicTypes;
64 SmallVector<const DIDerivedType *> PointerTypes;
65 SmallVector<const DISubroutineType *> SubroutineTypes;
66 // DICompositeType nodes with DW_TAG_array_type and DINode::FlagVector,
67 // partitioned from DebugInfoFinder.types() in beginModule().
68 SmallVector<const DICompositeType *> VectorTypes;
69
70 // Filled in emitNonSemanticGlobalDebugInfo(): DI types to their result
71 // registers.
72 DenseMap<const DIType *, MCRegister> DebugTypeRegs;
73
74 // DISubprogram nodes that are declarations only (!isDefinition()), collected
75 // in beginModule() for DebugFunctionDeclaration emission.
76 SmallVector<const DISubprogram *> SubprogramDeclarations;
77
78 // DebugFunctionDeclaration result id per emitted declaration DISubprogram
79 // (only entries where emission succeeded).
80 DenseMap<const DISubprogram *, MCRegister> DebugFunctionDeclarationRegs;
81
82 // Path \c OpString result id per \c DIScope (CU, \c DIFile, declaration
83 // \c DISubprogram, …). Filled during \c emitNonSemanticDebugStrings() using
84 // \c getDebugFullPath + \c emitOpStringIfNew; section 10 uses it for
85 // \c DebugSource without recomputing path text.
86 DenseMap<const DIScope *, MCRegister> ScopeToPathOpStringReg;
87
88 // DebugCompilationUnit result id per DICompileUnit (for Parent operands).
89 DenseMap<const DICompileUnit *, MCRegister> CUToCompilationUnitDbgReg;
90
91 // DebugSource result id keyed by path \c OpString id (\c MCRegister::id()),
92 // deduplicating when the same file string is reused.
93 DenseMap<unsigned, MCRegister> DebugSourceRegByFileStr;
94
95 // Maps OpString contents to result id. Populated only by emitOpStringIfNew()
96 // during section 7; section 10 uses getCachedOpStringReg() (lookup only).
97 StringMap<MCRegister> OpStringContentCache;
98
99#ifndef NDEBUG // Only declare the variable for debugging purposes.
100 // True after emitNonSemanticDebugStrings() emitted the NSDI OpStrings for
101 // this module. SPIRVAsmPrinter calls that before
102 // emitNonSemanticGlobalDebugInfo().
103 bool NonSemanticOpStringsSectionEmitted = false;
104#endif
105
106 MCRegister CachedDebugInfoNoneReg;
107
108 MCRegister CachedOpTypeVoidReg;
109
110 MCRegister CachedOpTypeInt32Reg;
111
112 // Cache of already-emitted i32 constants, keyed by value. Prevents
113 // duplicate OpConstant instructions for the same integer value.
114 DenseMap<uint32_t, MCRegister> I32ConstantCache;
115
116 // Cache of already-emitted DebugTypeFunction instructions, keyed by operand
117 // ids (flags, return type, parameters).
118 DenseMap<SmallVector<MCRegister, 8>, MCRegister> DebugTypeFunctionCache;
119
120 // True once emitNonSemanticGlobalDebugInfo() has run. Both
121 // SPIRVAsmPrinter::emitFunctionHeader() and emitEndOfAsmFile() may call
122 // outputModuleSections(), each guarded by ModuleSectionsEmitted, so only
123 // one fires. This flag provides a secondary guard in case the call sites
124 // change.
125 bool GlobalDIEmitted = false;
126
127public:
128 explicit SPIRVNonSemanticDebugHandler(AsmPrinter &AP);
129
130 /// Collect compile-unit metadata from the module. Called by
131 /// AsmPrinter::doInitialization() via the handler list. No emission.
132 void beginModule(Module *M) override;
133
134 /// Emit OpString instructions for all NSDI file paths and basic type names
135 /// into the debug section (section 7 of the SPIR-V module layout). Must be
136 /// called from SPIRVAsmPrinter::outputDebugSourceAndStrings(), after
137 /// prepareModuleOutput() has registered the ext inst set. Registers are
138 /// stored in \c OpStringContentCache and \c ScopeToPathOpStringReg;
139 /// \c emitNonSemanticGlobalDebugInfo() resolves them via
140 /// \c getCachedOpStringReg() and path maps.
141 void emitNonSemanticDebugStrings(SPIRV::ModuleAnalysisInfo &MAI);
142
143 /// Add SPV_KHR_non_semantic_info extension and
144 /// NonSemantic.Shader.DebugInfo.100 ext inst set entry to MAI. Must be called
145 /// before outputGlobalRequirements() and outputOpExtInstImports() in
146 /// SPIRVAsmPrinter::outputModuleSections().
147 void prepareModuleOutput(const SPIRVSubtarget &ST,
148 SPIRV::ModuleAnalysisInfo &MAI);
149
150 /// Emit module-scope NSDI instructions (DebugSource, DebugCompilationUnit,
151 /// DebugTypeBasic, DebugTypePointer, DebugTypeFunction,
152 /// DebugFunctionDeclaration). Called by
153 /// SPIRVAsmPrinter::outputModuleSections() at section 10 in place of
154 /// outputModuleSection(MB_NonSemanticGlobalDI). Requires
155 /// emitNonSemanticDebugStrings() to have run first when NSDI strings apply.
156 void emitNonSemanticGlobalDebugInfo(SPIRV::ModuleAnalysisInfo &MAI);
157
158protected:
159 // All module-level output is driven by emitNonSemanticGlobalDebugInfo(),
160 // called explicitly from SPIRVAsmPrinter::outputModuleSections(). Nothing
161 // needs to happen in the AsmPrinterHandler::endModule() callback.
162 void endModule() override {}
163
164 // DebugHandlerBase stores MMI as a pointer copy from Asm->MMI at construction
165 // time (DebugHandlerBase.cpp: `MMI(Asm->MMI)`). The handler is constructed
166 // before AsmPrinter::doInitialization() runs, so Asm->MMI is null at that
167 // point and MMI remains null for this handler's entire lifetime. The
168 // base-class beginInstruction/endInstruction dereference MMI to create temp
169 // symbols for label tracking and would crash. Override them as no-ops.
170 // When per-function NSDI is implemented, use Asm->OutStreamer->getContext()
171 // for MCContext access rather than MMI->getContext().
172 void beginInstruction(const MachineInstr *MI) override {}
173 void endInstruction() override {}
174
175 // TODO: Emit DebugFunction and DebugFunctionDefinition here once per-function
176 // NSDI emission is implemented. DebugHandlerBase::beginFunction() populates
177 // LScopes and DbgValues, which are needed for DebugLine emission. Do not
178 // override beginFunction() until that work is in place.
179 void beginFunctionImpl(const MachineFunction *MF) override {}
180 // TODO: Add per-function cleanup when DebugFunction emission is in place.
181 void endFunctionImpl(const MachineFunction *MF) override {}
182
183private:
184 void emitMCInst(MCInst &Inst);
185 MCRegister emitOpString(StringRef S, SPIRV::ModuleAnalysisInfo &MAI);
186
187 /// Section 7 only: emit OpString and cache it if not already present. Must
188 /// not be called after NonSemanticOpStringsSectionEmitted is set. Returns
189 /// the path (or string) \c OpString result id.
190 MCRegister emitOpStringIfNew(StringRef S, SPIRV::ModuleAnalysisInfo &MAI);
191
192 /// Section 10 only: lookup OpString id from cache; asserts if missing or if
193 /// section 7 did not complete.
194 MCRegister getCachedOpStringReg(StringRef S);
195 MCRegister emitOpConstantI32(uint32_t Value, MCRegister I32TypeReg,
196 SPIRV::ModuleAnalysisInfo &MAI);
197 MCRegister emitExtInst(SPIRV::NonSemanticExtInst::NonSemanticExtInst Opcode,
198 MCRegister VoidTypeReg, MCRegister ExtInstSetReg,
199 ArrayRef<MCRegister> Operands,
200 SPIRV::ModuleAnalysisInfo &MAI);
201
202 /// Return a cached DebugTypeFunction id when \p Ops matches a prior emission,
203 /// otherwise emit and cache a new instruction.
204 MCRegister getOrEmitDebugTypeFunction(ArrayRef<MCRegister> Ops,
205 MCRegister VoidTypeReg,
206 MCRegister ExtInstSetReg,
207 SPIRV::ModuleAnalysisInfo &MAI);
208
209 /// Return OpTypeVoid id for this module (lazy lookup / emit, then cache).
210 MCRegister getOrEmitOpTypeVoidReg(SPIRV::ModuleAnalysisInfo &MAI);
211
212 /// Return OpTypeInt 32 0 id for this module (lazy lookup / emit, then cache).
213 MCRegister getOrEmitOpTypeInt32Reg(SPIRV::ModuleAnalysisInfo &MAI);
214
215 /// Find OpTypeVoid in the already-emitted TypeConstVars section, or emit one
216 /// if the module does not contain it (e.g. no void-returning functions).
217 MCRegister findOrEmitOpTypeVoid(SPIRV::ModuleAnalysisInfo &MAI);
218
219 /// Find OpTypeInt 32 0 in the already-emitted TypeConstVars section, or emit
220 /// one if the module does not contain it.
221 MCRegister findOrEmitOpTypeInt32(SPIRV::ModuleAnalysisInfo &MAI);
222
223 /// Emit \c DebugTypePointer for pointer metadata \p PT.
224 ///
225 /// \returns The result id register on success. Returns \c std::nullopt and
226 /// emits nothing if \p PT has no DWARF address space (needed to pick the
227 /// SPIR-V storage class), or if \p PT has a non-null base DI type that is not
228 /// yet in \c DebugTypeRegs (the pointee was not emitted as a debug type).
229 ///
230 /// Base Type operand: the register from \c DebugTypeRegs for \p PT's base
231 /// type when it is set and mapped; \c DebugInfoNone when there is no base
232 /// type (e.g. \c void * in IR), consistent with SPIRV-LLVM-Translator.
233 std::optional<MCRegister>
234 emitDebugTypePointer(const DIDerivedType *PT, MCRegister ExtInstSetReg,
235 SPIRV::ModuleAnalysisInfo &MAI);
236
237 /// Emit one DebugTypeFunction for ST when every DI operand maps to a debug
238 /// type id; otherwise emit nothing and return std::nullopt.
239 std::optional<MCRegister>
240 emitDebugTypeFunctionForSubroutineType(const DISubroutineType *ST,
241 MCRegister ExtInstSetReg,
242 SPIRV::ModuleAnalysisInfo &MAI);
243
244 /// Emit \c DebugFunctionDeclaration for a \c DISubprogram that is not a
245 /// definition (\p SP must satisfy \c !isDefinition()).
246 ///
247 /// \returns The result id register on success. Returns \c std::nullopt and
248 /// emits nothing if \p SP is null, is a definition, has no \c
249 /// DISubroutineType type, the signature type was not emitted in \c
250 /// DebugTypeRegs, no path
251 /// \c OpString was recorded for \p SP in section 7, or
252 /// \c resolveDebugFunctionDeclarationParent returns no id for the \c Parent
253 /// operand.
254 std::optional<MCRegister>
255 emitDebugFunctionDeclaration(const DISubprogram *SP, MCRegister VoidTypeReg,
256 MCRegister I32TypeReg, MCRegister ExtInstSetReg,
257 SPIRV::ModuleAnalysisInfo &MAI);
258
259 /// Emit \c DebugTypeVector for the vector composite type \p VT.
260 ///
261 /// \returns The result id register on success. Returns \c std::nullopt and
262 /// emits nothing if \p VT has no \c DIBasicType base type, if the base type
263 /// has not been emitted yet, if \p VT has more than one \c DISubrange
264 /// element, or if the component count is not a compile-time constant.
265 std::optional<MCRegister> emitDebugTypeVector(const DICompositeType *VT,
266 MCRegister ExtInstSetReg,
267 SPIRV::ModuleAnalysisInfo &MAI);
268
269 /// Map a \c DISubroutineType::getTypeArray() element to an operand register
270 /// for
271 /// \c DebugTypeFunction. Non-null \p Ty resolves via \c DebugTypeRegs; if the
272 /// type was never emitted, returns \c std::nullopt.
273 ///
274 /// LLVM encodes a void return as a null first element (and may use null in
275 /// later slots). NonSemantic \c DebugTypeFunction
276 /// requires a concrete return-type operand, so when \p ReturnType is true and
277 /// \p Ty is null, this returns \p VoidTypeReg (\c OpTypeVoid). When
278 /// \p ReturnType is false and \p Ty is null, this returns
279 /// \c CachedDebugInfoNoneReg (\c DebugInfoNone).
280 std::optional<MCRegister> mapDISignatureTypeToReg(const DIType *Ty,
281 MCRegister VoidTypeReg,
282 bool ReturnType);
283
284 /// Map a DWARF source language code to a NonSemantic.Shader.DebugInfo.100
285 /// source language code.
286 static unsigned toNSDISrcLang(unsigned DwarfSrcLang);
287
288 /// Build a full path from debug \p Scope for OpString / DebugSource, matching
289 /// SPIRV-LLVM-Translator \c getFullPath (OCLUtil.h): \c DIScope::getFilename,
290 /// \c getDirectory, and \c sys::path::Style::native. Works for any \c DIScope
291 /// that carries file path fields (e.g. \c DIFile, \c DISubprogram,
292 /// \c DICompileUnit). Returns an empty path when \p Scope is null.
293 SmallString<128> getDebugFullPath(const DIScope *Scope) const;
294
295 /// Return an existing \c DebugSource id for file path \c OpString \p
296 /// FileStrReg or emit \c DebugSource and cache it (keyed by \p FileStrReg
297 /// id).
298 MCRegister getOrEmitDebugSourceForFileStrReg(MCRegister FileStrReg,
299 MCRegister VoidTypeReg,
300 MCRegister ExtInstSetReg,
301 SPIRV::ModuleAnalysisInfo &MAI);
302
303 /// Resolve the \c Parent operand for \c DebugFunctionDeclaration: an emitted
304 /// debug type id when \c SP->getScope() is a \c DIType in \c DebugTypeRegs,
305 /// otherwise \c DebugCompilationUnit for \c SP->getUnit() (or the first
306 /// module CU when \c unit: is absent).
307 /// \returns \c std::nullopt when the scope requires a parent we cannot supply
308 /// (non-file scope that is not a mapped \c DIType) or the CU has no emitted
309 /// id.
310 std::optional<MCRegister>
311 resolveDebugFunctionDeclarationParent(const DISubprogram *SP) const;
312};
313
314} // namespace llvm
315
316#endif // LLVM_LIB_TARGET_SPIRV_SPIRVNONSEMANTICDEBUGHANDLER_H
317