DebugInfo: Move new hierarchy into place

Move the specialized metadata nodes for the new debug info hierarchy
into place, finishing off PR22464.  I've done bootstraps (and all that)
and I'm confident this commit is NFC as far as DWARF output is
concerned.  Let me know if I'm wrong :).

The code changes are fairly mechanical:

  - Bumped the "Debug Info Version".
  - `DIBuilder` now creates the appropriate subclass of `MDNode`.
  - Subclasses of DIDescriptor now expect to hold their "MD"
    counterparts (e.g., `DIBasicType` expects `MDBasicType`).
  - Deleted a ton of dead code in `AsmWriter.cpp` and `DebugInfo.cpp`
    for printing comments.
  - Big update to LangRef to describe the nodes in the new hierarchy.
    Feel free to make it better.

Testcase changes are enormous.  There's an accompanying clang commit on
its way.

If you have out-of-tree debug info testcases, I just broke your build.

  - `upgrade-specialized-nodes.sh` is attached to PR22564.  I used it to
    update all the IR testcases.
  - Unfortunately I failed to find way to script the updates to CHECK
    lines, so I updated all of these by hand.  This was fairly painful,
    since the old CHECKs are difficult to reason about.  That's one of
    the benefits of the new hierarchy.

This work isn't quite finished, BTW.  The `DIDescriptor` subclasses are
almost empty wrappers, but not quite: they still have loose casting
checks (see the `RETURN_FROM_RAW()` macro).  Once they're completely
gutted, I'll rename the "MD" classes to "DI" and kill the wrappers.  I
also expect to make a few schema changes now that it's easier to reason
about everything.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@231082 91177308-0d34-0410-b5e6-96231b3b80d8

docs/LangRef.rst

@@ -2837,6 +2837,8 @@ Metadata does not have a type, and is not a value.  If referenced from a
 
 All metadata are identified in syntax by a exclamation point ('``!``').
 
+.. _metadata-string:
+
 Metadata Nodes and Metadata Strings
 -----------------------------------
 
@@ -2896,16 +2898,299 @@ Specialized metadata nodes are custom data structures in metadata (as opposed
 to generic tuples).  Their fields are labelled, and can be specified in any
 order.
 
+These aren't inherently debug info centric, but currently all the specialized
+metadata nodes are related to debug info.
+
+MDCompileUnit
+"""""""""""""
+
+``MDCompileUnit`` nodes represent a compile unit.  The ``enums:``,
+``retainedTypes:``, ``subprograms:``, ``globals:`` and ``imports:`` fields are
+tuples containing the debug info to be emitted along with the compile unit,
+regardless of code optimizations (some nodes are only emitted if there are
+references to them from instructions).
+
+.. code-block:: llvm
+
+    !0 = !MDCompileUnit(language: DW_LANG_C99, file: !1, producer: "clang",
+                        isOptimized: true, flags: "-O2", runtimeVersion: 2,
+                        splitDebugFilename: "abc.debug", emissionKind: 1,
+                        enums: !2, retainedTypes: !3, subprograms: !4,
+                        globals: !5, imports: !6)
+
+MDFile
+""""""
+
+``MDFile`` nodes represent files.  The ``filename:`` can include slashes.
+
+.. code-block:: llvm
+
+    !0 = !MDFile(filename: "path/to/file", directory: "/path/to/dir")
+
+.. _MDLocation:
+
+MDBasicType
+"""""""""""
+
+``MDBasicType`` nodes represent primitive types.  ``tag:`` defaults to
+``DW_TAG_base_type``.
+
+.. code-block:: llvm
+
+    !0 = !MDBasicType(name: "unsigned char", size: 8, align: 8,
+                      encoding: DW_ATE_unsigned_char)
+    !1 = !MDBasicType(tag: DW_TAG_unspecified_type, name: "decltype(nullptr)")
+
+.. _MDSubroutineType:
+
+MDSubroutineType
+""""""""""""""""
+
+``MDSubroutineType`` nodes represent subroutine types.  Their ``types:`` field
+refers to a tuple; the first operand is the return type, while the rest are the
+types of the formal arguments in order.  If the first operand is ``null``, that
+represents a function with no return value (such as ``void foo() {}`` in C++).
+
+.. code-block:: llvm
+
+    !0 = !BasicType(name: "int", size: 32, align: 32, DW_ATE_signed)
+    !1 = !BasicType(name: "char", size: 8, align: 8, DW_ATE_signed_char)
+    !2 = !MDSubroutineType(types: !{null, !0, !1}) ; void (int, char)
+
+MDDerivedType
+"""""""""""""
+
+``MDDerivedType`` nodes represent types derived from other types, such as
+qualified types.
+
+.. code-block:: llvm
+
+    !0 = !MDBasicType(name: "unsigned char", size: 8, align: 8,
+                      encoding: DW_ATE_unsigned_char)
+    !1 = !MDDerivedType(tag: DW_TAG_pointer_type, baseType: !0, size: 32,
+                        align: 32)
+
+.. _MDCompositeType:
+
+MDCompositeType
+"""""""""""""""
+
+``MDCompositeType`` nodes represent types composed of other types, like
+structures and unions.  ``elements:`` points to a tuple of the composed types.
+
+If the source language supports ODR, the ``identifier:`` field gives the unique
+identifier used for type merging between modules.  When specified, other types
+can refer to composite types indirectly via a :ref:`metadata string
+<metadata-string>` that matches their identifier.
+
+.. code-block:: llvm
+
+    !0 = !MDEnumerator(name: "SixKind", value: 7)
+    !1 = !MDEnumerator(name: "SevenKind", value: 7)
+    !2 = !MDEnumerator(name: "NegEightKind", value: -8)
+    !3 = !MDCompositeType(tag: DW_TAG_enumeration_type, name: "Enum", file: !12,
+                          line: 2, size: 32, align: 32, identifier: "_M4Enum",
+                          elements: !{!0, !1, !2})
+
+MDSubrange
+""""""""""
+
+``MDSubrange`` nodes are the elements for ``DW_TAG_array_type`` variants of
+:ref:`MDCompositeType`.  ``count: -1`` indicates an empty array.
+
+.. code-block:: llvm
+
+    !0 = !MDSubrange(count: 5, lowerBound: 0) ; array counting from 0
+    !1 = !MDSubrange(count: 5, lowerBound: 1) ; array counting from 1
+    !2 = !MDSubrange(count: -1) ; empty array.
+
+MDEnumerator
+""""""""""""
+
+``MDEnumerator`` nodes are the elements for ``DW_TAG_enumeration_type``
+variants of :ref:`MDCompositeType`.
+
+.. code-block:: llvm
+
+    !0 = !MDEnumerator(name: "SixKind", value: 7)
+    !1 = !MDEnumerator(name: "SevenKind", value: 7)
+    !2 = !MDEnumerator(name: "NegEightKind", value: -8)
+
+MDTemplateTypeParameter
+"""""""""""""""""""""""
+
+``MDTemplateTypeParameter`` nodes represent type parameters to generic source
+language constructs.  They are used (optionally) in :ref:`MDCompositeType` and
+:ref:`MDSubprogram` ``templateParams:`` fields.
+
+.. code-block:: llvm
+
+    !0 = !MDTemplateTypeParameter(name: "Ty", type: !1)
+
+MDTemplateValueParameter
+""""""""""""""""""""""""
+
+``MDTemplateValueParameter`` nodes represent value parameters to generic source
+language constructs.  ``tag:`` defaults to ``DW_TAG_template_value_parameter``,
+but if specified can also be set to ``DW_TAG_GNU_template_template_param`` or
+``DW_TAG_GNU_template_param_pack``.  They are used (optionally) in
+:ref:`MDCompositeType` and :ref:`MDSubprogram` ``templateParams:`` fields.
+
+.. code-block:: llvm
+
+    !0 = !MDTemplateValueParameter(name: "Ty", type: !1, value: i32 7)
+
+MDNamespace
+"""""""""""
+
+``MDNamespace`` nodes represent namespaces in the source language.
+
+.. code-block:: llvm
+
+    !0 = !MDNamespace(name: "myawesomeproject", scope: !1, file: !2, line: 7)
+
+MDGlobalVariable
+""""""""""""""""
+
+``MDGlobalVariable`` nodes represent global variables in the source language.
+
+.. code-block:: llvm
+
+    !0 = !MDGlobalVariable(name: "foo", linkageName: "foo", scope: !1,
+                           file: !2, line: 7, type: !3, isLocal: true,
+                           isDefinition: false, variable: i32* @foo,
+                           declaration: !4)
+
+.. _MDSubprogram:
+
+MDSubprogram
+""""""""""""
+
+``MDSubprogram`` nodes represent functions from the source language.  The
+``variables:`` field points at :ref:`variables <MDLocalVariable>` that must be
+retained, even if their IR counterparts are optimized out of the IR.  The
+``type:`` field must point at an :ref:`MDSubroutineType`.
+
+.. code-block:: llvm
+
+    !0 = !MDSubprogram(name: "foo", linkageName: "_Zfoov", scope: !1,
+                       file: !2, line: 7, type: !3, isLocal: true,
+                       isDefinition: false, scopeLine: 8, containingType: !4,
+                       virtuality: DW_VIRTUALITY_pure_virtual, virtualIndex: 10,
+                       flags: DIFlagPrototyped, isOptimized: true,
+                       function: void ()* @_Z3foov,
+                       templateParams: !5, declaration: !6, variables: !7)
+
+.. _MDLexicalBlock:
+
+MDLexicalBlock
+""""""""""""""
+
+``MDLexicalBlock`` nodes represent lexical blocks in the source language (a
+scope).
+
+.. code-block:: llvm
+
+    !0 = !MDLexicalBlock(scope: !1, file: !2, line: 7, column: 35)
+
+.. _MDLexicalBlockFile:
+
+MDLexicalBlockFile
+""""""""""""""""""
+
+``MDLexicalBlockFile`` nodes are used to discriminate between sections of a
+:ref:`lexical block <MDLexicalBlock>`.  The ``file:`` field can be changed to
+indicate textual inclusion, or the ``discriminator:`` field can be used to
+discriminate between control flow within a single block in the source language.
+
+.. code-block:: llvm
+
+    !0 = !MDLexicalBlock(scope: !3, file: !4, line: 7, column: 35)
+    !1 = !MDLexicalBlockFile(scope: !0, file: !4, discriminator: 0)
+    !2 = !MDLexicalBlockFile(scope: !0, file: !4, discriminator: 1)
+
 MDLocation
 """"""""""
 
 ``MDLocation`` nodes represent source debug locations.  The ``scope:`` field is
-mandatory.
+mandatory, and points at an :ref:`MDLexicalBlockFile`, an
+:ref:`MDLexicalBlock`, or an :ref:`MDSubprogram`.
 
 .. code-block:: llvm
 
     !0 = !MDLocation(line: 2900, column: 42, scope: !1, inlinedAt: !2)
 
+.. _MDLocalVariable:
+
+MDLocalVariable
+"""""""""""""""
+
+``MDLocalVariable`` nodes represent local variables in the source language.
+Instead of ``DW_TAG_variable``, they use LLVM-specific fake tags to
+discriminate between local variables (``DW_TAG_auto_variable``) and subprogram
+arguments (``DW_TAG_arg_variable``).  In the latter case, the ``arg:`` field
+specifies the argument position, and this variable will be included in the
+``variables:`` field of its :ref:`MDSubprogram`.
+
+If set, the ``inlinedAt:`` field points at an :ref:`MDLocation`, and the
+variable represents an inlined version of a variable (with all other fields
+duplicated from the non-inlined version).
+
+.. code-block:: llvm
+
+    !0 = !MDLocalVariable(tag: DW_TAG_arg_variable, name: "this", arg: 0,
+                          scope: !3, file: !2, line: 7, type: !3,
+                          flags: DIFlagArtificial, inlinedAt: !4)
+    !1 = !MDLocalVariable(tag: DW_TAG_arg_variable, name: "x", arg: 1,
+                          scope: !4, file: !2, line: 7, type: !3,
+                          inlinedAt: !6)
+    !1 = !MDLocalVariable(tag: DW_TAG_auto_variable, name: "y",
+                          scope: !5, file: !2, line: 7, type: !3,
+                          inlinedAt: !6)
+
+MDExpression
+""""""""""""
+
+``MDExpression`` nodes represent DWARF expression sequences.  They are used in
+:ref:`debug intrinsics<dbg_intrinsics>` (such as ``llvm.dbg.declare``) to
+describe how the referenced LLVM variable relates to the source language
+variable.
+
+The current supported vocabulary is limited:
+
+- ``DW_OP_deref`` dereferences the working expression.
+- ``DW_OP_plus, 93`` adds ``93`` to the working expression.
+- ``DW_OP_bit_piece, 16, 8`` specifies the offset and size (``16`` and ``8``
+  here, respectively) of the variable piece from the working expression.
+
+.. code-block:: llvm
+
+    !0 = !MDExpression(DW_OP_deref)
+    !1 = !MDExpression(DW_OP_plus, 3)
+    !2 = !MDExpression(DW_OP_bit_piece, 3, 7)
+    !3 = !MDExpression(DW_OP_deref, DW_OP_plus, 3, DW_OP_bit_piece, 3, 7)
+
+MDObjCProperty
+""""""""""""""
+
+``MDObjCProperty`` nodes represent Objective-C property nodes.
+
+.. code-block:: llvm
+
+    !3 = !MDObjCProperty(name: "foo", file: !1, line: 7, setter: "setFoo",
+                         getter: "getFoo", attributes: 7, type: !2)
+
+MDImportedEntity
+""""""""""""""""
+
+``MDImportedEntity`` nodes represent entities (such as modules) imported into a
+compile unit.
+
+.. code-block:: llvm
+
+   !2 = !MDImportedEntity(tag: DW_TAG_imported_module, name: "foo", scope: !0,
+                          entity: !1, line: 7)
+
 '``tbaa``' Metadata
 ^^^^^^^^^^^^^^^^^^^
 
@@ -9217,6 +9502,8 @@ Examples:
       %a = load i16* @x, align 2
       %res = call float @llvm.convert.from.fp16(i16 %a)
 
+.. _dbg_intrinsics:
+
 Debugger Intrinsics
 -------------------