[spirv] generate OpenCL.DebugInfo.100 instructions (#3155)

OpenCL.DebugInfo.100
is a SPIR-V extended instruction set that provides DWARF style debug information.
This PR allows DXC SPIR-V backend to generate the rich HLSL debug information
using OpenCL.DebugInfo.100 instructions.

Author: jaebaek

external/SPIRV-Tools

@@ -42,6 +42,7 @@ struct SpirvCodeGenOptions {
   bool debugInfoLine;
   bool debugInfoSource;
   bool debugInfoTool;
+  bool debugInfoRich;
   bool defaultRowMajor;
   bool disableValidation;
   bool enable16BitTypes;

include/dxc/Support/SPIRVOptions.h

@@ -817,6 +817,7 @@ int ReadDxcOpts(const OptTable *optionTable, unsigned flagsToInclude,
 
   opts.SpirvOptions.debugInfoFile = opts.SpirvOptions.debugInfoSource = false;
   opts.SpirvOptions.debugInfoLine = opts.SpirvOptions.debugInfoTool = false;
+  opts.SpirvOptions.debugInfoRich = false;
   if (Args.hasArg(OPT_fspv_debug_EQ)) {
     opts.DebugInfo = true;
     for (const Arg *A : Args.filtered(OPT_fspv_debug_EQ)) {
@@ -832,6 +833,16 @@ int ReadDxcOpts(const OptTable *optionTable, unsigned flagsToInclude,
         opts.SpirvOptions.debugInfoLine = true;
       } else if (v == "tool") {
         opts.SpirvOptions.debugInfoTool = true;
+      } else if (v == "rich") {
+        opts.SpirvOptions.debugInfoFile = true;
+        opts.SpirvOptions.debugInfoSource = false;
+        opts.SpirvOptions.debugInfoLine = true;
+        opts.SpirvOptions.debugInfoRich = true;
+      } else if (v == "rich-with-source") {
+        opts.SpirvOptions.debugInfoFile = true;
+        opts.SpirvOptions.debugInfoSource = true;
+        opts.SpirvOptions.debugInfoLine = true;
+        opts.SpirvOptions.debugInfoRich = true;
       } else {
         errors << "unknown SPIR-V debug info control parameter: " << v;
         return 1;

lib/DxcSupport/HLSLOptions.cpp

@@ -70,10 +70,29 @@ class SpirvBasicBlock {
   /// OpLoopMerge instruction. Returns nullptr otherwise.
   SpirvBasicBlock *getContinueTarget() const { return continueTarget; }
 
+  /// Get/set DebugScope for this basic block.
+  SpirvDebugScope *getDebugScope() const { return debugScope; }
+  void setDebugScope(SpirvDebugScope *scope) {
+    assert(debugScope == nullptr);
+    debugScope = scope;
+  }
+
+  /// Deletes existing debugScope and sets scope as the new debugScope.
+  void updateDebugScope(SpirvDebugScope *scope) {
+    if (debugScope != nullptr) {
+      debugScope->releaseMemory();
+      debugScope = nullptr;
+    }
+    setDebugScope(scope);
+  }
+
   /// Adds an instruction to the vector of instructions belonging to this basic
   /// block.
   void addInstruction(SpirvInstruction *inst) { instructions.push_back(inst); }
 
+  /// Return true if instructions is empty. Otherwise, return false.
+  bool empty() { return instructions.empty(); }
+
   /// Returns true if the last instruction in this basic block is a termination
   /// instruction.
   bool hasTerminator() const;
@@ -106,6 +125,13 @@ class SpirvBasicBlock {
   /// The continue merge targets if this basic block is a header block
   /// of structured control flow.
   SpirvBasicBlock *continueTarget;
+
+  /// DebugScope that groups all instructions in this basic block.
+  /// TODO: There can be multiple DebugScope instructions in a basic block.
+  ///       Currently, we do not find an actual case that DXC has to emit
+  ///       multiple DebugScope instructions in a basic block, but update it
+  ///       when we find the actual case.
+  SpirvDebugScope *debugScope;
 };
 
 } // end namespace spirv

tools/clang/include/clang/SPIRV/SpirvBasicBlock.h

@@ -103,6 +103,10 @@ class SpirvBuilder {
   /// for the basic block. On failure, returns zero.
   SpirvBasicBlock *createBasicBlock(llvm::StringRef name = "");
 
+  /// \brief Creates a SPIR-V DebugScope (OpenCL.DebugInfo.100 instruction).
+  /// On success, returns the <id> of DebugScope. On failure, returns nullptr.
+  SpirvDebugScope *createDebugScope(SpirvDebugInstruction *scope);
+
   /// \brief Adds the basic block with the given label as a successor to the
   /// current basic block.
   void addSuccessor(SpirvBasicBlock *successorBB);
@@ -126,6 +130,9 @@ class SpirvBuilder {
   /// \brief Sets insertion point to the given basic block.
   inline void setInsertPoint(SpirvBasicBlock *bb) { insertPoint = bb; }
 
+  /// \brief Gets insertion point.
+  inline SpirvBasicBlock *getInsertPoint() { return insertPoint; }
+
   // === Instruction at the current Insertion Point ===
 
   /// \brief Creates a composite construct instruction with the given
@@ -445,6 +452,44 @@ class SpirvBuilder {
   /// \brief Creates an OpDemoteToHelperInvocationEXT instruction.
   SpirvInstruction *createDemoteToHelperInvocationEXT(SourceLocation);
 
+  // === SPIR-V Rich Debug Info Creation ===
+  SpirvDebugSource *createDebugSource(llvm::StringRef file,
+                                      llvm::StringRef text = "");
+
+  SpirvDebugCompilationUnit *createDebugCompilationUnit(SpirvDebugSource *);
+
+  SpirvDebugLexicalBlock *
+  createDebugLexicalBlock(SpirvDebugSource *, uint32_t line, uint32_t column,
+                          SpirvDebugInstruction *parent);
+
+  SpirvDebugLocalVariable *createDebugLocalVariable(
+      QualType debugType, llvm::StringRef varName, SpirvDebugSource *src,
+      uint32_t line, uint32_t column, SpirvDebugInstruction *parentScope,
+      uint32_t flags, llvm::Optional<uint32_t> argNumber = llvm::None);
+
+  SpirvDebugGlobalVariable *createDebugGlobalVariable(
+      QualType debugType, llvm::StringRef varName, SpirvDebugSource *src,
+      uint32_t line, uint32_t column, SpirvDebugInstruction *parentScope,
+      llvm::StringRef linkageName, SpirvVariable *var, uint32_t flags,
+      llvm::Optional<SpirvInstruction *> staticMemberDebugType = llvm::None);
+
+  // Get a DebugInfoNone if exists. Otherwise, create one and return it.
+  SpirvDebugInfoNone *getOrCreateDebugInfoNone();
+
+  // Get a null DebugExpression if exists. Otherwise, create one and return it.
+  SpirvDebugExpression *getOrCreateNullDebugExpression();
+
+  SpirvDebugDeclare *createDebugDeclare(
+      SpirvDebugLocalVariable *dbgVar, SpirvInstruction *var,
+      llvm::Optional<SpirvDebugExpression *> dbgExpr = llvm::None);
+
+  SpirvDebugFunction *
+  createDebugFunction(const FunctionDecl *decl, llvm::StringRef name,
+                      SpirvDebugSource *src, uint32_t fnLine, uint32_t fnColumn,
+                      SpirvDebugInstruction *parentScope,
+                      llvm::StringRef linkageName, uint32_t flags,
+                      uint32_t scopeLine, SpirvFunction *fn);
+
   /// \brief Create SPIR-V instructions for KHR RayQuery ops
   SpirvInstruction *
   createRayQueryOpsKHR(spv::Op opcode, QualType resultType,
@@ -464,7 +509,7 @@ class SpirvBuilder {
   /// content. Returns the SpirvString instruction of the file name.
   inline SpirvString *setDebugSource(uint32_t major, uint32_t minor,
                                      const std::vector<llvm::StringRef> &name,
-                                     llvm::StringRef content);
+                                     llvm::StringRef content = "");
 
   /// \brief Adds an execution mode to the module under construction.
   inline void addExecutionMode(SpirvFunction *entryPoint, spv::ExecutionMode em,
@@ -474,6 +519,11 @@ class SpirvBuilder {
   /// construction.
   void addModuleProcessed(llvm::StringRef process);
 
+  /// \brief If not added already, adds an OpExtInstImport (import of extended
+  /// instruction set) of the OpenCL.DebugInfo.100 instruction set. Returns the
+  /// imported instruction set.
+  SpirvExtInstImport *getOpenCLDebugInfoExtInstSet();
+
   /// \brief Adds a stage input/ouput variable whose value is of the given type.
   ///
   /// Note: the corresponding pointer type of the given type will not be
@@ -627,6 +677,11 @@ class SpirvBuilder {
   /// Used as caches for all created builtin variables to avoid duplication.
   llvm::SmallVector<BuiltInVarInfo, 16> builtinVars;
 
+  SpirvDebugInfoNone *debugNone;
+
+  /// DebugExpression that does not reference any DebugOperation
+  SpirvDebugExpression *nullDebugExpr;
+
   // To avoid generating multiple OpStrings for the same string literal
   // the SpirvBuilder will generate and reuse them.
   llvm::DenseMap<std::string, SpirvString *, StringMapInfo> stringLiterals;
@@ -667,7 +722,7 @@ SpirvBuilder::setDebugSource(uint32_t major, uint32_t minor,
     SpirvSource *debugSource = new (context)
         SpirvSource(/*SourceLocation*/ {}, spv::SourceLanguage::HLSL, version,
                     fileString, content);
-    mod->addDebugSource(debugSource);
+    mod->addSource(debugSource);
     if (!mainSource)
       mainSource = debugSource;
   }
@@ -678,7 +733,7 @@ SpirvBuilder::setDebugSource(uint32_t major, uint32_t minor,
     mainSource = new (context)
         SpirvSource(/*SourceLocation*/ {}, spv::SourceLanguage::HLSL, version,
                     nullptr, content);
-    mod->addDebugSource(mainSource);
+    mod->addSource(mainSource);
   }
   return mainSource->getFile();
 }

tools/clang/include/clang/SPIRV/SpirvBuilder.h

@@ -12,16 +12,38 @@
 #include <array>
 
 #include "dxc/DXIL/DxilShaderModel.h"
+#include "clang/AST/DeclTemplate.h"
 #include "clang/Frontend/FrontendAction.h"
 #include "clang/SPIRV/SpirvInstruction.h"
 #include "clang/SPIRV/SpirvType.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/DenseMapInfo.h"
+#include "llvm/ADT/MapVector.h"
+#include "llvm/ADT/StringMap.h"
 #include "llvm/Support/Allocator.h"
 
 namespace clang {
 namespace spirv {
 
+class SpirvModule;
+
+struct RichDebugInfo {
+  RichDebugInfo(SpirvDebugSource *src, SpirvDebugCompilationUnit *cu)
+      : source(src), compilationUnit(cu) {
+    scopeStack.push_back(cu);
+  }
+  RichDebugInfo() : source(nullptr), compilationUnit(nullptr), scopeStack() {}
+
+  // The HLL source code
+  SpirvDebugSource *source;
+
+  // The compilation unit (topmost debug info node)
+  SpirvDebugCompilationUnit *compilationUnit;
+
+  // Stack of lexical scopes
+  std::vector<SpirvDebugInstruction *> scopeStack;
+};
+
 // Provides DenseMapInfo for spv::StorageClass so that we can use
 // spv::StorageClass as key to DenseMap.
 //
@@ -139,10 +161,66 @@ class SpirvContext {
   /// Deallocates the memory pointed by the given pointer.
   void deallocate(void *ptr) const {}
 
+  // === DebugTypes ===
+
+  // TODO: Replace uint32_t with an enum for encoding.
+  SpirvDebugType *getDebugTypeBasic(const SpirvType *spirvType,
+                                    llvm::StringRef name, SpirvConstant *size,
+                                    uint32_t encoding);
+
+  SpirvDebugType *getDebugTypeMember(llvm::StringRef name, SpirvDebugType *type,
+                                     SpirvDebugSource *source, uint32_t line,
+                                     uint32_t column,
+                                     SpirvDebugInstruction *parent,
+                                     uint32_t flags, uint32_t offsetInBits,
+                                     uint32_t sizeInBits, const APValue *value);
+
+  SpirvDebugTypeComposite *getDebugTypeComposite(const SpirvType *spirvType,
+                                                 llvm::StringRef name,
+                                                 SpirvDebugSource *source,
+                                                 uint32_t line, uint32_t column,
+                                                 SpirvDebugInstruction *parent,
+                                                 llvm::StringRef linkageName,
+                                                 uint32_t flags, uint32_t tag);
+
+  SpirvDebugType *getDebugType(const SpirvType *spirvType);
+
+  SpirvDebugType *getDebugTypeArray(const SpirvType *spirvType,
+                                    SpirvDebugInstruction *elemType,
+                                    llvm::ArrayRef<uint32_t> elemCount);
+
+  SpirvDebugType *getDebugTypeVector(const SpirvType *spirvType,
+                                     SpirvDebugInstruction *elemType,
+                                     uint32_t elemCount);
+
+  SpirvDebugType *getDebugTypeFunction(const SpirvType *spirvType,
+                                       uint32_t flags, SpirvDebugType *ret,
+                                       llvm::ArrayRef<SpirvDebugType *> params);
+
+  SpirvDebugTypeTemplate *createDebugTypeTemplate(
+      const ClassTemplateSpecializationDecl *templateType,
+      SpirvDebugInstruction *target,
+      const llvm::SmallVector<SpirvDebugTypeTemplateParameter *, 2> &params);
+
+  SpirvDebugTypeTemplate *
+  getDebugTypeTemplate(const ClassTemplateSpecializationDecl *templateType);
+
+  SpirvDebugTypeTemplateParameter *createDebugTypeTemplateParameter(
+      const TemplateArgument *templateArg, llvm::StringRef name,
+      SpirvDebugType *type, SpirvInstruction *value, SpirvDebugSource *source,
+      uint32_t line, uint32_t column);
+
+  SpirvDebugTypeTemplateParameter *
+  getDebugTypeTemplateParameter(const TemplateArgument *templateArg);
+
+  // Moves all debug type instructions to module and makes the data structures
+  // that contain the debug type instructions empty. After calling this method,
+  // module will have the ownership of debug type instructions.
+  void moveDebugTypesToModule(SpirvModule *module);
+
   // === Types ===
 
   const VoidType *getVoidType() const { return voidType; }
-
   const BoolType *getBoolType() const { return boolType; }
   const IntegerType *getSIntType(uint32_t bitwidth);
   const IntegerType *getUIntType(uint32_t bitwidth);
@@ -237,6 +315,47 @@ class SpirvContext {
     return curShaderModelKind == ShaderModelKind::Amplification;
   }
 
+  /// Function to get all RichDebugInfo (i.e., the current status of
+  /// compilation units).
+  llvm::StringMap<RichDebugInfo> &getDebugInfo() { return debugInfo; }
+
+  /// Function to let the lexical scope stack grow when it enters a
+  /// new lexical scope.
+  void pushDebugLexicalScope(RichDebugInfo *info, SpirvDebugInstruction *scope);
+
+  /// Function to pop the last element from the lexical scope stack.
+  void popDebugLexicalScope(RichDebugInfo *info) {
+    info->scopeStack.pop_back();
+    currentLexicalScope = info->scopeStack.back();
+  }
+
+  /// Function to get the last lexical scope that the SpirvEmitter
+  /// class instance entered.
+  SpirvDebugInstruction *getCurrentLexicalScope() {
+    return currentLexicalScope;
+  }
+
+  /// Function to add/get the mapping from a SPIR-V type to its Decl for
+  /// a struct type.
+  void registerStructDeclForSpirvType(const SpirvType *spvTy,
+                                      const DeclContext *decl) {
+    assert(spvTy != nullptr && decl != nullptr);
+    spvStructTypeToDecl[spvTy] = decl;
+  }
+  const DeclContext *getStructDeclForSpirvType(const SpirvType *spvTy) {
+    return spvStructTypeToDecl[spvTy];
+  }
+
+  /// Function to add/get the mapping from a FunctionDecl to its DebugFunction.
+  void registerDebugFunctionForDecl(const FunctionDecl *decl,
+                                    SpirvDebugFunction *fn) {
+    assert(decl != nullptr && fn != nullptr);
+    declToDebugFunction[decl] = fn;
+  }
+  SpirvDebugFunction *getDebugFunctionForDecl(const FunctionDecl *decl) {
+    return declToDebugFunction[decl];
+  }
+
 private:
   /// \brief The allocator used to create SPIR-V entity objects.
   ///
@@ -294,6 +413,35 @@ class SpirvContext {
   // Major/Minor hlsl profile version.
   uint32_t majorVersion;
   uint32_t minorVersion;
+
+  /// File name to rich debug info map. When the main source file
+  /// includes header files, we create an element of debugInfo for
+  /// each file. RichDebugInfo includes DebugSource,
+  /// DebugCompilationUnit and scopeStack which keeps lexical scopes
+  /// recursively.
+  llvm::StringMap<RichDebugInfo> debugInfo;
+  SpirvDebugInstruction *currentLexicalScope;
+
+  // Mapping from SPIR-V type to debug type instruction.
+  // The purpose is not to generate several DebugType* instructions for the same
+  // type if the type is used for several variables.
+  llvm::MapVector<const SpirvType *, SpirvDebugType *> debugTypes;
+
+  // Mapping from template decl to DebugTypeTemplate.
+  llvm::MapVector<const ClassTemplateSpecializationDecl *,
+                  SpirvDebugTypeTemplate *>
+      typeTemplates;
+
+  // Mapping from template parameter decl to DebugTypeTemplateParameter.
+  llvm::MapVector<const TemplateArgument *, SpirvDebugTypeTemplateParameter *>
+      typeTemplateParams;
+
+  // Mapping from SPIR-V type to Decl for a struct type.
+  llvm::DenseMap<const SpirvType *, const DeclContext *> spvStructTypeToDecl;
+
+  // Mapping from FunctionDecl to SPIR-V debug function.
+  llvm::DenseMap<const FunctionDecl *, SpirvDebugFunction *>
+      declToDebugFunction;
 };
 
 } // end namespace spirv