Add debug info support for Swift/Clang APINotes.

[aprantl]

Summary

Disclaimer: This is a little awkward, since this adds DWARF support for a feature that is currently only present in swift-clang but has been proposed for upstreaming (http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html) multiple times (http://lists.llvm.org/pipermail/cfe-dev/2017-May/053860.html) and will — I believe — eventually find tis way into upstream clang.

In order for dsymutil to collect .apinotes files (which capture attributes such as nullability, Swift import names, and availability), I want to propose adding an apinotes: field to DIModule that gets translated into a DW_AT_LLVM_apinotes (path) nested inside DW_TAG_module. This will be primarily used by LLDB to indirectly extract the Swift names of Clang declarations that were deserialized from DWARF.

[aprantl]

llvm/include/llvm/BinaryFormat/Dwarf.def

412

I'm fine with calling this DW_AT_LLVM_apinotes, too.

[dblaikie]

Disclaimer: This is a little awkward, since this adds DWARF support for a feature that is currently only present in swift-clang but has been proposed for upstreaming (http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html) multiple times (http://lists.llvm.org/pipermail/cfe-dev/2017-May/053860.html) and will — I believe — eventually find tis way into upstream clang.

Those threads are fairly old (2015 and 2017 respectively). If this is a relevant goal/justiifcation, perhaps it should be moved forward a bit more along with this proposal. Though I'm not 100% sure it's necessary for this feature to be used in clang for it to be added to LLVM - Julia and other non-clang/non-llvm-project frontends have, to my knowledge, had features added to upstream LLVM for their use cases that were never generated by any frontend in llvm-project. (stackmap/patchpoint comes to mind?)

Just to clarify the purpose of the feature in this thread/review: apinotes allow externally imposing attributes on functions/entities you don't own, right? (sort of the same reason as ADL in C++ - I want to say something about "swap" but I don't own the canonical swap, so I need some mechanism to do that)

In order for dsymutil to collect .apinotes files (which capture attributes such as nullability, Swift import names, and availability), I want to propose adding an apinotes: field to DIModule that gets translated into a DW_AT_LLVM_apinotes (path) nested inside DW_TAG_module. This will be primarily used by LLDB to indirectly extract the Swift names of Clang declarations that were deserialized from DWARF.

& this applies not just to dsymutil, right? Presumably it's used by debuggers when debugging using unlinked debug info, or using non-.o+dsymutil style debug info, such as when using Swift on Linux/ELF?

Is it worth discussing whether these apinotes should be embedded directly into the debug info, rather than referenced by file name? I guess they're /sort/ of like source files (they likely have the same distribution model - so if the source is accessible, so are the apinotes), so referencing by file name makes sense?

[aprantl]

In D75585#1905759, @dblaikie wrote:

Disclaimer: This is a little awkward, since this adds DWARF support for a feature that is currently only present in swift-clang but has been proposed for upstreaming (http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html) multiple times (http://lists.llvm.org/pipermail/cfe-dev/2017-May/053860.html) and will — I believe — eventually find tis way into upstream clang.

Those threads are fairly old (2015 and 2017 respectively). If this is a relevant goal/justiifcation, perhaps it should be moved forward a bit more along with this proposal. Though I'm not 100% sure it's necessary for this feature to be used in clang for it to be added to LLVM - Julia and other non-clang/non-llvm-project frontends have, to my knowledge, had features added to upstream LLVM for their use cases that were never generated by any frontend in llvm-project. (stackmap/patchpoint comes to mind?)

Correct, we have language support in LLVM for languages not in the LLVM project. But since this is a Clang feature and it has been discussed previously, I thought I should link this for context.

Just to clarify the purpose of the feature in this thread/review: apinotes allow externally imposing attributes on functions/entities you don't own, right? (sort of the same reason as ADL in C++ - I want to say something about "swap" but I don't own the canonical swap, so I need some mechanism to do that)

Yes, apinotes are a YAML file that allows adding extra attributes to declarations in system header files without modifying those header files themselves.

In order for dsymutil to collect .apinotes files (which capture attributes such as nullability, Swift import names, and availability), I want to propose adding an apinotes: field to DIModule that gets translated into a DW_AT_LLVM_apinotes (path) nested inside DW_TAG_module. This will be primarily used by LLDB to indirectly extract the Swift names of Clang declarations that were deserialized from DWARF.

& this applies not just to dsymutil, right? Presumably it's used by debuggers when debugging using unlinked debug info, or using non-.o+dsymutil style debug info, such as when using Swift on Linux/ELF?

Absolutely. The end goal is for LLDB to import the APINotes, so it can access the attributes. What I'm particularly interested in right now is the Swift name attribute, which defines the name under which an (Objective-)C declaration should be imported into Swift, so LLDB can import Clang types from DWARF into Swift under the correct name.

Is it worth discussing whether these apinotes should be embedded directly into the debug info, rather than referenced by file name? I guess they're /sort/ of like source files (they likely have the same distribution model - so if the source is accessible, so are the apinotes), so referencing by file name makes sense?

The alternative I considered was to invent explicit DWARF for all of the attribute kinds and put them on the decl in CGDebugInfo and deserialize them in LLDB and put them as attributes on the Decl. However, compared to just passing the apinotes file verbatim to Swift's ClangImporter this would be a lot more churn in upstream LLVM, as we'd need to add several new attributes to almost every type and decl kind.

[dblaikie]

In order for dsymutil to collect .apinotes files (which capture attributes such as nullability, Swift import names, and availability), I want to propose adding an apinotes: field to DIModule that gets translated into a DW_AT_LLVM_apinotes (path) nested inside DW_TAG_module. This will be primarily used by LLDB to indirectly extract the Swift names of Clang declarations that were deserialized from DWARF.

& this applies not just to dsymutil, right? Presumably it's used by debuggers when debugging using unlinked debug info, or using non-.o+dsymutil style debug info, such as when using Swift on Linux/ELF?

Absolutely. The end goal is for LLDB to import the APINotes, so it can access the attributes. What I'm particularly interested in right now is the Swift name attribute, which defines the name under which an (Objective-)C declaration should be imported into Swift, so LLDB can import Clang types from DWARF into Swift under the correct name.

Is it worth discussing whether these apinotes should be embedded directly into the debug info, rather than referenced by file name? I guess they're /sort/ of like source files (they likely have the same distribution model - so if the source is accessible, so are the apinotes), so referencing by file name makes sense?

The alternative I considered was to invent explicit DWARF for all of the attribute kinds and put them on the decl in CGDebugInfo and deserialize them in LLDB and put them as attributes on the Decl. However, compared to just passing the apinotes file verbatim to Swift's ClangImporter this would be a lot more churn in upstream LLVM, as we'd need to add several new attributes to almost every type and decl kind.

oh, yeah, I wasn't thinking that level of fidelity - just the whole file embedded as a string or something. But yeah, doesn't seem like that'd be especially better. If APINotes is like a source/header file type thing (some could be user authored, others could be generated from something else, same way header/source might be generated) then it seems fine to reference it on disk.

I guess the only thing that makes me vascillate a bit is that debuggers don't usually process the source in any way - they just render it to the user. APINotes are meant to be semantically consumed by the debugger - that's where the analogy breaks down a bit for me, but not necessarily in a way that invalidates this approach. APINotes seem to be much more readily machine readable (JSon, etc) than, say, C++ source (reason debuggers don't just reparse the source to get type information, etc).

[aprantl]

In D75585#1906100, @dblaikie wrote:

In order for dsymutil to collect .apinotes files (which capture attributes such as nullability, Swift import names, and availability), I want to propose adding an apinotes: field to DIModule that gets translated into a DW_AT_LLVM_apinotes (path) nested inside DW_TAG_module. This will be primarily used by LLDB to indirectly extract the Swift names of Clang declarations that were deserialized from DWARF.

& this applies not just to dsymutil, right? Presumably it's used by debuggers when debugging using unlinked debug info, or using non-.o+dsymutil style debug info, such as when using Swift on Linux/ELF?

Absolutely. The end goal is for LLDB to import the APINotes, so it can access the attributes. What I'm particularly interested in right now is the Swift name attribute, which defines the name under which an (Objective-)C declaration should be imported into Swift, so LLDB can import Clang types from DWARF into Swift under the correct name.

Is it worth discussing whether these apinotes should be embedded directly into the debug info, rather than referenced by file name? I guess they're /sort/ of like source files (they likely have the same distribution model - so if the source is accessible, so are the apinotes), so referencing by file name makes sense?

The alternative I considered was to invent explicit DWARF for all of the attribute kinds and put them on the decl in CGDebugInfo and deserialize them in LLDB and put them as attributes on the Decl. However, compared to just passing the apinotes file verbatim to Swift's ClangImporter this would be a lot more churn in upstream LLVM, as we'd need to add several new attributes to almost every type and decl kind.

oh, yeah, I wasn't thinking that level of fidelity - just the whole file embedded as a string or something. But yeah, doesn't seem like that'd be especially better.

No, I don't think that would be bette, either.

If APINotes is like a source/header file type thing (some could be user authored, others could be generated from something else, same way header/source might be generated) then it seems fine to reference it on disk.

I guess the only thing that makes me vascillate a bit is that debuggers don't usually process the source in any way - they just render it to the user. APINotes are meant to be semantically consumed by the debugger - that's where the analogy breaks down a bit for me, but not necessarily in a way that invalidates this approach.

What blurs the line here is that LLDB is not a traditional debugger in this sense. It can load clang modules and thus also processes source (or at least header files).

APINotes seem to be much more readily machine readable (JSon, etc) than, say, C++ source (reason debuggers don't just reparse the source to get type information, etc).

Yes, though LLDB *can* parse type information from Clang modules to get at templates in the STL, etc. But it is a secondary source used for the expression evaluator, and not needed to just inspect the state of the program by looking at variables in the traditional debugger sense.

[dblaikie]

Quoting myself from another review:

Mechanically seems fine (though probably/I think these sort of things should be committed in three parts - IR support, frontend usage, backend usage - but nice to review in one piece like this). I'll defer actual detailed review/sign-off to at least someone else with a vested interest in this features usage just to make sure it's got some (more) in-review... review :)

[davide]

This is all fairly mechanical plumbing

llvm/include/llvm/BinaryFormat/Dwarf.def

412

I'd rather call them LLVM_apinotes, but I don't have a strong opinion about it.

[aprantl]

llvm/include/llvm/BinaryFormat/Dwarf.def

412

I carefully chose the number out of the LLVM space already, so the constant could be renamed once it's upstream. But I'm fine with naming it LLVM from the start.

llvm/include/llvm-c/DebugInfo.h

  * \param ParentScope     The parent scope containing this module declaration.
  * \param Name            Module name.
  * \param NameLen         The length of the C string passed to \c Name.
  * \param ConfigMacros    A space-separated shell-quoted list of -D macro
                           definitions as they would appear on a command line.
  * \param ConfigMacrosLen The length of the C string passed to \c ConfigMacros.
  * \param IncludePath     The path to the module map file.
  * \param IncludePathLen  The length of the C string passed to \c IncludePath.
+ * \param APINotesFile    The path to an API notes file for the module.
+ * \param APINotesFileLen The length of the C string passed to \c APINotestFile.
  */
 LLVMMetadataRef
 LLVMDIBuilderCreateModule(LLVMDIBuilderRef Builder, LLVMMetadataRef ParentScope,
                           const char *Name, size_t NameLen,
                           const char *ConfigMacros, size_t ConfigMacrosLen,
-                          const char *IncludePath, size_t IncludePathLen);
+                          const char *IncludePath, size_t IncludePathLen,
+                          const char *APINotestFile, size_t APINotestFileLen);
 
 /**
  * Creates a new descriptor for a namespace with the specified parent scope.
  * \param Builder          The \c DIBuilder.
  * \param ParentScope      The parent scope containing this module declaration.
  * \param Name             NameSpace name.
  * \param NameLen          The length of the C string passed to \c Name.
  * \param ExportSymbols    Whether or not the namespace exports symbols, e.g.

llvm/include/llvm/BinaryFormat/Dwarf.def

 HANDLE_DW_AT(0x3b29, BORLAND_Delphi_return, 0, BORLAND)
 HANDLE_DW_AT(0x3b30, BORLAND_Delphi_frameptr, 0, BORLAND)
 HANDLE_DW_AT(0x3b31, BORLAND_closure, 0, BORLAND)
 // LLVM project extensions.
 HANDLE_DW_AT(0x3e00, LLVM_include_path, 0, LLVM)
 HANDLE_DW_AT(0x3e01, LLVM_config_macros, 0, LLVM)
 HANDLE_DW_AT(0x3e02, LLVM_sysroot, 0, LLVM)
 HANDLE_DW_AT(0x3e03, LLVM_tag_offset, 0, LLVM)
+
 // Apple extensions.
+HANDLE_DW_AT(0x3e07, APPLE_apinotes, 0, APPLE)
 HANDLE_DW_AT(0x3fe1, APPLE_optimized, 0, APPLE)
 HANDLE_DW_AT(0x3fe2, APPLE_flags, 0, APPLE)
 HANDLE_DW_AT(0x3fe3, APPLE_isa, 0, APPLE)
 HANDLE_DW_AT(0x3fe4, APPLE_block, 0, APPLE)
 HANDLE_DW_AT(0x3fe5, APPLE_major_runtime_vers, 0, APPLE)
 HANDLE_DW_AT(0x3fe6, APPLE_runtime_class, 0, APPLE)
 HANDLE_DW_AT(0x3fe7, APPLE_omit_frame_ptr, 0, APPLE)
 HANDLE_DW_AT(0x3fe8, APPLE_property_name, 0, APPLE)

llvm/include/llvm/IR/DIBuilder.h

public:
     /// This creates new descriptor for a module with the specified
     /// parent scope.
     /// \param Scope       Parent scope
     /// \param Name        Name of this module
     /// \param ConfigurationMacros
     ///                    A space-separated shell-quoted list of -D macro
     ///                    definitions as they would appear on a command line.
     /// \param IncludePath The path to the module map file.
+    /// \param APINotesFile The path to an API notes file for this module.
     DIModule *createModule(DIScope *Scope, StringRef Name,
                            StringRef ConfigurationMacros,
-                           StringRef IncludePath);
+                           StringRef IncludePath, StringRef APINotesFile);
 
     /// This creates a descriptor for a lexical block with a new file
     /// attached. This merely extends the existing
     /// lexical block as it crosses a file.
     /// \param Scope       Lexical block.
     /// \param File        Source file.
     /// \param Discriminator DWARF path discriminator value.
     DILexicalBlockFile *createLexicalBlockFile(DIScope *Scope, DIFile *File,

llvm/include/llvm/IR/DebugInfoMetadata.h

class DIModule : public DIScope {
   friend class MDNode;
 
   DIModule(LLVMContext &Context, StorageType Storage, ArrayRef<Metadata *> Ops)
       : DIScope(Context, DIModuleKind, Storage, dwarf::DW_TAG_module, Ops) {}
   ~DIModule() = default;
 
   static DIModule *getImpl(LLVMContext &Context, DIScope *Scope, StringRef Name,
                            StringRef ConfigurationMacros, StringRef IncludePath,
-                           StorageType Storage, bool ShouldCreate = true) {
+                           StringRef APINotesFile, StorageType Storage,
+                           bool ShouldCreate = true) {
     return getImpl(Context, Scope, getCanonicalMDString(Context, Name),
                    getCanonicalMDString(Context, ConfigurationMacros),
                    getCanonicalMDString(Context, IncludePath),
+                   getCanonicalMDString(Context, APINotesFile),
                    Storage, ShouldCreate);
   }
   static DIModule *getImpl(LLVMContext &Context, Metadata *Scope,
                            MDString *Name, MDString *ConfigurationMacros,
-                           MDString *IncludePath, StorageType Storage,
-                           bool ShouldCreate = true);
+                           MDString *IncludePath, MDString *APINotesFile,
+                           StorageType Storage, bool ShouldCreate = true);
 
   TempDIModule cloneImpl() const {
     return getTemporary(getContext(), getScope(), getName(),
-                        getConfigurationMacros(), getIncludePath());
+                        getConfigurationMacros(), getIncludePath(),
+                        getAPINotesFile());
   }
 
 public:
   DEFINE_MDNODE_GET(DIModule,
                     (DIScope * Scope, StringRef Name,
-                     StringRef ConfigurationMacros, StringRef IncludePath),
-                    (Scope, Name, ConfigurationMacros, IncludePath))
+                     StringRef ConfigurationMacros, StringRef IncludePath,
+                     StringRef APINotesFile),
+                    (Scope, Name, ConfigurationMacros, IncludePath,
+                     APINotesFile))
   DEFINE_MDNODE_GET(DIModule,
-                    (Metadata *Scope, MDString *Name, MDString *ConfigurationMacros,
-                     MDString *IncludePath),
-                    (Scope, Name, ConfigurationMacros, IncludePath))
+                    (Metadata * Scope, MDString *Name,
+                     MDString *ConfigurationMacros, MDString *IncludePath,
+                     MDString *APINotesFile),
+                    (Scope, Name, ConfigurationMacros, IncludePath,
+                     APINotesFile))
 
   TempDIModule clone() const { return cloneImpl(); }
 
   DIScope *getScope() const { return cast_or_null<DIScope>(getRawScope()); }
   StringRef getName() const { return getStringOperand(1); }
   StringRef getConfigurationMacros() const { return getStringOperand(2); }
   StringRef getIncludePath() const { return getStringOperand(3); }
+  StringRef getAPINotesFile() const { return getStringOperand(4); }
 
   Metadata *getRawScope() const { return getOperand(0); }
   MDString *getRawName() const { return getOperandAs<MDString>(1); }
   MDString *getRawConfigurationMacros() const { return getOperandAs<MDString>(2); }
   MDString *getRawIncludePath() const { return getOperandAs<MDString>(3); }
+  MDString *getRawAPINotesFile() const { return getOperandAs<MDString>(4); }
 
   static bool classof(const Metadata *MD) {
     return MD->getMetadataID() == DIModuleKind;
   }
 };
 
 /// Base class for template parameters.
 class DITemplateParameter : public DINode {

llvm/lib/AsmParser/LLParser.cpp

#undef VISIT_MD_FIELDS
 
   Result = GET_OR_DISTINCT(DIMacroFile,
                            (Context, type.Val, line.Val, file.Val, nodes.Val));
   return false;
 }
 
 /// ParseDIModule:
 ///   ::= !DIModule(scope: !0, name: "SomeModule", configMacros: "-DNDEBUG",
-///                 includePath: "/usr/include")
+///                 includePath: "/usr/include", apinotes: "module.apinotes")
 bool LLParser::ParseDIModule(MDNode *&Result, bool IsDistinct) {
 #define VISIT_MD_FIELDS(OPTIONAL, REQUIRED)                                    \
   REQUIRED(scope, MDField, );                                                  \
   REQUIRED(name, MDStringField, );                                             \
   OPTIONAL(configMacros, MDStringField, );                                     \
-  OPTIONAL(includePath, MDStringField, );
+  OPTIONAL(includePath, MDStringField, );                                      \
+  OPTIONAL(apinotes, MDStringField, );
   PARSE_MD_FIELDS();
 #undef VISIT_MD_FIELDS
 
-  Result = GET_OR_DISTINCT(DIModule, (Context, scope.Val, name.Val,
-                           configMacros.Val, includePath.Val));
+  Result =
+      GET_OR_DISTINCT(DIModule, (Context, scope.Val, name.Val, configMacros.Val,
+                                 includePath.Val, apinotes.Val));
   return false;
 }
 
 /// ParseDITemplateTypeParameter:
 ///   ::= !DITemplateTypeParameter(name: "Ty", type: !1, defaulted: false)
 bool LLParser::ParseDITemplateTypeParameter(MDNode *&Result, bool IsDistinct) {
 #define VISIT_MD_FIELDS(OPTIONAL, REQUIRED)                                    \
   OPTIONAL(name, MDStringField, );                                             \

llvm/lib/Bitcode/Reader/MetadataLoader.cpp

case bitc::METADATA_SUBROUTINE_TYPE: {
     MetadataList.assignValue(
         GET_OR_DISTINCT(DISubroutineType, (Context, Flags, CC, Types)),
         NextMetadataNo);
     NextMetadataNo++;
     break;
   }
 
   case bitc::METADATA_MODULE: {
-    if (Record.size() < 5 || Record.size() > 6)
+    if (Record.size() < 5 || Record.size() > 7)
       return error("Invalid record");
 
     IsDistinct = Record[0];
     MetadataList.assignValue(
-        GET_OR_DISTINCT(
-            DIModule, (Context, getMDOrNull(Record[1]), getMDString(Record[2]),
-                       getMDString(Record[3]), getMDString(Record[4]))),
+        GET_OR_DISTINCT(DIModule,
+                        (Context, getMDOrNull(Record[1]),
+                         getMDString(Record[2]), getMDString(Record[3]),
+                         getMDString(Record[4]), getMDString(Record[5]))),
         NextMetadataNo);
     NextMetadataNo++;
     break;
   }
 
   case bitc::METADATA_FILE: {
     if (Record.size() != 3 && Record.size() != 5 && Record.size() != 6)
       return error("Invalid record");

llvm/lib/CodeGen/AsmPrinter/DwarfUnit.cpp

if (!M->getName().empty()) {
     addString(MDie, dwarf::DW_AT_name, M->getName());
     addGlobalName(M->getName(), MDie, M->getScope());
   }
   if (!M->getConfigurationMacros().empty())
     addString(MDie, dwarf::DW_AT_LLVM_config_macros,
               M->getConfigurationMacros());
   if (!M->getIncludePath().empty())
     addString(MDie, dwarf::DW_AT_LLVM_include_path, M->getIncludePath());
+  if (!M->getAPINotesFile().empty())
+    addString(MDie, dwarf::DW_AT_APPLE_apinotes, M->getAPINotesFile());
 
   return &MDie;
 }
 
 DIE *DwarfUnit::getOrCreateSubprogramDIE(const DISubprogram *SP, bool Minimal) {
   // Construct the context before querying for the existence of the DIE in case
   // such construction creates the DIE (as is the case for member function
   // declarations).

llvm/lib/IR/AsmWriter.cpp

static void writeDIModule(raw_ostream &Out, const DIModule *N,
                           TypePrinting *TypePrinter, SlotTracker *Machine,
                           const Module *Context) {
   Out << "!DIModule(";
   MDFieldPrinter Printer(Out, TypePrinter, Machine, Context);
   Printer.printMetadata("scope", N->getRawScope(), /* ShouldSkipNull */ false);
   Printer.printString("name", N->getName());
   Printer.printString("configMacros", N->getConfigurationMacros());
   Printer.printString("includePath", N->getIncludePath());
+  Printer.printString("apinotes", N->getAPINotesFile());
   Out << ")";
 }
 
 
 static void writeDITemplateTypeParameter(raw_ostream &Out,
                                          const DITemplateTypeParameter *N,
                                          TypePrinting *TypePrinter,
                                          SlotTracker *Machine,

llvm/lib/IR/DIBuilder.cpp

DINamespace *DIBuilder::createNameSpace(DIScope *Scope, StringRef Name,
   // DICompileUnit. This decision is an explicit tradeoff of link time versus
   // memory usage versus code simplicity and may get revisited in the future.
   return DINamespace::get(VMContext, getNonCompileUnitScope(Scope), Name,
                           ExportSymbols);
 }
 
 DIModule *DIBuilder::createModule(DIScope *Scope, StringRef Name,
                                   StringRef ConfigurationMacros,
-                                  StringRef IncludePath) {
+                                  StringRef IncludePath,
+                                  StringRef APINotesFile) {
   return DIModule::get(VMContext, getNonCompileUnitScope(Scope), Name,
-                       ConfigurationMacros, IncludePath);
+                       ConfigurationMacros, IncludePath, APINotesFile);
 }
 
 DILexicalBlockFile *DIBuilder::createLexicalBlockFile(DIScope *Scope,
                                                       DIFile *File,
                                                       unsigned Discriminator) {
   return DILexicalBlockFile::get(VMContext, Scope, File, Discriminator);
 }
 

llvm/lib/IR/DebugInfo.cpp

LLVMDIBuilderCreateFile(LLVMDIBuilderRef Builder, const char *Filename,
   return wrap(unwrap(Builder)->createFile(StringRef(Filename, FilenameLen),
                                           StringRef(Directory, DirectoryLen)));
 }
 
 LLVMMetadataRef
 LLVMDIBuilderCreateModule(LLVMDIBuilderRef Builder, LLVMMetadataRef ParentScope,
                           const char *Name, size_t NameLen,
                           const char *ConfigMacros, size_t ConfigMacrosLen,
-                          const char *IncludePath, size_t IncludePathLen) {
+                          const char *IncludePath, size_t IncludePathLen,
+                          const char *APINotesFile, size_t APINotesFileLen) {
   return wrap(unwrap(Builder)->createModule(
       unwrapDI<DIScope>(ParentScope), StringRef(Name, NameLen),
       StringRef(ConfigMacros, ConfigMacrosLen),
-      StringRef(IncludePath, IncludePathLen)));
+      StringRef(IncludePath, IncludePathLen),
+      StringRef(APINotesFile, APINotesFileLen)));
 }
 
 LLVMMetadataRef LLVMDIBuilderCreateNameSpace(LLVMDIBuilderRef Builder,
                                              LLVMMetadataRef ParentScope,
                                              const char *Name, size_t NameLen,
                                              LLVMBool ExportSymbols) {
   return wrap(unwrap(Builder)->createNameSpace(
       unwrapDI<DIScope>(ParentScope), StringRef(Name, NameLen), ExportSymbols));

llvm/lib/IR/DebugInfoMetadata.cpp

DICommonBlock *DICommonBlock::getImpl(LLVMContext &Context, Metadata *Scope,
   DEFINE_GETIMPL_LOOKUP(DICommonBlock, (Scope, Decl, Name, File, LineNo));
   // The nullptr is for DIScope's File operand. This should be refactored.
   Metadata *Ops[] = {Scope, Decl, Name, File};
   DEFINE_GETIMPL_STORE(DICommonBlock, (LineNo), Ops);
 }
 
 DIModule *DIModule::getImpl(LLVMContext &Context, Metadata *Scope,
                             MDString *Name, MDString *ConfigurationMacros,
-                            MDString *IncludePath, StorageType Storage,
-                            bool ShouldCreate) {
+                            MDString *IncludePath, MDString *APINotesFile,
+                            StorageType Storage, bool ShouldCreate) {
   assert(isCanonical(Name) && "Expected canonical MDString");
-  DEFINE_GETIMPL_LOOKUP(DIModule,
-                        (Scope, Name, ConfigurationMacros, IncludePath));
-  Metadata *Ops[] = {Scope, Name, ConfigurationMacros, IncludePath};
+  DEFINE_GETIMPL_LOOKUP(
+      DIModule, (Scope, Name, ConfigurationMacros, IncludePath, APINotesFile));
+  Metadata *Ops[] = {Scope, Name, ConfigurationMacros, IncludePath,
+                     APINotesFile};
   DEFINE_GETIMPL_STORE_NO_CONSTRUCTOR_ARGS(DIModule, Ops);
 }
 
 DITemplateTypeParameter *
 DITemplateTypeParameter::getImpl(LLVMContext &Context, MDString *Name,
                                  Metadata *Type, bool isDefault,
                                  StorageType Storage, bool ShouldCreate) {
   assert(isCanonical(Name) && "Expected canonical MDString");

llvm/lib/IR/LLVMContextImpl.h

template <> struct MDNodeKeyImpl<DICommonBlock> {
   }
 };
 
 template <> struct MDNodeKeyImpl<DIModule> {
   Metadata *Scope;
   MDString *Name;
   MDString *ConfigurationMacros;
   MDString *IncludePath;
+  MDString *APINotesFile;
 
   MDNodeKeyImpl(Metadata *Scope, MDString *Name, MDString *ConfigurationMacros,
-                MDString *IncludePath)
+                MDString *IncludePath, MDString *APINotesFile)
       : Scope(Scope), Name(Name), ConfigurationMacros(ConfigurationMacros),
-        IncludePath(IncludePath) {}
+        IncludePath(IncludePath), APINotesFile(APINotesFile) {}
   MDNodeKeyImpl(const DIModule *N)
       : Scope(N->getRawScope()), Name(N->getRawName()),
         ConfigurationMacros(N->getRawConfigurationMacros()),
-        IncludePath(N->getRawIncludePath()) {}
+        IncludePath(N->getRawIncludePath()),
+        APINotesFile(N->getRawAPINotesFile()) {}
 
   bool isKeyOf(const DIModule *RHS) const {
     return Scope == RHS->getRawScope() && Name == RHS->getRawName() &&
            ConfigurationMacros == RHS->getRawConfigurationMacros() &&
-           IncludePath == RHS->getRawIncludePath();
+           IncludePath == RHS->getRawIncludePath() &&
+           APINotesFile == RHS->getRawAPINotesFile();
   }
 
   unsigned getHashValue() const {
     return hash_combine(Scope, Name, ConfigurationMacros, IncludePath);
   }
 };
 
 template <> struct MDNodeKeyImpl<DITemplateTypeParameter> {

llvm/test/Assembler/dimodule.ll

 ; RUN: llvm-as < %s | llvm-dis | llvm-as | llvm-dis | FileCheck %s
 ; RUN: verify-uselistorder %s
 
-; CHECK: !named = !{!0, !1, !2, !1}
-!named = !{!0, !1, !2, !3}
+; CHECK: !named = !{!0, !1, !2, !1, !3}
+!named = !{!0, !1, !2, !3, !4}
 
 !0 = distinct !{}
 
 ; CHECK: !1 = !DIModule(scope: !0, name: "Module")
 !1 = !DIModule(scope: !0, name: "Module")
 
 ; CHECK: !2 = !DIModule(scope: !0, name: "Module", configMacros: "-DNDEBUG", includePath: "/usr/include")
 !2 = !DIModule(scope: !0, name: "Module", configMacros: "-DNDEBUG", includePath: "/usr/include")
 
 !3 = !DIModule(scope: !0, name: "Module", configMacros: "")
+
+; CHECK: !3 = !DIModule(scope: !0, name: "Module", configMacros: "-DNDEBUG", includePath: "/usr/include", apinotes: "/tmp/m.apinotes")
+!4 = !DIModule(scope: !0, name: "Module", configMacros: "-DNDEBUG", includePath: "/usr/include", apinotes: "/tmp/m.apinotes")

llvm/test/DebugInfo/X86/DIModule.ll

 ; ModuleID = '/Volumes/Data/apple-internal/llvm/tools/clang/test/Modules/debug-info-moduleimport.m'
 ; RUN: llc %s -accel-tables=Dwarf -o %t -filetype=obj
 ; RUN: llvm-dwarfdump -debug-info %t | FileCheck %s
 ; RUN: llvm-dwarfdump -verify %t
 ; CHECK: DW_TAG_compile_unit
 ; CHECK-NOT: DW_TAG
 ; CHECK:   DW_AT_LLVM_sysroot {{.*}}"/"
 ; CHECK:   DW_TAG_module
 ; CHECK-NEXT: DW_AT_name {{.*}}"DebugModule"
 ; CHECK-NEXT: DW_AT_LLVM_config_macros {{.*}}"-DMODULES=0"
 ; CHECK-NEXT: DW_AT_LLVM_include_path {{.*}}"/llvm/tools/clang/test/Modules/Inputs"
+; CHECK-NEXT: DW_AT_APPLE_apinotes {{.*}}"m.apinotes"
 
 target datalayout = "e-m:o-i64:64-f80:128-n8:16:32:64-S128"
 target triple = "x86_64-apple-macosx"
 
 !llvm.dbg.cu = !{!0}
 !llvm.module.flags = !{!6, !7}
 !llvm.ident = !{!8}
 
 !0 = distinct !DICompileUnit(language: DW_LANG_ObjC, file: !1, producer: "LLVM version 3.7.0", isOptimized: false, runtimeVersion: 2, emissionKind: FullDebug, enums: !2, retainedTypes: !2, globals: !2, imports: !3,  sysroot: "/")
 !1 = !DIFile(filename: "/llvm/tools/clang/test/Modules/<stdin>", directory: "/")
 !2 = !{}
 !3 = !{!4}
 !4 = !DIImportedEntity(tag: DW_TAG_imported_declaration, scope: !0, entity: !5, file: !1, line: 5)
-!5 = !DIModule(scope: null, name: "DebugModule", configMacros: "-DMODULES=0", includePath: "/llvm/tools/clang/test/Modules/Inputs")
+!5 = !DIModule(scope: null, name: "DebugModule", configMacros: "-DMODULES=0", includePath: "/llvm/tools/clang/test/Modules/Inputs", apinotes: "m.apinotes")
 !6 = !{i32 2, !"Dwarf Version", i32 4}
 !7 = !{i32 2, !"Debug Info Version", i32 3}
 !8 = !{!"LLVM version 3.7.0"}

llvm/tools/llvm-c-test/debuginfo.c

int llvm_test_dibuilder(void) {
   LLVMMetadataRef CompileUnit = LLVMDIBuilderCreateCompileUnit(
       DIB, LLVMDWARFSourceLanguageC, File, "llvm-c-test", 11, 0, NULL, 0, 0,
       NULL, 0, LLVMDWARFEmissionFull, 0, 0, 0, "/", 1);
 
   LLVMMetadataRef Module =
     LLVMDIBuilderCreateModule(DIB, CompileUnit,
                               "llvm-c-test", 11,
                               "", 0,
-                              "/test/include/llvm-c-test.h", 27);
+                              "/test/include/llvm-c-test.h", 27,
+                              "", 0);
 
   LLVMMetadataRef OtherModule =
     LLVMDIBuilderCreateModule(DIB, CompileUnit,
                               "llvm-c-test-import", 18,
                               "", 0,
-                              "/test/include/llvm-c-test-import.h", 34);
+                              "/test/include/llvm-c-test-import.h", 34,
+                              "", 0);
   LLVMMetadataRef ImportedModule =
     LLVMDIBuilderCreateImportedModuleFromModule(DIB, Module, OtherModule,
                                                 File, 42);
   LLVMDIBuilderCreateImportedModuleFromAlias(DIB, Module, ImportedModule,
                                              File, 42);
 
   LLVMMetadataRef ClassTy = declare_objc_class(DIB, File);
   LLVMMetadataRef GlobalClassValueExpr =

llvm/unittests/IR/MetadataTest.cpp

 
 typedef MetadataTest DIModuleTest;
 
 TEST_F(DIModuleTest, get) {
   DIScope *Scope = getFile();
   StringRef Name = "module";
   StringRef ConfigMacro = "-DNDEBUG";
   StringRef Includes = "-I.";
+  StringRef APINotes = "/tmp/m.apinotes";
 
-  auto *N = DIModule::get(Context, Scope, Name, ConfigMacro, Includes);
+  auto *N = DIModule::get(Context, Scope, Name, ConfigMacro, Includes, APINotes);
 
   EXPECT_EQ(dwarf::DW_TAG_module, N->getTag());
   EXPECT_EQ(Scope, N->getScope());
   EXPECT_EQ(Name, N->getName());
   EXPECT_EQ(ConfigMacro, N->getConfigurationMacros());
   EXPECT_EQ(Includes, N->getIncludePath());
-  EXPECT_EQ(N, DIModule::get(Context, Scope, Name, ConfigMacro, Includes));
-  EXPECT_NE(N, DIModule::get(Context, getFile(), Name, ConfigMacro, Includes));
-  EXPECT_NE(N, DIModule::get(Context, Scope, "other", ConfigMacro, Includes));
-  EXPECT_NE(N, DIModule::get(Context, Scope, Name, "other", Includes));
-  EXPECT_NE(N, DIModule::get(Context, Scope, Name, ConfigMacro, "other"));
+  EXPECT_EQ(APINotes, N->getAPINotesFile());
+  EXPECT_EQ(
+      N, DIModule::get(Context, Scope, Name, ConfigMacro, Includes, APINotes));
+  EXPECT_NE(N, DIModule::get(Context, getFile(), Name, ConfigMacro, Includes,
+                             APINotes));
+  EXPECT_NE(N, DIModule::get(Context, Scope, "other", ConfigMacro, Includes,
+                             APINotes));
+  EXPECT_NE(N,
+            DIModule::get(Context, Scope, Name, "other", Includes, APINotes));
+  EXPECT_NE(
+      N, DIModule::get(Context, Scope, Name, ConfigMacro, "other", APINotes));
+  EXPECT_NE(
+      N, DIModule::get(Context, Scope, Name, ConfigMacro, Includes, "other"));
 
   TempDIModule Temp = N->clone();
   EXPECT_EQ(N, MDNode::replaceWithUniqued(std::move(Temp)));
 }
 
 typedef MetadataTest DITemplateTypeParameterTest;
 
 TEST_F(DITemplateTypeParameterTest, get) {