lldb/docs/resources/extensions.rst

   1 DWARF Extensions
   2 ================
   3
   4 LLDB supports some DWARF extensions produced by Clang.
   5
   6 Clang ``-gmodules`` debug info
   7 ------------------------------
   8
   9 On Darwin platforms, including Apple macOS and iOS, Clang can emit
  10 DWARF debug info for types found in `Clang
  11 modules <https://clang.llvm.org/docs/Modules.html>`_ more efficiently.
  12
  13 From an on-disk storage perspective, Clang modules are precompiled
  14 header files that contain serialized Clang ASTs of all the
  15 declarations found in a Clang module. In traditional DWARF debug info,
  16 two object files that were built from sources that imported the same
  17 header file will both contain DWARF debug type info for types in that
  18 header file. This can lead to a lot of redundant `debug
  19 info <https://llvm.org/devmtg/2015-10/#talk19>`_.
  20
  21 When Clang compiles a Clang module or precompiled header with the
  22 ``-gmodules`` option, the precompiled header (``.pch``) or module
  23 (``.pcm``) files become object file containers (on Darwin: Mach-O)
  24 that hold a ``__clang_ast`` section with the serialized Clang AST and
  25 various DWARF sections containing debug info for the type declarations
  26 found in the header or module.
  27
  28 This allows Clang to omit these type definitions from the object
  29 (``.o``) files and replace them with forward declarations to save
  30 space. Type declarations in a Clang module are nested inside one
  31 ``DW_TAG_module``, or -- in the case of submodules -- multiple levels
  32 of ``DW_TAG_module``. If a DWARF DIE needs to reference a type DIE
  33 from another module, Clang emits a forward declaration of the
  34 referenced DIE into a ``DW_TAG_module`` inside the same compile unit.
  35
  36 When a consumer sees a forward declaration that is nested inside a
  37 ``DW_TAG_module``, it knows that it can find the full type declaration
  38 in an external ``.pcm`` or ``.pch`` file. To facilitate locating these
  39 external dependencies, Clang emits skeleton CUs into each object file
  40 that references external modules. Clang uses the same mechanism that
  41 is used to locate external ``.dwo`` files on ELF-based platforms. The
  42 ``DW_AT_GNU_dwo_name`` contains the absolute path to the ``.pcm``
  43 file, and the ``DW_AT_GNU_dwo_id`` is a hash of the contents that is
  44 repeated in the ``DW_TAG_compile_unit`` of the ``.pcm`` file.
  45
  46 For example:
  47
  48 M.h
  49
  50 ::
  51
  52    struct A {
  53      int x;
  54    };
  55
  56
  57 M.pcm
  58
  59 ::
  60
  61    DW_TAG_compile_unit
  62      DW_AT_GNU_dwo_id  (0xabcdef)
  63      DW_TAG_module
  64        DW_AT_name "M"
  65        DW_TAG_structure
  66          DW_AT_name "A"
  67          DW_TAG_member
  68            DW_AT_name "x"
  69
  70 A.c
  71
  72 ::
  73
  74    A a;
  75
  76 A.o
  77
  78 ::
  79
  80    DW_TAG_compile_unit
  81      DW_TAG_module
  82        DW_AT_name "M"
  83        DW_TAG_structure
  84          DW_AT_name "A"
  85          DW_AT_declaration (true)
  86      DW_TAG_variable
  87        DW_AT_name "a"
  88        DW_AT_type (local ref to fwd decl "A")
  89
  90    DW_TAG_compile_unit
  91      DW_AT_GNU_dwo_id  (0xabcdef)
  92      DW_AT_GNU_dwo_name    ("M.pcm")
  93
  94 The debug info inside a ``.pcm`` file may recursively reference
  95 further external types that are defined in other ``.pcm`` files. Clang
  96 generates external references (and debug info inside the modules) for
  97 the following types:
  98
  99 C:
 100
 101 - ``struct``
 102 - ``union``
 103 - ``enum``
 104 - ``typedef``
 105
 106 Objective-C:
 107
 108 - all the C types listed above
 109 - ``@interface``
 110
 111 C++:
 112
 113 - all the C types listed above
 114 - ``namespace``
 115 - any explicit ``extern template`` specializations
 116
 117 LLDB supports this DWARF extension only when debugging from ``.o``
 118 files. The ``dsymutil`` debug info linker also understands this format
 119 and will resolve all module type references to point straight to the
 120 underlying defining declaration. Because of this a ``.dSYM`` bundle
 121 will never contain any ``-gmodules``-style references.
 122
 123 Apple SDK information
 124 ---------------------
 125
 126 Clang and the Swift compiler emit information about the Xcode SDK that
 127 was used to build a translation unit into the ``DW_TAG_compile_unit``.
 128 The ``DW_AT_LLVM_sysroot`` attribute points to the SDK root
 129 (equivalent to Clang's ``-isysroot`` option). The ``DW_AT_APPLE_sdk``
 130 attribute contains the name of the SDK, for example ``MacOSX.sdk``.
 131
 132 Objective-C runtime
 133 -------------------
 134
 135 Clang emits the Objective-C runtime version into the
 136 ``DW_TAG_compile_unit`` using the
 137 ``DW_AT_APPLE_major_runtime_version`` attribute. The value 2 stands
 138 for Objective-C 2.0.