brintos / llvm-project-archived public Read only

1================================2Source Level Debugging with LLVM3================================4 5.. contents::6   :local:7 8Introduction9============10 11This document is the central repository for all information pertaining to debug12information in LLVM.  It describes the :ref:`actual format that the LLVM debug13information takes <format>`, which is useful for those interested in creating14front-ends or dealing directly with the information.  Further, this document15provides specific examples of what debug information for C/C++ looks like.16 17Philosophy behind LLVM debugging information18--------------------------------------------19 20The idea of the LLVM debugging information is to capture how the important21pieces of the source-language's Abstract Syntax Tree map onto LLVM code.22Several design aspects have shaped the solution that appears here.  The23important ones are:24 25* Debugging information should have very little impact on the rest of the26  compiler.  No transformations, analyses, or code generators should need to27  be modified because of debugging information.28 29* LLVM optimizations should interact in :ref:`well-defined and easily described30  ways <intro_debugopt>` with the debugging information.31 32* Because LLVM is designed to support arbitrary programming languages,33  LLVM-to-LLVM tools should not need to know anything about the semantics of34  the source-level-language.35 36* Source-level languages are often **widely** different from one another.37  LLVM should not put any restrictions on the flavor of the source-language,38  and the debugging information should work with any language.39 40* With code generator support, it should be possible to use an LLVM compiler41  to compile a program to native machine code and standard debugging42  formats.  This allows compatibility with traditional machine-code level43  debuggers, like GDB or DBX.44 45The approach used by the LLVM implementation is to use a small set of46:ref:`debug records <debug_records>` to define a mapping47between LLVM program objects and the source-level objects.  The description of48the source-level program is maintained in LLVM metadata in an49:ref:`implementation-defined format <ccxx_frontend>` (the C/C++ front-end50currently uses working draft 7 of the `DWARF 3 standard51<http://www.eagercon.com/dwarf/dwarf3std.htm>`_).52 53When a program is being debugged, a debugger interacts with the user and turns54the stored debug information into source-language specific information.  As55such, a debugger must be aware of the source-language, and is thus tied to a56specific language or family of languages.57 58.. _intro_consumers:59 60Debug information consumers61---------------------------62 63The role of debug information is to provide meta information normally stripped64away during the compilation process.  This meta information provides an LLVM65user a relationship between generated code and the original program source66code.67 68Currently, there are two backend consumers of debug info: DwarfDebug and69CodeViewDebug. DwarfDebug produces DWARF suitable for use with GDB, LLDB, and70other DWARF-based debuggers. :ref:`CodeViewDebug <codeview>` produces CodeView,71the Microsoft debug info format, which is usable with Microsoft debuggers such72as Visual Studio and WinDBG. LLVM's debug information format is mostly derived73from and inspired by DWARF, but it is feasible to translate into other target74debug info formats such as STABS.75 76SamplePGO (also known as `AutoFDO <https://gcc.gnu.org/wiki/AutoFDO>`_)77is a variant of profile-guided optimizations which uses hardware sampling based78profilers to collect branch frequency data with low overhead in production79environments. It relies on debug information to associate profile information80with LLVM IR which is then used to guide optimization heuristics. Maintaining81deterministic and distinct source locations is necessary to maximize the82accuracy of mapping hardware sample counts to LLVM IR. For example, DWARF83`discriminators <https://wiki.dwarfstd.org/Path_Discriminators.md>`_ allow84SamplePGO to distinguish between multiple paths of execution which map to the85same source line.86 87It would also be reasonable to use debug information to feed profiling tools88for analysis of generated code, or, tools for reconstructing the original89source from generated code.90 91.. _intro_debugopt:92 93Debug information and optimizations94-----------------------------------95 96An extremely high priority of LLVM debugging information is to make it interact97well with optimizations and analysis.  In particular, the LLVM debug98information provides the following guarantees:99 100* LLVM debug information **always provides information to accurately read101  the source-level state of the program**, regardless of which LLVM102  optimizations have been run. :doc:`HowToUpdateDebugInfo` specifies how debug103  info should be updated in various kinds of code transformations to avoid104  breaking this guarantee, and how to preserve as much useful debug info as105  possible.  Note that some optimizations may impact the ability to modify the106  current state of the program with a debugger, such as setting program107  variables, or calling functions that have been deleted.108 109* As desired, LLVM optimizations can be upgraded to be aware of debugging110  information, allowing them to update the debugging information as they111  perform aggressive optimizations.  This means that, with effort, the LLVM112  optimizers could optimize debug code just as well as non-debug code.113 114* LLVM debug information does not prevent optimizations from115  happening (for example inlining, basic block reordering/merging/cleanup,116  tail duplication, etc).117 118* LLVM debug information is automatically optimized along with the rest of119  the program, using existing facilities.  For example, duplicate120  information is automatically merged by the linker, and unused information121  is automatically removed.122 123Basically, the debug information allows you to compile a program with124"``-O0 -g``" and get full debug information, allowing you to arbitrarily modify125the program as it executes from a debugger.  Compiling a program with126"``-O3 -g``" gives you full debug information that is always available and127accurate for reading (e.g., you get accurate stack traces despite tail call128elimination and inlining), but you might lose the ability to modify the program129and call functions which were optimized out of the program, or inlined away130completely.131 132The :doc:`LLVM test-suite <TestSuiteMakefileGuide>` provides a framework to133test the optimizer's handling of debugging information.  It can be run like134this:135 136.. code-block:: bash137 138  % cd llvm/projects/test-suite/MultiSource/Benchmarks  # or some other level139  % make TEST=dbgopt140 141This will test impact of debugging information on optimization passes.  If142debugging information influences optimization passes then it will be reported143as a failure.  See :doc:`TestingGuide` for more information on LLVM test144infrastructure and how to run various tests.145 146.. _variables_and_variable_fragments:147 148Variables and Variable Fragments149================================150 151In this document "variable" refers generally to any source language object152which can have a value, including at least:153 154- Variables155- Constants156- Formal parameters157 158.. note::159 160   There is no special provision for "true" constants in LLVM today, and161   they are instead treated as local or global variables.162 163A variable is represented by a :ref:`local variable <dilocalvariable>` or164:ref:`global variable <diglobalvariable>` metadata node.165 166A "variable fragment" (or just "fragment") is a contiguous span of bits of a167variable.168 169A :ref:`debug record <debug_records>` which refers to a :ref:`diexpression`170ending with a ``DW_OP_LLVM_fragment`` operation describes a fragment of the171variable it refers to.172 173The operands of the ``DW_OP_LLVM_fragment`` operation encode the bit offset of174the fragment relative to the start of the variable, and the size of the175fragment in bits, respectively.176 177.. note::178 179   The ``DW_OP_LLVM_fragment`` operation acts only to encode the fragment180   information, and does not have an effect on the semantics of the expression.181 182.. _format:183 184Debugging information format185============================186 187LLVM debugging information has been carefully designed to make it possible for188the optimizer to optimize the program and debugging information without189necessarily having to know anything about debugging information.  In190particular, the use of metadata avoids duplicated debugging information from191the beginning, and the global dead code elimination pass automatically deletes192debugging information for a function if it decides to delete the function.193 194To do this, most of the debugging information (descriptors for types,195variables, functions, source files, etc) is inserted by the language front-end196in the form of LLVM metadata.197 198Debug information is designed to be agnostic about the target debugger and199debugging information representation (e.g. DWARF/Stabs/etc).  It uses a generic200pass to decode the information that represents variables, types, functions,201namespaces, etc: this allows for arbitrary source-language semantics and202type-systems to be used, as long as there is a module written for the target203debugger to interpret the information.204 205To provide basic functionality, the LLVM debugger does have to make some206assumptions about the source-level language being debugged, though it keeps207these to a minimum.  The only common features that the LLVM debugger assumes208exist are :ref:`source files <difile>`, and :ref:`program objects209<diglobalvariable>`.  These abstract objects are used by a debugger to form210stack traces, show information about local variables, etc.211 212This section of the documentation first describes the representation aspects213common to any source-language.  :ref:`ccxx_frontend` describes the data layout214conventions used by the C and C++ front-ends.215 216Debug information descriptors are :ref:`specialized metadata nodes217<specialized-metadata>`, first-class subclasses of ``Metadata``.218 219There are two models for defining the values of source variables at different220states of the program and tracking these values through optimization and code221generation: :ref:`debug records <debug_records>`, the current default, and222:ref:`intrinsic function calls <format_common_intrinsics>`, which are223non-default but currently supported for backwards compatibility - though these224two models must never be mixed within an IR module. For an explanation of why225we changed to the new model, how it works, and guidance on how to update old226code or IR to use debug records, see the `RemoveDIs <RemoveDIsDebugInfo.html>`_227document.228 229.. _debug_records:230 231Debug Records232-------------233 234Debug records define the value that a source variable has during execution of235the program; they appear interleaved with instructions, although they are not236instructions themselves and have no effect on the code generated by the237compiler.238 239LLVM uses several types of debug records to define source variables. The240common syntax for these records is:241 242.. code-block:: llvm243 244    #dbg_<kind>([<arg>, ]* <DILocation>)245  ; Using the intrinsic model, the above is equivalent to:246  call void llvm.dbg.<kind>([metadata <arg>, ]*), !dbg <DILocation>247 248Debug records are always printed with an extra level of indentation compared249to instructions, and always have the prefix `#dbg_` and a list of250comma-separated arguments in parentheses, as with a `call`.251 252``#dbg_declare``253^^^^^^^^^^^^^^^^254 255.. code-block:: llvm256 257    #dbg_declare([Value|MDNode], DILocalVariable, DIExpression, DILocation)258 259This record provides information about a local element (e.g., variable). The260first argument is an SSA ``ptr`` value corresponding to a variable address, and261is typically a static ``alloca`` in the function entry block.  The second262argument is a :ref:`local variable <dilocalvariable>` containing a description263of the variable.  The third argument is a :ref:`complex expression264<diexpression>`. The fourth argument is a :ref:`source location <dilocation>`.265A ``#dbg_declare`` record describes the *address* of a source variable.266 267.. code-block:: llvm268 269    %i.addr = alloca i32, align 4270      #dbg_declare(ptr %i.addr, !1, !DIExpression(), !2)271    ; ...272    !1 = !DILocalVariable(name: "i", ...) ; int i273    !2 = !DILocation(...)274    ; ...275    %buffer = alloca [256 x i8], align 8276    ; The address of i is buffer+64.277      #dbg_declare(ptr %buffer, !3, !DIExpression(DW_OP_plus, 64), !4)278    ; ...279    !3 = !DILocalVariable(name: "i", ...) ; int i280    !4 = !DILocation(...)281 282A frontend should generate exactly one ``#dbg_declare`` record at the point283of declaration of a source variable. Optimization passes that fully promote the284variable from memory to SSA values will replace this record with possibly285multiple ``#dbg_value``` records. Passes that delete stores are effectively286partial promotion, and they will insert a mix of ``#dbg_value`` records to287track the source variable value when it is available. After optimization, there288may be multiple ``#dbg_declare`` records describing the program points where289the variables lives in memory. All calls for the same concrete source variable290must agree on the memory location.291 292 293``#dbg_value``294^^^^^^^^^^^^^^295 296.. code-block:: llvm297 298    #dbg_value([Value|DIArgList|MDNode], DILocalVariable, DIExpression, DILocation)299 300This record provides information when a user source variable is set to a new301value.  The first argument is the new value. The second argument is a302:ref:`local variable <dilocalvariable>` containing a description of the303variable.  The third argument is a :ref:`complex expression <diexpression>`.304The fourth argument is a :ref:`source location <dilocation>`.305 306A ``#dbg_value`` record describes the *value* of a source variable307directly, not its address.  Note that the value operand of this intrinsic may308be indirect (i.e, a pointer to the source variable), provided that interpreting309the complex expression derives the direct value.310 311 312``#dbg_declare_value``313^^^^^^^^^^^^^^^^^^^^^^314 315.. code-block:: llvm316 317    #dbg_declare_value([Value|MDNode], DILocalVariable, DIExpression, DILocation)318 319This record provides information about a local element (e.g., variable). The320first argument is used to compute the value of the variable throughout the 321entire function.  The second argument is a 322:ref:`local variable <dilocalvariable>` containing a description of the 323variable. The third argument is a :ref:`complex expression <diexpression>`. The324foruth argument is a :ref:`source location <dilocation>`. A 325``#dbg_declare_value`` record describes describes the *value* of a source 326variable directly, not its address. The difference between a ``#dbg_value`` and327a ``#dbg_declare_value`` is that, just like a ``#dbg_declare``, a frontend 328should generate exactly one ``#dbg_declare_value`` record. The idea is to have329``#dbg_declare`` guarantees but be able to describe a value rather than the 330address of a value.331 332 333``#dbg_assign``334^^^^^^^^^^^^^^^335.. toctree::336   :hidden:337 338   AssignmentTracking339 340.. code-block:: llvm341 342  #dbg_assign( [Value|DIArgList|MDNode] Value,343               DILocalVariable Variable,344               DIExpression ValueExpression,345               DIAssignID ID,346               [Value|MDNode] Address,347               DIExpression AddressExpression,348               DILocation SourceLocation )349 350This record marks the position in IR where a source assignment occurred. It351encodes the value of the variable. It references the store, if any, that352performs the assignment, and the destination address.353 354The first three arguments are the same as for a ``#dbg_value``. The fourth355argument is a ``DIAssignID`` used to reference a store. The fifth is the356destination of the store, the sixth is a :ref:`complex expression357<diexpression>` that modifies it, and the seventh is a :ref:`source location358<dilocation>`.359 360See :doc:`AssignmentTracking` for more info.361 362Debugger intrinsic functions363----------------------------364 365.. warning::366 367  These intrinsics are deprecated, please use :ref:`debug records368  <debug_records>` instead. For more details see `RemoveDIs369  <RemoveDIsDebugInfo.html>`_.370 371.. _format_common_intrinsics:372 373In intrinsic-mode, LLVM uses several intrinsic functions (name prefixed with "``llvm.dbg``") to374track source local variables through optimization and code generation. These375intrinsic functions each correspond to one of the debug records above, with a376few syntactic differences: each argument to a debugger intrinsic must be wrapped377as metadata, meaning it must be prefixed with ``metadata``, and the378``DILocation`` argument in each record must be a metadata attachment to the379call instruction, meaning it appears after the argument list with the prefix380``!dbg``.381 382``llvm.dbg.declare``383^^^^^^^^^^^^^^^^^^^^384 385.. code-block:: llvm386 387  void @llvm.dbg.declare(metadata, metadata, metadata)388 389This intrinsic is equivalent to ``#dbg_declare``:390 391.. code-block:: llvm392 393      #dbg_declare(i32* %i.addr, !1, !DIExpression(), !2)394    call void @llvm.dbg.declare(metadata i32* %i.addr, metadata !1,395                                metadata !DIExpression()), !dbg !2396 397``llvm.dbg.value``398^^^^^^^^^^^^^^^^^^399 400.. code-block:: llvm401 402  void @llvm.dbg.value(metadata, metadata, metadata)403 404This intrinsic is equivalent to ``#dbg_value``:405 406.. code-block:: llvm407 408      #dbg_value(i32 %i, !1, !DIExpression(), !2)409    call void @llvm.dbg.value(metadata i32 %i, metadata !1,410                              metadata !DIExpression()), !dbg !2411 412``llvm.dbg.assign``413^^^^^^^^^^^^^^^^^^^414 415.. code-block:: llvm416 417  void @llvm.dbg.assign(metadata, metadata, metadata, metadata, metadata, metadata)418 419This intrinsic is equivalent to ``#dbg_assign``:420 421.. code-block:: llvm422 423      #dbg_assign(i32 %i, !1, !DIExpression(), !2,424                  ptr %i.addr, !DIExpression(), !3)425    call void @llvm.dbg.assign(426      metadata i32 %i, metadata !1, metadata !DIExpression(), metadata !2,427      metadata ptr %i.addr, metadata !DIExpression(), metadata !3), !dbg !3428 429.. _diexpression:430 431DIExpression432------------433 434Debug expressions are represented as :ref:`specialized-metadata`.435 436Debug expressions are interpreted left-to-right: start by pushing the437value/address operand of the record onto a stack, then repeatedly push and438evaluate opcodes from the ``DIExpression`` until the final variable description439is produced.440 441The opcodes available in these expressions are described in442:ref:`dwarf-opcodes` and :ref:`internal-opcodes`.443 444DWARF specifies three kinds of simple location descriptions: register, memory,445and implicit location descriptions.  Note that a location description is446defined over certain ranges of a program, i.e the location of a variable may447change over the course of the program. Register and memory location448descriptions describe the *concrete location* of a source variable (in the449sense that a debugger might modify its value), whereas *implicit locations*450describe merely the actual *value* of a source variable which might not exist451in registers or in memory (see ``DW_OP_stack_value``).452 453A ``#dbg_declare`` record describes an indirect value (the address) of a source454variable. The first operand of the record must be an address of some kind. A455``DIExpression`` operand to the record refines this address to produce a456concrete location for the source variable.457 458A ``#dbg_value`` record describes the direct value of a source variable. The459first operand of the record may be a direct or indirect value. A460``DIExpression`` operand to the record refines the first operand to produce a461direct value. For example, if the first operand is an indirect value, it may be462necessary to insert ``DW_OP_deref`` into the ``DIExpression`` in order to463produce a valid debug record.464 465.. note::466 467   A ``DIExpression`` is interpreted in the same way regardless of which kind468   of debug record it's attached to.469 470   ``DIExpression``\s are always printed and parsed inline; they can never be471   referenced by an ID (e.g. ``!1``).472 473.. _dwarf-opcodes:474 475DWARF Opcodes476^^^^^^^^^^^^^477 478When possible LLVM reuses DWARF opcodes and gives them identical semantics in479LLVM expressions as in DWARF expressions. The current supported opcode480vocabulary is limited, but includes at least:481 482- ``DW_OP_deref`` dereferences the top of the expression stack.483- ``DW_OP_plus`` pops the last two entries from the expression stack, adds484  them together and pushes the result to the expression stack.485- ``DW_OP_minus`` pops the last two entries from the expression stack, subtracts486  the last entry from the second last entry and appends the result to the487  expression stack.488- ``DW_OP_plus_uconst, 93`` adds ``93`` to the value on top of the stack.489- ``DW_OP_swap`` swaps top two stack entries.490- ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top491  of the stack is treated as an address. The second stack entry is treated as an492  address space identifier. The two entries are popped and then an493  implementation defined value is pushed on the stack.494- ``DW_OP_stack_value`` may appear at most once in an expression, and must be495  the last opcode if ``DW_OP_LLVM_fragment`` is not present, or the second last496  opcode if ``DW_OP_LLVM_fragment`` is present. It pops the top value of the497  expression stack and makes an implicit value location with that value.498- ``DW_OP_breg`` (or ``DW_OP_bregx``) represents a content on the provided499  signed offset of the specified register. The opcode is only generated by the500  ``AsmPrinter`` pass to describe call site parameter value which requires an501  expression over two registers.502- ``DW_OP_push_object_address`` pushes the address of the object which can then503  serve as a descriptor in subsequent calculation. This opcode can be used to504  calculate bounds of a Fortran allocatable array which has array descriptors.505- ``DW_OP_over`` duplicates the entry currently second in the stack at the top506  of the stack. This opcode can be used to calculate bounds of a Fortran507  assumed rank array which has rank known at run time and current dimension508  number is implicitly first element of the stack.509 510.. _internal-opcodes:511 512Internal Opcodes513^^^^^^^^^^^^^^^^514 515Where the DWARF equivalent is not suitable, or no DWARF equivalent exists, LLVM516defines internal-only opcodes which have no direct analog in DWARF.517 518.. note::519 520   Some opcodes do not influence the final DWARF expression directly, instead521   encoding information logically belonging to the debug records which use522   them.523 524- ``DW_OP_LLVM_fragment, <offset>, <size>`` may appear at most once in an525  expression, and must be the last opcode. It specifies the bit offset and bit526  size of the variable fragment being described by the record or intrinsic527  using the expression. Note that contrary to ``DW_OP_bit_piece``, the offset528  is describing the location within the described source variable. At DWARF529  generation time all fragments for the same variable are collected together530  and DWARF ``DW_OP_piece`` and ``DW_OP_bit_piece`` opcodes are used to531  describe a composite with pieces corresponding to the fragments. (This does532  not affect the semantics of the expression containing it.) -533  ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding534  (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the535  expression stack is to be converted. Maps into a ``DW_OP_convert`` operation536  that references a base type constructed from the supplied values. -537  ``DW_OP_LLVM_tag_offset, tag_offset`` specifies that a memory tag should be538  optionally applied to the pointer. The memory tag is derived from the given539  tag offset in an implementation-defined manner. (This does not affect the540  semantics of the expression containing it.) - ``DW_OP_LLVM_entry_value, N``541  evaluates a sub-expression as-if it were evaluated upon entry to the current542  call frame.543 544  The sub-expression replaces the operations which comprise it, i.e. all such545  operations are evaluated only in the frame entry context.546 547  The sub-expression begins with the operation which immediately precedes548  ``DW_OP_LLVM_entry_value, N`` in the ``DIExpression``. If no such operation549  exists (i.e. the expression begins with ``DW_OP_LLVM_entry_value, N``), the550  implicit operation which pushes the first debug argument of the containing551  marker/pseudo is used instead. The value ``N`` must always be at least ``1``,552  as this first operation cannot be omitted and is counted in ``N``.553 554  The rest of the sub-expression comprises the ``(N - 1)`` operations following555  ``DW_OP_LLVM_entry_value, N`` in the ``DIExpression``.556 557  Due to framework limitations:558 559    - ``N`` must not be greater than ``1``. In other words, ``N`` must equal560      ``1``, and the sub-expression comprises only the operation immediately561      preceding ``DW_OP_LLVM_entry_value, N``.562    - ``DW_OP_LLVM_entry_value, N`` must be either the first operation of a563      ``DIExpression`` or the second operation if the expression begins with564      ``DW_OP_LLVM_arg, 0``.565    - The first operation must refer to a register value.566 567  Taken together, these limitations mean that ``DW_OP_LLVM_entry_value`` can568  only currently be used to push the value a single register had on entry to569  the current stack frame.570 571  For example, ``!DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_entry_value, 1,572  DW_OP_LLVM_arg, 1, DW_OP_plus, DW_OP_stack_value)`` specifies an expression573  where the entry value of the first argument to the ``DIExpression`` is added574  to the non-entry value of the second argument, and the result is used as the575  value for an implicit value location.576 577  When targeting DWARF, a ``DBG_VALUE(reg, ...,578  DIExpression(DW_OP_LLVM_entry_value, 1, ...)`` is lowered to579  ``DW_OP_entry_value [reg], ...``, which pushes the value ``reg`` had upon580  frame entry onto the DWARF expression stack.581 582  Because ``DW_OP_LLVM_entry_value`` is currently limited to registers, it is583  usually used in MIR, but it is also allowed in LLVM IR when targeting a584  :ref:`swiftasync <swiftasync>` argument. The operation is introduced by:585 586    - ``LiveDebugValues`` pass, which applies it to function parameters that587      are unmodified throughout the function. Support is limited to simple588      register location descriptions, or as indirect locations (e.g.,589      parameters passed-by-value to a callee via a pointer to a temporary copy590      made in the caller).591    - ``AsmPrinter`` pass when a call site parameter value592      (``DW_AT_call_site_parameter_value``) is represented as entry value of593      the parameter.594    - ``CoroSplit`` pass, which may move variables from ``alloca``\s into a595      coroutine frame. If the coroutine frame is a596      :ref:`swiftasync <swiftasync>` argument, the variable is described with597      an ``DW_OP_LLVM_entry_value`` operation.598 599- ``DW_OP_LLVM_implicit_pointer`` It specifies the dereferenced value. It can600  be used to represent pointer variables which are optimized out but the value601  it points to is known. This operator is required as it is different than602  DWARF operator ``DW_OP_implicit_pointer`` in representation and specification603  (number and types of operands) and later can not be used as multiple level.604 605  Examples using ``DW_OP_LLVM_implicit_pointer``:606 607  .. code-block:: text608 609      IR for "*ptr = 4;"610      --------------611        #dbg_value(i32 4, !17, !DIExpression(DW_OP_LLVM_implicit_pointer), !20)612      !17 = !DILocalVariable(name: "ptr", scope: !12, file: !3, line: 5,613                             type: !18)614      !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64)615      !19 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)616      !20 = !DILocation(line: 10, scope: !12)617 618      IR for "**ptr = 4;"619      --------------620        #dbg_value(i32 4, !17,621          !DIExpression(DW_OP_LLVM_implicit_pointer, DW_OP_LLVM_implicit_pointer),622          !21)623      !17 = !DILocalVariable(name: "ptr", scope: !12, file: !3, line: 5,624                             type: !18)625      !18 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !19, size: 64)626      !19 = !DIDerivedType(tag: DW_TAG_pointer_type, baseType: !20, size: 64)627      !20 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)628      !21 = !DILocation(line: 10, scope: !12)629 630- ``DW_OP_LLVM_arg, N`` is used in debug intrinsics that refer to more than one631  value, such as one that calculates the sum of two registers. This is always632  used in combination with an ordered list of values, such that633  ``DW_OP_LLVM_arg, N`` refers to the ``N``\ :sup:`th` element in that list.634  For example, ``!DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1,635  DW_OP_minus, DW_OP_stack_value)`` used with the list ``(%reg1, %reg2)`` would636  evaluate to an implicit value location that has the value of637  ``%reg1 - reg2``. This list of values should be provided by the containing638  intrinsic/instruction.639- ``DW_OP_LLVM_extract_bits_sext, 16, 8,`` specifies the offset and size640  (``16`` and ``8`` here, respectively) of bits that are to be extracted and641  sign-extended from the value at the top of the expression stack. If the top of642  the expression stack is a memory location then these bits are extracted from643  the value pointed to by that memory location. Maps into a ``DW_OP_shl``644  followed by ``DW_OP_shra``.645- ``DW_OP_LLVM_extract_bits_zext`` behaves similarly to646  ``DW_OP_LLVM_extract_bits_sext``, but zero-extends instead of sign-extending.647  Maps into a ``DW_OP_shl`` followed by ``DW_OP_shr``.648 649Object lifetimes and scoping650============================651 652In many languages, the local variables in functions can have their lifetimes or653scopes limited to a subset of a function.  In the C family of languages, for654example, variables are only live (readable and writable) within the source655block that they are defined in.  In functional languages, values are only656readable after they have been defined.  Though this is a very obvious concept,657it is non-trivial to model in LLVM, because it has no notion of scoping in this658sense, and does not want to be tied to a language's scoping rules.659 660In order to handle this, the LLVM debug format uses the metadata attached to661LLVM instructions to encode line number and scoping information.  Consider the662following C fragment, for example:663 664.. code-block:: c665 666  1.  void foo() {667  2.    int X = 21;668  3.    int Y = 22;669  4.    {670  5.      int Z = 23;671  6.      Z = X;672  7.    }673  8.    X = Y;674  9.  }675 676Compiled to LLVM, this function would be represented like this:677 678.. code-block:: text679 680  ; Function Attrs: nounwind ssp uwtable681  define void @foo() #0 !dbg !4 {682  entry:683    %X = alloca i32, align 4684    %Y = alloca i32, align 4685    %Z = alloca i32, align 4686      #dbg_declare(ptr %X, !11, !DIExpression(), !13)687    store i32 21, i32* %X, align 4, !dbg !13688      #dbg_declare(ptr %Y, !14, !DIExpression(), !15)689    store i32 22, i32* %Y, align 4, !dbg !15690      #dbg_declare(ptr %Z, !16, !DIExpression(), !18)691    store i32 23, i32* %Z, align 4, !dbg !18692    %0 = load i32, i32* %X, align 4, !dbg !20693    store i32 %0, i32* %Z, align 4, !dbg !21694    %1 = load i32, i32* %Y, align 4, !dbg !22695    store i32 %1, i32* %X, align 4, !dbg !23696    ret void, !dbg !24697  }698 699  attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false" "frame-pointer"="all" "no-infs-fp-math"="false" "no-nans-fp-math"="false" "stack-protector-buffer-size"="8" "use-soft-float"="false" }700  attributes #1 = { nounwind readnone }701 702  !llvm.dbg.cu = !{!0}703  !llvm.module.flags = !{!7, !8, !9}704  !llvm.ident = !{!10}705 706  !0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)", isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug, enums: !2, retainedTypes: !2, subprograms: !3, globals: !2, imports: !2)707  !1 = !DIFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info")708  !2 = !{}709  !3 = !{!4}710  !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, retainedNodes: !2)711  !5 = !DISubroutineType(types: !6)712  !6 = !{null}713  !7 = !{i32 2, !"Dwarf Version", i32 2}714  !8 = !{i32 2, !"Debug Info Version", i32 3}715  !9 = !{i32 1, !"PIC Level", i32 2}716  !10 = !{!"clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)"}717  !11 = !DILocalVariable(name: "X", scope: !4, file: !1, line: 2, type: !12)718  !12 = !DIBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)719  !13 = !DILocation(line: 2, column: 9, scope: !4)720  !14 = !DILocalVariable(name: "Y", scope: !4, file: !1, line: 3, type: !12)721  !15 = !DILocation(line: 3, column: 9, scope: !4)722  !16 = !DILocalVariable(name: "Z", scope: !18, file: !1, line: 5, type: !12)723  !17 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)724  !18 = !DILocation(line: 5, column: 11, scope: !17)725  !29 = !DILocation(line: 6, column: 11, scope: !17)726  !20 = !DILocation(line: 6, column: 9, scope: !17)727  !21 = !DILocation(line: 8, column: 9, scope: !4)728  !22 = !DILocation(line: 8, column: 7, scope: !4)729  !23 = !DILocation(line: 9, column: 3, scope: !4)730 731 732This example illustrates a few important details about LLVM debugging733information.  In particular, it shows how the ``#dbg_declare`` record and734location information, which are attached to an instruction, are applied735together to allow a debugger to analyze the relationship between statements,736variable definitions, and the code used to implement the function.737 738.. code-block:: llvm739 740    #dbg_declare(ptr %X, !11, !DIExpression(), !13)741    ; [debug line = 2:9] [debug variable = X]742 743The first record ``#dbg_declare`` encodes debugging information for the744variable ``X``.  The location ``!13`` at the end of the record provides745scope information for the variable ``X``.746 747.. code-block:: text748 749  !13 = !DILocation(line: 2, column: 9, scope: !4)750  !4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,751                              isLocal: false, isDefinition: true, scopeLine: 1,752                              isOptimized: false, retainedNodes: !2)753 754Here ``!13`` is metadata providing :ref:`location information <dilocation>`.755In this example, scope is encoded by ``!4``, a :ref:`subprogram descriptor756<disubprogram>`.  This way the location information parameter to the records757indicates that the variable ``X`` is declared at line number 2 at a function758level scope in function ``foo``.759 760Now, let's take another example.761 762.. code-block:: llvm763 764    #dbg_declare(ptr %Z, !16, !DIExpression(), !18)765    ; [debug line = 5:11] [debug variable = Z]766 767The third record ``#dbg_declare`` encodes debugging information for768variable ``Z``.  The metadata ``!18`` at the end of the record provides769scope information for the variable ``Z``.770 771.. code-block:: text772 773  !17 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)774  !18 = !DILocation(line: 5, column: 11, scope: !17)775 776Here ``!18`` indicates that ``Z`` is declared at line number 5 and column777number 11 inside of lexical scope ``!17``.  The lexical scope itself resides778inside of subprogram ``!4`` described above.779 780The scope information attached to each instruction provides a straightforward781way to find instructions covered by a scope.782 783Object lifetime in optimized code784=================================785 786In the example above, every variable assignment uniquely corresponds to a787memory store to the variable's position on the stack. However, in heavily788optimized code LLVM promotes most variables into SSA values, which can789eventually be placed in physical registers or memory locations. To track SSA790values through compilation, when objects are promoted to SSA values a791``#dbg_value`` record is created for each assignment, recording the792variable's new location. Compared with the ``#dbg_declare`` record:793 794* A ``#dbg_value`` terminates the effects that any preceding records have on795  any common bits of a common variable.796 797  .. note::798 799    The current implementation generally terminates the effect of every800    record in its entirety if any of its effects would be terminated, rather801    than carrying forward the effect of previous records for non-overlapping802    bits as it would be permitted to do by this definition. This is allowed803    just as dropping any debug information at any point in the compilation is804    allowed.805 806    One exception to this is :doc:`AssignmentTracking` where certain807    memory-based locations are carried forward partially in some situations.808 809* The ``#dbg_value``'s position in the IR defines where in the instruction810  stream the variable's value changes.811* Operands can be constants, indicating the variable is assigned a812  constant value.813 814Care must be taken to update ``#dbg_value`` records when optimization815passes alter or move instructions and blocks -- the developer could observe such816changes reflected in the value of variables when debugging the program. For any817execution of the optimized program, the set of variable values presented to the818developer by the debugger should not show a state that would never have existed819in the execution of the unoptimized program, given the same input. Doing so820risks misleading the developer by reporting a state that does not exist,821damaging their understanding of the optimized program and undermining their822trust in the debugger.823 824Sometimes perfectly preserving variable locations is not possible, often when a825redundant calculation is optimized out. In such cases, a ``#dbg_value``826with operand ``poison`` should be used, to terminate earlier variable locations827and let the debugger present ``optimized out`` to the developer. Withholding828these potentially stale variable values from the developer diminishes the829amount of available debug information, but increases the reliability of the830remaining information.831 832To illustrate some potential issues, consider the following example:833 834.. code-block:: llvm835 836  define i32 @foo(i32 %bar, i1 %cond) {837  entry:838      #dbg_value(i32 0, !1, !DIExpression(), !4)839    br i1 %cond, label %truebr, label %falsebr840  truebr:841    %tval = add i32 %bar, 1842      #dbg_value(i32 %tval, !1, !DIExpression(), !4)843    %g1 = call i32 @gazonk()844    br label %exit845  falsebr:846    %fval = add i32 %bar, 2847      #dbg_value(i32 %fval, !1, !DIExpression(), !4)848    %g2 = call i32 @gazonk()849    br label %exit850  exit:851    %merge = phi [ %tval, %truebr ], [ %fval, %falsebr ]852    %g = phi [ %g1, %truebr ], [ %g2, %falsebr ]853      #dbg_value(i32 %merge, !1, !DIExpression(), !4)854      #dbg_value(i32 %g, !3, !DIExpression(), !4)855    %plusten = add i32 %merge, 10856    %toret = add i32 %plusten, %g857      #dbg_value(i32 %toret, !1, !DIExpression(), !4)858    ret i32 %toret859  }860 861Containing two source-level variables in ``!1`` and ``!3``. The function could,862perhaps, be optimized into the following code:863 864.. code-block:: llvm865 866  define i32 @foo(i32 %bar, i1 %cond) {867  entry:868    %g = call i32 @gazonk()869    %addoper = select i1 %cond, i32 11, i32 12870    %plusten = add i32 %bar, %addoper871    %toret = add i32 %plusten, %g872    ret i32 %toret873  }874 875What ``#dbg_value`` records should be placed to represent the original variable876locations in this code? Unfortunately the second, third, and fourth877``#dbg_value``\s for ``!1`` in the source function have had their operands878(``%tval``, ``%fval``, ``%merge``) optimized out. Assuming we cannot recover879them, we might consider this placement of ``#dbg_value``\s:880 881.. code-block:: llvm882 883  define i32 @foo(i32 %bar, i1 %cond) {884  entry:885      #dbg_value(i32 0, !1, !DIExpression(), !4)886    %g = call i32 @gazonk()887      #dbg_value(i32 %g, !3, !DIExpression(), !4)888    %addoper = select i1 %cond, i32 11, i32 12889    %plusten = add i32 %bar, %addoper890    %toret = add i32 %plusten, %g891      #dbg_value(i32 %toret, !1, !DIExpression(), !4)892    ret i32 %toret893  }894 895However, this will cause ``!3`` to have the return value of ``@gazonk()`` at896the same time as ``!1`` has the constant value zero -- a pair of assignments897that never occurred in the unoptimized program. To avoid this, we must terminate898the range that ``!1`` has the constant value assignment by inserting an poison899``#dbg_value`` before the ``#dbg_value`` for ``!3``:900 901.. code-block:: llvm902 903  define i32 @foo(i32 %bar, i1 %cond) {904  entry:905      #dbg_value(i32 0, !1, !DIExpression(), !2)906    %g = call i32 @gazonk()907      #dbg_value(i32 poison, !1, !DIExpression(), !2)908      #dbg_value(i32 %g, !3, !DIExpression(), !2)909    %addoper = select i1 %cond, i32 11, i32 12910    %plusten = add i32 %bar, %addoper911    %toret = add i32 %plusten, %g912      #dbg_value(i32 %toret, !1, !DIExpression(), !2)913    ret i32 %toret914  }915 916There are a few other ``#dbg_value`` configurations that mean it terminates917dominating location definitions without adding a new location. The complete918list is:919 920* Any location operand is ``poison`` (or ``undef``).921* Any location operand is an empty metadata tuple (``!{}``) (which cannot922  occur in a ``!DIArgList``).923* There are no location operands (empty ``DIArgList``) and the ``DIExpression``924  is empty.925 926This class of ``#dbg_value`` that kills variable locations is called a "kill927``#dbg_value``" or "kill location", and for legacy reasons the term "``undef928#dbg_value``" may be used in existing code. The ``DbgVariableIntrinsic``929methods ``isKillLocation`` and ``setKillLocation`` should be used where930possible rather than inspecting location operands directly to check or set931whether a ``#dbg_value`` is a kill location.932 933In general, if any ``#dbg_value`` has its operand optimized out and cannot be934recovered, then a kill ``#dbg_value`` is necessary to terminate earlier935variable locations. Additional kill ``#dbg_values`` may be necessary when the936debugger can observe re-ordering of assignments.937 938How variable location metadata is transformed during CodeGen939============================================================940 941LLVM preserves debug information throughout mid-level and backend passes,942ultimately producing a mapping between source-level information and943instruction ranges. This944is relatively straightforward for line number information, as mapping945instructions to line numbers is a simple association. For variable locations946however the story is more complex. As each ``#dbg_value`` record947represents a source-level assignment of a value to a source variable, the948debug records effectively embed a small imperative program949within the LLVM IR. By the end of CodeGen, this becomes a mapping from each950variable to their machine locations over ranges of instructions.951From IR to object emission, the major transformations which affect variable952location fidelity are:953 9541. Instruction Selection9552. Register allocation9563. Block layout957 958each of which is discussed below. In addition, instruction scheduling can959significantly change the ordering of the program, and occurs in a number of960different passes.961 962Some variable locations are not transformed during CodeGen. Stack locations963specified by ``#dbg_declare`` are valid and unchanging for the entire duration964of the function, and are recorded in a simple ``MachineFunction`` table.965Location changes in the prologue and epilogue of a function are also ignored:966frame setup and destruction may take several instructions, require a967disproportionate amount of debugging information in the output binary to968describe, and should be stepped over by debuggers anyway.969 970Variable locations in Instruction Selection and MIR971---------------------------------------------------972 973Instruction selection creates a MIR function from an IR function, and just as974it transforms ``intermediate`` instructions into machine instructions, so must975``intermediate`` variable locations become machine variable locations. Within976IR, variable locations are always identified by a Value, but in MIR there can977be different types of variable locations. In addition, some IR locations become978unavailable, for example if the operation of multiple IR instructions are979combined into one machine instruction (such as multiply-and-accumulate) then980intermediate Values are lost. To track variable locations through instruction981selection, they are first separated into locations that do not depend on code982generation (constants, stack locations, allocated virtual registers) and those983that do. For those that do, debug metadata is attached to ``SDNode``\s in984``SelectionDAG``\s. After instruction selection has occurred and a MIR function985is created, if the ``SDNode`` associated with debug metadata is allocated a986virtual register, that virtual register is used as the variable location. If987the ``SDNode`` is folded into a machine instruction or otherwise transformed988into a non-register, the variable location becomes unavailable.989 990Locations that are unavailable are treated as if they have been optimized out:991in IR the location would be assigned ``undef`` by a debug record, and in MIR992the equivalent location is used.993 994After MIR locations are assigned to each variable, machine pseudo-instructions995corresponding to each ``#dbg_value`` record are inserted. There are two996forms of this type of instruction.997 998The first form, ``DBG_VALUE``, appears thus:999 1000.. code-block:: text1001 1002  DBG_VALUE %1, $noreg, !123, !DIExpression()1003 1004And has the following operands:1005 * The first operand can record the variable location as a register,1006   a frame index, an immediate, or the base address register if the original1007   debug record referred to memory. ``$noreg`` indicates the variable1008   location is undefined, equivalent to an ``undef #dbg_value`` operand.1009 * The type of the second operand indicates whether the variable location is1010   directly referred to by the ``DBG_VALUE``, or whether it is indirect. The1011   ``$noreg`` register signifies the former, an immediate operand (0) the1012   latter.1013 * Operand 3 is the Variable field of the original debug record.1014 * Operand 4 is the Expression field of the original debug record.1015 1016The second form, ``DBG_VALUE_LIST``, appears thus:1017 1018.. code-block:: text1019 1020  DBG_VALUE_LIST !123, !DIExpression(DW_OP_LLVM_arg, 0, DW_OP_LLVM_arg, 1, DW_OP_plus), %1, %21021 1022And has the following operands:1023 * The first operand is the Variable field of the original debug record.1024 * The second operand is the Expression field of the original debug record.1025 * Any number of operands, from the 3rd onwards, record a sequence of variable1026   location operands, which may take any of the same values as the first1027   operand of the ``DBG_VALUE`` instruction above. These variable location1028   operands are inserted into the final DWARF Expression in positions indicated1029   by the ``DW_OP_LLVM_arg`` operator in the :ref:`diexpression`.1030 1031The position at which the ``DBG_VALUE``\s are inserted should correspond to the1032positions of their matching ``#dbg_value`` records in the IR block.  As with1033optimization, LLVM aims to preserve the order in which variable assignments1034occurred in the source program. However, ``SelectionDAG`` performs some1035instruction scheduling, which can reorder assignments (discussed below).1036Function parameter locations are moved to the beginning of the function if1037they're not already, to ensure they're immediately available on function entry.1038 1039To demonstrate variable locations during instruction selection, consider1040the following example:1041 1042.. code-block:: llvm1043 1044  define i32 @foo(i32* %addr) {1045  entry:1046      #dbg_value(i32 0, !3, !DIExpression(), !5)1047    br label %bb1, !dbg !51048 1049  bb1:                                              ; preds = %bb1, %entry1050    %bar.0 = phi i32 [ 0, %entry ], [ %add, %bb1 ]1051      #dbg_value(i32 %bar.0, !3, !DIExpression(), !5)1052    %addr1 = getelementptr i32, i32 *%addr, i32 1, !dbg !51053      #dbg_value(i32 *%addr1, !3, !DIExpression(), !5)1054    %loaded1 = load i32, i32* %addr1, !dbg !51055    %addr2 = getelementptr i32, i32 *%addr, i32 %bar.0, !dbg !51056      #dbg_value(i32 *%addr2, !3, !DIExpression(), !5)1057    %loaded2 = load i32, i32* %addr2, !dbg !51058    %add = add i32 %bar.0, 1, !dbg !51059      #dbg_value(i32 %add, !3, !DIExpression(), !5)1060    %added = add i32 %loaded1, %loaded21061    %cond = icmp ult i32 %added, %bar.0, !dbg !51062    br i1 %cond, label %bb1, label %bb2, !dbg !51063 1064  bb2:                                              ; preds = %bb11065    ret i32 0, !dbg !51066  }1067 1068If one compiles this IR with ``llc -o - -start-after=codegen-prepare -stop-after=expand-isel-pseudos -mtriple=x86_64--``, the following MIR is produced:1069 1070.. code-block:: text1071 1072  bb.0.entry:1073    successors: %bb.1(0x80000000)1074    liveins: $rdi1075 1076    %2:gr64 = COPY $rdi1077    %3:gr32 = MOV32r0 implicit-def dead $eflags1078    DBG_VALUE 0, $noreg, !3, !DIExpression(), debug-location !51079 1080  bb.1.bb1:1081    successors: %bb.1(0x7c000000), %bb.2(0x04000000)1082 1083    %0:gr32 = PHI %3, %bb.0, %1, %bb.11084    DBG_VALUE %0, $noreg, !3, !DIExpression(), debug-location !51085    DBG_VALUE %2, $noreg, !3, !DIExpression(DW_OP_plus_uconst, 4, DW_OP_stack_value), debug-location !51086    %4:gr32 = MOV32rm %2, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)1087    %5:gr64_nosp = MOVSX64rr32 %0, debug-location !51088    DBG_VALUE $noreg, $noreg, !3, !DIExpression(), debug-location !51089    %1:gr32 = INC32r %0, implicit-def dead $eflags, debug-location !51090    DBG_VALUE %1, $noreg, !3, !DIExpression(), debug-location !51091    %6:gr32 = ADD32rm %4, %2, 4, killed %5, 0, $noreg, implicit-def dead $eflags :: (load 4 from %ir.addr2)1092    %7:gr32 = SUB32rr %6, %0, implicit-def $eflags, debug-location !51093    JB_1 %bb.1, implicit $eflags, debug-location !51094    JMP_1 %bb.2, debug-location !51095 1096  bb.2.bb2:1097    %8:gr32 = MOV32r0 implicit-def dead $eflags1098    $eax = COPY %8, debug-location !51099    RET 0, $eax, debug-location !51100 1101Observe first that there is a ``DBG_VALUE`` instruction for every ``#dbg_value``1102record in the source IR, ensuring no source level assignments go missing.1103Then consider the different ways in which variable locations have been recorded:1104 1105* For the first ``#dbg_value`` an immediate operand is used to record a zero value.1106* The ``#dbg_value`` of the PHI instruction leads to a ``DBG_VALUE`` of virtual register1107  ``%0``.1108* The first GEP has its effect folded into the first load instruction1109  (as a 4-byte offset), but the variable location is salvaged by folding1110  the GEPs effect into the ``DIExpression``.1111* The second GEP is also folded into the corresponding load. However, it is1112  insufficiently simple to be salvaged, and is emitted as a ``$noreg``1113  ``DBG_VALUE``, indicating that the variable takes on an undefined location.1114* The final ``#dbg_value`` has its Value placed in virtual register ``%1``.1115 1116Instruction Scheduling1117----------------------1118 1119A number of passes can reschedule instructions, notably instruction selection1120and the pre-and-post RA machine schedulers. Instruction scheduling can1121significantly change the nature of the program -- in the (very unlikely) worst1122case the instruction sequence could be completely reversed. In such1123circumstances LLVM follows the principle applied to optimizations, that it is1124better for the debugger not to display any state than a misleading state.1125Thus, whenever instructions are advanced in order of execution, any1126corresponding ``DBG_VALUE`` is kept in its original position, and if an instruction1127is delayed then the variable is given an undefined location for the duration1128of the delay. To illustrate, consider this pseudo-MIR:1129 1130.. code-block:: text1131 1132  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)1133  DBG_VALUE %1, $noreg, !1, !21134  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags1135  DBG_VALUE %4, $noreg, !3, !41136  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags1137  DBG_VALUE %7, $noreg, !5, !61138 1139Imagine that the ``SUB32rr`` were moved forward to give us the following MIR:1140 1141.. code-block:: text1142 1143  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags1144  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)1145  DBG_VALUE %1, $noreg, !1, !21146  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags1147  DBG_VALUE %4, $noreg, !3, !41148  DBG_VALUE %7, $noreg, !5, !61149 1150In this circumstance LLVM would leave the MIR as shown above. Were we to move1151the ``DBG_VALUE`` of virtual register %7 upwards with the ``SUB32rr``, we would re-order1152assignments and introduce a new state of the program. Whereas with the solution1153above, the debugger will see one fewer combination of variable values, because1154``!3`` and ``!5`` will change value at the same time. This is preferred over1155misrepresenting the original program.1156 1157In comparison, if one sunk the ``MOV32rm``, LLVM would produce the following:1158 1159.. code-block:: text1160 1161  DBG_VALUE $noreg, $noreg, !1, !21162  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags1163  DBG_VALUE %4, $noreg, !3, !41164  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags1165  DBG_VALUE %7, $noreg, !5, !61166  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)1167  DBG_VALUE %1, $noreg, !1, !21168 1169Here, to avoid presenting a state in which the first assignment to ``!1``1170disappears, the ``DBG_VALUE`` at the top of the block assigns the variable the1171undefined location, until its value is available at the end of the block where1172an additional ``DBG_VALUE`` is added. Were any other ``DBG_VALUE`` for ``!1`` to occur1173in the instructions that the ``MOV32rm`` was sunk past, the ``DBG_VALUE`` for ``%1``1174would be dropped and the debugger would never observe it in the variable. This1175accurately reflects that the value is not available during the corresponding1176portion of the original program.1177 1178Variable locations during Register Allocation1179---------------------------------------------1180 1181To avoid debug instructions interfering with the register allocator, the1182``LiveDebugVariables`` pass extracts variable locations from a MIR function and1183deletes the corresponding ``DBG_VALUE`` instructions. Some localized copy1184propagation is performed within blocks. After register allocation, the1185``VirtRegRewriter`` pass re-inserts ``DBG_VALUE`` instructions in their1186original positions, translating virtual register references into their physical1187machine locations. To avoid encoding incorrect variable locations, in this pass1188any ``DBG_VALUE`` of a virtual register that is not live, is replaced by the1189undefined location. The ``LiveDebugVariables`` may insert redundant1190``DBG_VALUE``\s because of virtual register rewriting. These will be1191subsequently removed by the ``RemoveRedundantDebugValues`` pass.1192 1193``LiveDebugValues`` expansion of variable locations1194---------------------------------------------------1195 1196After all optimizations have run and shortly before emission, the1197``LiveDebugValue``\s pass runs to achieve two aims:1198 1199* To propagate the location of variables through copies and register spills,1200* For every block, to record every valid variable location in that block.1201 1202After this pass the ``DBG_VALUE`` instruction changes meaning: rather than1203corresponding to a source-level assignment where the variable may change value,1204it asserts the location of a variable in a block, and loses effect outside the1205block. Propagating variable locations through copies and spills is1206straightforward: determining the variable location in every basic block1207requires the consideration of control flow. Consider the following IR, which1208presents several difficulties:1209 1210.. code-block:: text1211 1212  define dso_local i32 @foo(i1 %cond, i32 %input) !dbg !12 {1213  entry:1214    br i1 %cond, label %truebr, label %falsebr1215 1216  bb1:1217    %value = phi i32 [ %value1, %truebr ], [ %value2, %falsebr ]1218    br label %exit, !dbg !261219 1220  truebr:1221      #dbg_value(i32 %input, !30, !DIExpression(), !24)1222      #dbg_value(i32 1, !23, !DIExpression(), !24)1223    %value1 = add i32 %input, 11224    br label %bb11225 1226  falsebr:1227      #dbg_value(i32 %input, !30, !DIExpression(), !24)1228      #dbg_value(i32 2, !23, !DIExpression(), !24)1229    %value2 = add i32 %input, 21230    br label %bb11231 1232  exit:1233    ret i32 %value, !dbg !301234  }1235 1236Here the difficulties are:1237 1238* The control flow is roughly the opposite of basic block order1239* The value of the ``!23`` variable merges into ``%bb1``, but there is no PHI1240  node1241 1242As mentioned above, the ``#dbg_value`` records essentially form an1243imperative program embedded in the IR, with each record defining a variable1244location. This *could* be converted to an SSA form by ``mem2reg``, in the same way1245that it uses use-def chains to identify control flow merges and insert phi1246nodes for IR Values. However, because debug variable locations are defined for1247every machine instruction, in effect every IR instruction uses every variable1248location, which would lead to a large number of debugging records being1249generated.1250 1251Examining the example above, variable ``!30`` is assigned ``%input`` on both1252conditional paths through the function, while ``!23`` is assigned differing1253constant values on either path. Where control flow merges in ``%bb1`` we would1254want ``!30`` to keep its location (``%input``), but ``!23`` to become undefined1255as we cannot determine at runtime what value it should have in ``%bb1`` without1256inserting a PHI node. ``mem2reg`` does not insert the PHI node to avoid changing1257CodeGen when debugging is enabled, and does not insert the other ``#dbg_values``1258to avoid adding very large numbers of records.1259 1260Instead, ``LiveDebugValue``\s determines variable locations when control1261flow merges. A dataflow analysis is used to propagate locations between blocks:1262when control flow merges, if a variable has the same location in all1263predecessors then that location is propagated into the successor. If the1264predecessor locations disagree, the location becomes undefined.1265 1266Once ``LiveDebugValue``\s has run, every block should have all valid variable1267locations described by ``DBG_VALUE`` instructions within the block. Very little1268effort is then required by supporting classes (such as1269``DbgEntityHistoryCalculator``) to build a map of each instruction to every1270valid variable location, without the need to consider control flow. From1271the example above, it is otherwise difficult to determine that the location1272of variable ``!30`` should flow "up" into block ``%bb1``, but that the location1273of variable ``!23`` should not flow "down" into the ``%exit`` block.1274 1275.. _ccxx_frontend:1276 1277C/C++ front-end specific debug information1278==========================================1279 1280The C and C++ front-ends represent information about the program in a1281format that is effectively identical to `DWARF <http://www.dwarfstd.org/>`_1282in terms of information content.  This allows code generators to1283trivially support native debuggers by generating standard dwarf1284information, and contains enough information for non-dwarf targets to1285translate it as needed.1286 1287This section describes the forms used to represent C and C++ programs.  Other1288languages could pattern themselves after this (which itself is tuned to1289representing programs in the same way that DWARF does), or they could choose1290to provide completely different forms if they don't fit into the DWARF model.1291As support for debugging information gets added to the various LLVM1292source-language front-ends, the information used should be documented here.1293 1294The following sections provide examples of a few C/C++ constructs and1295the debug information that would best describe those constructs.  The1296canonical references are the ``DINode`` classes defined in1297``include/llvm/IR/DebugInfoMetadata.h`` and the implementations of the1298helper functions in ``lib/IR/DIBuilder.cpp``.1299 1300C/C++ source file information1301-----------------------------1302 1303``llvm::Instruction`` provides easy access to metadata attached to an1304instruction.  One can extract line number information encoded in LLVM IR using1305``Instruction::getDebugLoc()`` and ``DILocation::getLine()``.1306 1307.. code-block:: c++1308 1309  if (DILocation *Loc = I->getDebugLoc()) { // Here I is an LLVM instruction1310    unsigned Line = Loc->getLine();1311    StringRef File = Loc->getFilename();1312    StringRef Dir = Loc->getDirectory();1313    bool ImplicitCode = Loc->isImplicitCode();1314  }1315 1316When the flag ``ImplicitCode`` is true then it means that the Instruction has been1317added by the front-end but doesn't correspond to source code written by the user. For example1318 1319.. code-block:: c++1320 1321  if (MyBoolean) {1322    MyObject MO;1323    ...1324  }1325 1326At the end of the scope the ``MyObject``'s destructor is called but it isn't written1327explicitly. This information is useful to avoid having counters on brackets when1328making code coverage.1329 1330C/C++ global variable information1331---------------------------------1332 1333Given an integer global variable declared as follows:1334 1335.. code-block:: c1336 1337  _Alignas(8) int MyGlobal = 100;1338 1339a C/C++ front-end would generate the following descriptors:1340 1341.. code-block:: text1342 1343  ;;1344  ;; Define the global itself.1345  ;;1346  @MyGlobal = global i32 100, align 8, !dbg !01347 1348  ;;1349  ;; List of debug info of globals1350  ;;1351  !llvm.dbg.cu = !{!1}1352 1353  ;; Some unrelated metadata.1354  !llvm.module.flags = !{!6, !7}1355  !llvm.ident = !{!8}1356 1357  ;; Define the global variable itself1358  !0 = distinct !DIGlobalVariable(name: "MyGlobal", scope: !1, file: !2, line: 1, type: !5, isLocal: false, isDefinition: true, align: 64)1359 1360  ;; Define the compile unit.1361  !1 = distinct !DICompileUnit(language: DW_LANG_C99, file: !2,1362                               producer: "clang version 4.0.0",1363                               isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug,1364                               enums: !3, globals: !4)1365 1366  ;;1367  ;; Define the file1368  ;;1369  !2 = !DIFile(filename: "/dev/stdin",1370               directory: "/Users/dexonsmith/data/llvm/debug-info")1371 1372  ;; An empty array.1373  !3 = !{}1374 1375  ;; The Array of Global Variables1376  !4 = !{!0}1377 1378  ;;1379  ;; Define the type1380  ;;1381  !5 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)1382 1383  ;; Dwarf version to output.1384  !6 = !{i32 2, !"Dwarf Version", i32 4}1385 1386  ;; Debug info schema version.1387  !7 = !{i32 2, !"Debug Info Version", i32 3}1388 1389  ;; Compiler identification1390  !8 = !{!"clang version 4.0.0"}1391 1392 1393The align value in ``DIGlobalVariable`` description specifies variable alignment in1394case it was forced by C11 ``_Alignas()``, C++11 ``alignas()`` keywords or compiler1395attribute ``__attribute__((aligned ()))``. In other case (when this field is missing)1396alignment is considered default. This is used when producing DWARF output1397for ``DW_AT_alignment`` value.1398 1399C/C++ function information1400--------------------------1401 1402Given a function declared as follows:1403 1404.. code-block:: c1405 1406  int main(int argc, char *argv[]) {1407    return 0;1408  }1409 1410a C/C++ front-end would generate the following descriptors:1411 1412.. code-block:: text1413 1414  ;;1415  ;; Define the anchor for subprograms.1416  ;;1417  !4 = !DISubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5,1418                     isLocal: false, isDefinition: true, scopeLine: 1,1419                     flags: DIFlagPrototyped, isOptimized: false,1420                     retainedNodes: !2)1421 1422  ;;1423  ;; Define the subprogram itself.1424  ;;1425  define i32 @main(i32 %argc, i8** %argv) !dbg !4 {1426  ...1427  }1428 1429C++ specific debug information1430==============================1431 1432C++ special member functions information1433----------------------------------------1434 1435DWARF v5 introduces attributes defined to enhance debugging information of C++ programs. LLVM can generate (or omit) these appropriate DWARF attributes. In C++ a special member function Ctors, Dtors, Copy/Move Ctors, assignment operators can be declared with C++11 keyword deleted. This is represented in LLVM using ``spFlags`` value ``DISPFlagDeleted``.1436 1437Given a class declaration with copy constructor declared as deleted:1438 1439.. code-block:: c1440 1441  class foo {1442   public:1443     foo(const foo&) = deleted;1444  };1445 1446A C++ frontend would generate the following:1447 1448.. code-block:: text1449 1450  !17 = !DISubprogram(name: "foo", scope: !11, file: !1, line: 5, type: !18, scopeLine: 5, flags: DIFlagPublic | DIFlagPrototyped, spFlags: DISPFlagDeleted)1451 1452and this will produce an additional DWARF attribute as:1453 1454.. code-block:: text1455 1456  DW_TAG_subprogram [7] *1457    DW_AT_name [DW_FORM_strx1]    (indexed (00000006) string = "foo")1458    DW_AT_decl_line [DW_FORM_data1]       (5)1459    ...1460    DW_AT_deleted [DW_FORM_flag_present]  (true)1461 1462Fortran specific debug information1463==================================1464 1465Fortran function information1466----------------------------1467 1468There are a few DWARF attributes defined to support client debugging of Fortran programs.  LLVM can generate (or omit) the appropriate DWARF attributes for the prefix-specs of ELEMENTAL, PURE, IMPURE, RECURSIVE, and NON_RECURSIVE.  This is done by using the ``spFlags`` values: ``DISPFlagElemental``, ``DISPFlagPure``, and ``DISPFlagRecursive``.1469 1470.. code-block:: fortran1471 1472  elemental function elem_func(a)1473 1474a Fortran front-end would generate the following descriptors:1475 1476.. code-block:: text1477 1478  !11 = distinct !DISubprogram(name: "subroutine2", scope: !1, file: !1,1479          line: 5, type: !8, scopeLine: 6,1480          spFlags: DISPFlagDefinition | DISPFlagElemental, unit: !0,1481          retainedNodes: !2)1482 1483and this will materialize an additional DWARF attribute as:1484 1485.. code-block:: text1486 1487  DW_TAG_subprogram [3]1488     DW_AT_low_pc [DW_FORM_addr]     (0x0000000000000010 ".text")1489     DW_AT_high_pc [DW_FORM_data4]   (0x00000001)1490     ...1491     DW_AT_elemental [DW_FORM_flag_present]  (true)1492 1493There are a few DWARF tags defined to represent Fortran specific constructs i.e ``DW_TAG_string_type`` for representing Fortran character(n). In LLVM, this is represented as ``DIStringType``.1494 1495.. code-block:: fortran1496 1497  character(len=*), intent(in) :: string1498 1499a Fortran front-end would generate the following descriptors:1500 1501.. code-block:: text1502 1503  !DILocalVariable(name: "string", arg: 1, scope: !10, file: !3, line: 4, type: !15)1504  !DIStringType(name: "character(*)!2", stringLength: !16, stringLengthExpression: !DIExpression(), size: 32)1505 1506A fortran deferred-length character can also contain the information of raw storage of the characters in addition to the length of the string. This information is encoded in the  stringLocationExpression field. Based on this information, ``DW_AT_data_location`` attribute is emitted in a ``DW_TAG_string_type`` debug info.1507 1508  !DIStringType(name: "character(*)!2", stringLengthExpression: !DIExpression(), stringLocationExpression: !DIExpression(DW_OP_push_object_address, DW_OP_deref), size: 32)1509 1510and this will materialize in DWARF tags as:1511 1512.. code-block:: text1513 1514   DW_TAG_string_type1515                DW_AT_name      ("character(*)!2")1516                DW_AT_string_length     (0x00000064)1517   0x00000064:    DW_TAG_variable1518                  DW_AT_location      (DW_OP_fbreg +16)1519                  DW_AT_type  (0x00000083 "integer*8")1520                  DW_AT_data_location (DW_OP_push_object_address, DW_OP_deref)1521                  ...1522                  DW_AT_artificial    (true)1523 1524A Fortran front-end may need to generate a *trampoline* function to call a1525function defined in a different compilation unit. In this case, the front-end1526can emit the following descriptor for the trampoline function:1527 1528.. code-block:: text1529 1530  !DISubprogram(name: "sub1_.t0p", linkageName: "sub1_.t0p", scope: !4, file: !4, type: !5, spFlags: DISPFlagLocalToUnit | DISPFlagDefinition, unit: !7, retainedNodes: !24, targetFuncName: "sub1_")1531 1532The targetFuncName field is the name of the function that the trampoline1533calls. This descriptor results in the following DWARF tag:1534 1535.. code-block:: text1536 1537  DW_TAG_subprogram1538    ...1539    DW_AT_linkage_name	("sub1_.t0p")1540    DW_AT_name	("sub1_.t0p")1541    DW_AT_trampoline	("sub1_")1542 1543Debugging information format1544============================1545 1546Debugging Information Extension for Objective-C Properties1547----------------------------------------------------------1548 1549Introduction1550^^^^^^^^^^^^1551 1552Objective-C provides a simpler way to declare and define accessor methods using1553declared properties.  The language provides features to declare a property and1554to let compiler synthesize accessor methods.1555 1556The debugger lets developers inspect Objective-C interfaces and their instance1557variables and class variables.  However, the debugger does not know anything1558about the properties defined in Objective-C interfaces.  The debugger consumes1559information generated by compiler in DWARF format.  The format does not support1560encoding of Objective-C properties.  This proposal describes DWARF extensions to1561encode Objective-C properties, which the debugger can use to let developers1562inspect Objective-C properties.1563 1564Proposal1565^^^^^^^^1566 1567Objective-C properties exist separately from class members.  A property can be1568defined only by "setter" and "getter" selectors, and be calculated anew on each1569access.  Or a property can just be a direct access to some declared ivar.1570Finally it can have an ivar "automatically synthesized" for it by the compiler,1571in which case the property can be referred to in user code directly using the1572standard C dereference syntax as well as through the property "dot" syntax, but1573there is no entry in the ``@interface`` declaration corresponding to this ivar.1574 1575To facilitate debugging, these properties we will add a new DWARF TAG into the1576``DW_TAG_structure_type`` definition for the class to hold the description of a1577given property, and a set of DWARF attributes that provide said description.1578The property tag will also contain the name and declared type of the property.1579 1580If there is a related ivar, there will also be a DWARF property attribute placed1581in the ``DW_TAG_member`` DIE for that ivar referring back to the property TAG1582for that property.  And in the case where the compiler synthesizes the ivar1583directly, the compiler is expected to generate a ``DW_TAG_member`` for that1584ivar (with the ``DW_AT_artificial`` set to 1), whose name will be the name used1585to access this ivar directly in code, and with the property attribute pointing1586back to the property it is backing.1587 1588The following examples will serve as illustration for our discussion:1589 1590.. code-block:: objc1591 1592  @interface I1 {1593    int n2;1594  }1595 1596  @property int p1;1597  @property int p2;1598  @end1599 1600  @implementation I11601  @synthesize p1;1602  @synthesize p2 = n2;1603  @end1604 1605This produces the following DWARF (this is a "pseudo dwarfdump" output):1606 1607.. code-block:: none1608 1609  0x00000100:  TAG_structure_type [7] *1610                 AT_APPLE_runtime_class( 0x10 )1611                 AT_name( "I1" )1612                 AT_decl_file( "Objc_Property.m" )1613                 AT_decl_line( 3 )1614 1615  0x00000110    TAG_APPLE_property1616                  AT_name ( "p1" )1617                  AT_type ( {0x00000150} ( int ) )1618 1619  0x00000120:   TAG_APPLE_property1620                  AT_name ( "p2" )1621                  AT_type ( {0x00000150} ( int ) )1622 1623  0x00000130:   TAG_member [8]1624                  AT_name( "_p1" )1625                  AT_APPLE_property ( {0x00000110} "p1" )1626                  AT_type( {0x00000150} ( int ) )1627                  AT_artificial ( 0x1 )1628 1629  0x00000140:    TAG_member [8]1630                   AT_name( "n2" )1631                   AT_APPLE_property ( {0x00000120} "p2" )1632                   AT_type( {0x00000150} ( int ) )1633 1634  0x00000150:  AT_type( ( int ) )1635 1636Note, the current convention is that the name of the ivar for an1637auto-synthesized property is the name of the property from which it derives1638with an underscore prepended, as is shown in the example.  But we actually1639don't need to know this convention, since we are given the name of the ivar1640directly.1641 1642Also, it is common practice in ObjC to have different property declarations in1643the ``@interface`` and ``@implementation`` - e.g. to provide a read-only property in1644the interface, and a read-write interface in the implementation.  In that case,1645the compiler should emit whichever property declaration will be in force in the1646current translation unit.1647 1648Developers can decorate a property with attributes which are encoded using1649``DW_AT_APPLE_property_attribute``.1650 1651.. code-block:: objc1652 1653  @property (readonly, nonatomic) int pr;1654 1655.. code-block:: none1656 1657  TAG_APPLE_property [8]1658    AT_name( "pr" )1659    AT_type ( {0x00000147} (int) )1660    AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)1661 1662The setter and getter method names are attached to the property using1663``DW_AT_APPLE_property_setter`` and ``DW_AT_APPLE_property_getter`` attributes.1664 1665.. code-block:: objc1666 1667  @interface I11668  @property (setter=myOwnP3Setter:) int p3;1669  -(void)myOwnP3Setter:(int)a;1670  @end1671 1672  @implementation I11673  @synthesize p3;1674  -(void)myOwnP3Setter:(int)a{ }1675  @end1676 1677The DWARF for this would be:1678 1679.. code-block:: none1680 1681  0x000003bd: TAG_structure_type [7] *1682                AT_APPLE_runtime_class( 0x10 )1683                AT_name( "I1" )1684                AT_decl_file( "Objc_Property.m" )1685                AT_decl_line( 3 )1686 1687  0x000003cd      TAG_APPLE_property1688                    AT_name ( "p3" )1689                    AT_APPLE_property_setter ( "myOwnP3Setter:" )1690                    AT_type( {0x00000147} ( int ) )1691 1692  0x000003f3:     TAG_member [8]1693                    AT_name( "_p3" )1694                    AT_type ( {0x00000147} ( int ) )1695                    AT_APPLE_property ( {0x000003cd} )1696                    AT_artificial ( 0x1 )1697 1698New DWARF Tags1699^^^^^^^^^^^^^^1700 1701+-----------------------+--------+1702| TAG                   | Value  |1703+=======================+========+1704| DW_TAG_APPLE_property | 0x4200 |1705+-----------------------+--------+1706 1707New DWARF Attributes1708^^^^^^^^^^^^^^^^^^^^1709 1710+--------------------------------+--------+-----------+1711| Attribute                      | Value  | Classes   |1712+================================+========+===========+1713| DW_AT_APPLE_property           | 0x3fed | Reference |1714+--------------------------------+--------+-----------+1715| DW_AT_APPLE_property_getter    | 0x3fe9 | String    |1716+--------------------------------+--------+-----------+1717| DW_AT_APPLE_property_setter    | 0x3fea | String    |1718+--------------------------------+--------+-----------+1719| DW_AT_APPLE_property_attribute | 0x3feb | Constant  |1720+--------------------------------+--------+-----------+1721 1722New DWARF Constants1723^^^^^^^^^^^^^^^^^^^1724 1725+--------------------------------------+-------+1726| Name                                 | Value |1727+======================================+=======+1728| DW_APPLE_PROPERTY_readonly           | 0x01  |1729+--------------------------------------+-------+1730| DW_APPLE_PROPERTY_getter             | 0x02  |1731+--------------------------------------+-------+1732| DW_APPLE_PROPERTY_assign             | 0x04  |1733+--------------------------------------+-------+1734| DW_APPLE_PROPERTY_readwrite          | 0x08  |1735+--------------------------------------+-------+1736| DW_APPLE_PROPERTY_retain             | 0x10  |1737+--------------------------------------+-------+1738| DW_APPLE_PROPERTY_copy               | 0x20  |1739+--------------------------------------+-------+1740| DW_APPLE_PROPERTY_nonatomic          | 0x40  |1741+--------------------------------------+-------+1742| DW_APPLE_PROPERTY_setter             | 0x80  |1743+--------------------------------------+-------+1744| DW_APPLE_PROPERTY_atomic             | 0x100 |1745+--------------------------------------+-------+1746| DW_APPLE_PROPERTY_weak               | 0x200 |1747+--------------------------------------+-------+1748| DW_APPLE_PROPERTY_strong             | 0x400 |1749+--------------------------------------+-------+1750| DW_APPLE_PROPERTY_unsafe_unretained  | 0x800 |1751+--------------------------------------+-------+1752| DW_APPLE_PROPERTY_nullability        | 0x1000|1753+--------------------------------------+-------+1754| DW_APPLE_PROPERTY_null_resettable    | 0x2000|1755+--------------------------------------+-------+1756| DW_APPLE_PROPERTY_class              | 0x4000|1757+--------------------------------------+-------+1758 1759Name Accelerator Tables1760-----------------------1761 1762Introduction1763^^^^^^^^^^^^1764 1765The "``.debug_pubnames``" and "``.debug_pubtypes``" formats are not what a1766debugger needs.  The "``pub``" in the section name indicates that the entries1767in the table are publicly visible names only.  This means no static or hidden1768functions show up in the "``.debug_pubnames``".  No static variables or private1769class variables are in the "``.debug_pubtypes``".  Many compilers add different1770things to these tables, so we can't rely upon the contents between gcc, icc, or1771clang.1772 1773The typical query given by users tends not to match up with the contents of1774these tables.  For example, the DWARF spec states that "In the case of the name1775of a function member or static data member of a C++ structure, class or union,1776the name presented in the "``.debug_pubnames``" section is not the simple name1777given by the ``DW_AT_name attribute`` of the referenced debugging information1778entry, but rather the fully qualified name of the data or function member."1779So the only names in these tables for complex C++ entries is a fully1780qualified name.  Debugger users tend not to enter their search strings as1781"``a::b::c(int,const Foo&) const``", but rather as "``c``", "``b::c``" , or1782"``a::b::c``".  So the name entered in the name table must be demangled in1783order to chop it up appropriately and additional names must be manually entered1784into the table to make it effective as a name lookup table for debuggers to1785use.1786 1787All debuggers currently ignore the "``.debug_pubnames``" table as a result of1788its inconsistent and useless public-only name content making it a waste of1789space in the object file.  These tables, when they are written to disk, are not1790sorted in any way, leaving every debugger to do its own parsing and sorting.1791These tables also include an inlined copy of the string values in the table1792itself making the tables much larger than they need to be on disk, especially1793for large C++ programs.1794 1795Can't we just fix the sections by adding all of the names we need to this1796table? No, because that is not what the tables are defined to contain and we1797won't know the difference between the old bad tables and the new good tables.1798At best we could make our own renamed sections that contain all of the data we1799need.1800 1801These tables are also insufficient for what a debugger like LLDB needs.  LLDB1802uses clang for its expression parsing where LLDB acts as a PCH.  LLDB is then1803often asked to look for type "``foo``" or namespace "``bar``", or list items in1804namespace "``baz``".  Namespaces are not included in the pubnames or pubtypes1805tables.  Since clang asks a lot of questions when it is parsing an expression,1806we need to be very fast when looking up names, as it happens a lot.  Having new1807accelerator tables that are optimized for very quick lookups will benefit this1808type of debugging experience greatly.1809 1810We would like to generate name lookup tables that can be mapped into memory1811from disk, and used as is, with little or no up-front parsing.  We would also1812be able to control the exact content of these different tables so they contain1813exactly what we need.  The Name Accelerator Tables were designed to fix these1814issues.  In order to solve these issues we need to:1815 1816* Have a format that can be mapped into memory from disk and used as is1817* Lookups should be very fast1818* Extensible table format so these tables can be made by many producers1819* Contain all of the names needed for typical lookups out of the box1820* Strict rules for the contents of tables1821 1822Table size is important and the accelerator table format should allow the reuse1823of strings from common string tables so the strings for the names are not1824duplicated.  We also want to make sure the table is ready to be used as-is by1825simply mapping the table into memory with minimal header parsing.1826 1827The name lookups need to be fast and optimized for the kinds of lookups that1828debuggers tend to do.  Optimally we would like to touch as few parts of the1829mapped table as possible when doing a name lookup and be able to quickly find1830the name entry we are looking for, or discover there are no matches.  In the1831case of debuggers we optimized for lookups that fail most of the time.1832 1833Each table that is defined should have strict rules on exactly what is in the1834accelerator tables and documented so clients can rely on the content.1835 1836Hash Tables1837^^^^^^^^^^^1838 1839Standard Hash Tables1840""""""""""""""""""""1841 1842Typical hash tables have a header, buckets, and each bucket points to the1843bucket contents:1844 1845.. code-block:: none1846 1847  .------------.1848  |  HEADER    |1849  |------------|1850  |  BUCKETS   |1851  |------------|1852  |  DATA      |1853  `------------'1854 1855The BUCKETS are an array of offsets to DATA for each hash:1856 1857.. code-block:: none1858 1859  .------------.1860  | 0x00001000 | BUCKETS[0]1861  | 0x00002000 | BUCKETS[1]1862  | 0x00002200 | BUCKETS[2]1863  | 0x000034f0 | BUCKETS[3]1864  |            | ...1865  | 0xXXXXXXXX | BUCKETS[n_buckets]1866  '------------'1867 1868So for ``bucket[3]`` in the example above, we have an offset into the table18690x000034f0 which points to a chain of entries for the bucket.  Each bucket must1870contain a next pointer, full 32-bit hash value, the string itself, and the data1871for the current string value.1872 1873.. code-block:: none1874 1875              .------------.1876  0x000034f0: | 0x00003500 | next pointer1877              | 0x12345678 | 32-bit hash1878              | "erase"    | string value1879              | data[n]    | HashData for this bucket1880              |------------|1881  0x00003500: | 0x00003550 | next pointer1882              | 0x29273623 | 32-bit hash1883              | "dump"     | string value1884              | data[n]    | HashData for this bucket1885              |------------|1886  0x00003550: | 0x00000000 | next pointer1887              | 0x82638293 | 32-bit hash1888              | "main"     | string value1889              | data[n]    | HashData for this bucket1890              `------------'1891 1892The problem with this layout for debuggers is that we need to optimize for the1893negative lookup case where the symbol we're searching for is not present.  So1894if we were to lookup "``printf``" in the table above, we would make a 32-bit1895hash for "``printf``", it might match ``bucket[3]``.  We would need to go to1896the offset 0x000034f0 and start looking to see if our 32-bit hash matches.  To1897do so, we need to read the next pointer, then read the hash, compare it, and1898skip to the next bucket.  Each time we are skipping many bytes in memory and1899touching new pages just to do the compare on the full 32-bit hash.  All of1900these accesses then tell us that we didn't have a match.1901 1902Name Hash Tables1903""""""""""""""""1904 1905To solve the issues mentioned above, we have structured the hash tables a bit1906differently: a header, buckets, an array of all unique 32-bit hash values,1907followed by an array of hash value data offsets, one for each hash value, then1908the data for all hash values:1909 1910.. code-block:: none1911 1912  .-------------.1913  |  HEADER     |1914  |-------------|1915  |  BUCKETS    |1916  |-------------|1917  |  HASHES     |1918  |-------------|1919  |  OFFSETS    |1920  |-------------|1921  |  DATA       |1922  `-------------'1923 1924The ``BUCKETS`` in the name tables are an index into the ``HASHES`` array.  By1925making all of the full 32-bit hash values contiguous in memory, we allow1926ourselves to efficiently check for a match while touching as little memory as1927possible.  Most often checking the 32-bit hash values is as far as the lookup1928goes.  If it does match, it usually is a match with no collisions.  So for a1929table with "``n_buckets``" buckets, and "``n_hashes``" unique 32-bit hash1930values, we can clarify the contents of the ``BUCKETS``, ``HASHES`` and1931``OFFSETS`` as:1932 1933.. code-block:: none1934 1935  .-------------------------.1936  |  HEADER.magic           | uint32_t1937  |  HEADER.version         | uint16_t1938  |  HEADER.hash_function   | uint16_t1939  |  HEADER.bucket_count    | uint32_t1940  |  HEADER.hashes_count    | uint32_t1941  |  HEADER.header_data_len | uint32_t1942  |  HEADER_DATA            | HeaderData1943  |-------------------------|1944  |  BUCKETS                | uint32_t[n_buckets] // 32-bit hash indexes1945  |-------------------------|1946  |  HASHES                 | uint32_t[n_hashes] // 32-bit hash values1947  |-------------------------|1948  |  OFFSETS                | uint32_t[n_hashes] // 32-bit offsets to hash value data1949  |-------------------------|1950  |  ALL HASH DATA          |1951  `-------------------------'1952 1953So taking the exact same data from the standard hash example above, we end up1954with:1955 1956.. code-block:: none1957 1958              .------------.1959              | HEADER     |1960              |------------|1961              |          0 | BUCKETS[0]1962              |          2 | BUCKETS[1]1963              |          5 | BUCKETS[2]1964              |          6 | BUCKETS[3]1965              |            | ...1966              |        ... | BUCKETS[n_buckets]1967              |------------|1968              | 0x........ | HASHES[0]1969              | 0x........ | HASHES[1]1970              | 0x........ | HASHES[2]1971              | 0x........ | HASHES[3]1972              | 0x........ | HASHES[4]1973              | 0x........ | HASHES[5]1974              | 0x12345678 | HASHES[6]    hash for BUCKETS[3]1975              | 0x29273623 | HASHES[7]    hash for BUCKETS[3]1976              | 0x82638293 | HASHES[8]    hash for BUCKETS[3]1977              | 0x........ | HASHES[9]1978              | 0x........ | HASHES[10]1979              | 0x........ | HASHES[11]1980              | 0x........ | HASHES[12]1981              | 0x........ | HASHES[13]1982              | 0x........ | HASHES[n_hashes]1983              |------------|1984              | 0x........ | OFFSETS[0]1985              | 0x........ | OFFSETS[1]1986              | 0x........ | OFFSETS[2]1987              | 0x........ | OFFSETS[3]1988              | 0x........ | OFFSETS[4]1989              | 0x........ | OFFSETS[5]1990              | 0x000034f0 | OFFSETS[6]   offset for BUCKETS[3]1991              | 0x00003500 | OFFSETS[7]   offset for BUCKETS[3]1992              | 0x00003550 | OFFSETS[8]   offset for BUCKETS[3]1993              | 0x........ | OFFSETS[9]1994              | 0x........ | OFFSETS[10]1995              | 0x........ | OFFSETS[11]1996              | 0x........ | OFFSETS[12]1997              | 0x........ | OFFSETS[13]1998              | 0x........ | OFFSETS[n_hashes]1999              |------------|2000              |            |2001              |            |2002              |            |2003              |            |2004              |            |2005              |------------|2006  0x000034f0: | 0x00001203 | .debug_str ("erase")2007              | 0x00000004 | A 32-bit array count - number of HashData with name "erase"2008              | 0x........ | HashData[0]2009              | 0x........ | HashData[1]2010              | 0x........ | HashData[2]2011              | 0x........ | HashData[3]2012              | 0x00000000 | String offset into .debug_str (terminate data for hash)2013              |------------|2014  0x00003500: | 0x00001203 | String offset into .debug_str ("collision")2015              | 0x00000002 | A 32-bit array count - number of HashData with name "collision"2016              | 0x........ | HashData[0]2017              | 0x........ | HashData[1]2018              | 0x00001203 | String offset into .debug_str ("dump")2019              | 0x00000003 | A 32-bit array count - number of HashData with name "dump"2020              | 0x........ | HashData[0]2021              | 0x........ | HashData[1]2022              | 0x........ | HashData[2]2023              | 0x00000000 | String offset into .debug_str (terminate data for hash)2024              |------------|2025  0x00003550: | 0x00001203 | String offset into .debug_str ("main")2026              | 0x00000009 | A 32-bit array count - number of HashData with name "main"2027              | 0x........ | HashData[0]2028              | 0x........ | HashData[1]2029              | 0x........ | HashData[2]2030              | 0x........ | HashData[3]2031              | 0x........ | HashData[4]2032              | 0x........ | HashData[5]2033              | 0x........ | HashData[6]2034              | 0x........ | HashData[7]2035              | 0x........ | HashData[8]2036              | 0x00000000 | String offset into .debug_str (terminate data for hash)2037              `------------'2038 2039So we still have all of the same data, we just organize it more efficiently for2040debugger lookup.  If we repeat the same "``printf``" lookup from above, we2041would hash "``printf``" and find it matches ``BUCKETS[3]`` by taking the 32-bit2042hash value and modulo it by ``n_buckets``.  ``BUCKETS[3]`` contains "6" which2043is the index into the ``HASHES`` table.  We would then compare any consecutive204432-bit hash values in the ``HASHES`` array as long as the hashes would be in2045``BUCKETS[3]``.  We do this by verifying that each subsequent hash value modulo2046``n_buckets`` is still 3.  In the case of a failed lookup we would access the2047memory for ``BUCKETS[3]``, and then compare a few consecutive 32-bit hashes2048before we know that we have no match.  We don't end up marching through2049multiple words of memory and we really keep the number of processor data cache2050lines being accessed as small as possible.2051 2052The string hash that is used for these lookup tables is the Daniel J.2053Bernstein hash which is also used in the ELF ``GNU_HASH`` sections.  It is a2054very good hash for all kinds of names in programs with very few hash2055collisions.2056 2057Empty buckets are designated by using an invalid hash index of ``UINT32_MAX``.2058 2059Details2060^^^^^^^2061 2062These name hash tables are designed to be generic where specializations of the2063table get to define additional data that goes into the header ("``HeaderData``"),2064how the string value is stored ("``KeyType``") and the content of the data for each2065hash value.2066 2067Header Layout2068"""""""""""""2069 2070The header has a fixed part, and the specialized part.  The exact format of the2071header is:2072 2073.. code-block:: c2074 2075  struct Header2076  {2077    uint32_t   magic;           // 'HASH' magic value to allow endian detection2078    uint16_t   version;         // Version number2079    uint16_t   hash_function;   // The hash function enumeration that was used2080    uint32_t   bucket_count;    // The number of buckets in this hash table2081    uint32_t   hashes_count;    // The total number of unique hash values and hash data offsets in this table2082    uint32_t   header_data_len; // The bytes to skip to get to the hash indexes (buckets) for correct alignment2083                                // Specifically the length of the following HeaderData field - this does not2084                                // include the size of the preceding fields2085    HeaderData header_data;     // Implementation specific header data2086  };2087 2088The header starts with a 32-bit "``magic``" value which must be ``'HASH'``2089encoded as an ASCII integer.  This allows the detection of the start of the2090hash table and also allows the table's byte order to be determined so the table2091can be correctly extracted.  The "``magic``" value is followed by a 16-bit2092``version`` number which allows the table to be revised and modified in the2093future.  The current version number is 1. ``hash_function`` is a ``uint16_t``2094enumeration that specifies which hash function was used to produce this table.2095The current values for the hash function enumerations include:2096 2097.. code-block:: c2098 2099  enum HashFunctionType2100  {2101    eHashFunctionDJB = 0u, // Daniel J Bernstein hash function2102  };2103 2104``bucket_count`` is a 32-bit unsigned integer that represents how many buckets2105are in the ``BUCKETS`` array.  ``hashes_count`` is the number of unique 32-bit2106hash values that are in the ``HASHES`` array, and is the same number of offsets2107are contained in the ``OFFSETS`` array.  ``header_data_len`` specifies the size2108in bytes of the ``HeaderData`` that is filled in by specialized versions of2109this table.2110 2111Fixed Lookup2112""""""""""""2113 2114The header is followed by the buckets, hashes, offsets, and hash value data.2115 2116.. code-block:: c2117 2118  struct FixedTable2119  {2120    uint32_t buckets[Header.bucket_count];  // An array of hash indexes into the "hashes[]" array below2121    uint32_t hashes [Header.hashes_count];  // Every unique 32-bit hash for the entire table is in this table2122    uint32_t offsets[Header.hashes_count];  // An offset that corresponds to each item in the "hashes[]" array above2123  };2124 2125``buckets`` is an array of 32-bit indexes into the ``hashes`` array.  The2126``hashes`` array contains all of the 32-bit hash values for all names in the2127hash table.  Each hash in the ``hashes`` table has an offset in the ``offsets``2128array that points to the data for the hash value.2129 2130This table setup makes it very easy to repurpose these tables to contain2131different data, while keeping the lookup mechanism the same for all tables.2132This layout also makes it possible to save the table to disk and map it in2133later and do very efficient name lookups with little or no parsing.2134 2135DWARF lookup tables can be implemented in a variety of ways and can store a lot2136of information for each name.  We want to make the DWARF tables extensible and2137able to store the data efficiently so we have used some of the DWARF features2138that enable efficient data storage to define exactly what kind of data we store2139for each name.2140 2141The ``HeaderData`` contains a definition of the contents of each HashData chunk.2142We might want to store an offset to all of the debug information entries (DIEs)2143for each name.  To keep things extensible, we create a list of items, or2144Atoms, that are contained in the data for each name.  First comes the type of2145the data in each atom:2146 2147.. code-block:: c2148 2149  enum AtomType2150  {2151    eAtomTypeNULL       = 0u,2152    eAtomTypeDIEOffset  = 1u,   // DIE offset, check form for encoding2153    eAtomTypeCUOffset   = 2u,   // DIE offset of the compiler unit header that contains the item in question2154    eAtomTypeTag        = 3u,   // DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data22155    eAtomTypeNameFlags  = 4u,   // Flags from enum NameFlags2156    eAtomTypeTypeFlags  = 5u,   // Flags from enum TypeFlags2157  };2158 2159The enumeration values and their meanings are:2160 2161.. code-block:: none2162 2163  eAtomTypeNULL       - a termination atom that specifies the end of the atom list2164  eAtomTypeDIEOffset  - an offset into the .debug_info section for the DWARF DIE for this name2165  eAtomTypeCUOffset   - an offset into the .debug_info section for the CU that contains the DIE2166  eAtomTypeDIETag     - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is2167  eAtomTypeNameFlags  - Flags for functions and global variables (isFunction, isInlined, isExternal...)2168  eAtomTypeTypeFlags  - Flags for types (isCXXClass, isObjCClass, ...)2169 2170Then we allow each atom type to define the atom type and how the data for each2171atom type data is encoded:2172 2173.. code-block:: c2174 2175  struct Atom2176  {2177    uint16_t type;  // AtomType enum value2178    uint16_t form;  // DWARF DW_FORM_XXX defines2179  };2180 2181The ``form`` type above is from the DWARF specification and defines the exact2182encoding of the data for the Atom type.  See the DWARF specification for the2183``DW_FORM_`` definitions.2184 2185.. code-block:: c2186 2187  struct HeaderData2188  {2189    uint32_t die_offset_base;2190    uint32_t atom_count;2191    Atoms    atoms[atom_count0];2192  };2193 2194``HeaderData`` defines the base DIE offset that should be added to any atoms2195that are encoded using the ``DW_FORM_ref1``, ``DW_FORM_ref2``,2196``DW_FORM_ref4``, ``DW_FORM_ref8`` or ``DW_FORM_ref_udata``.  It also defines2197what is contained in each ``HashData`` object -- ``Atom.form`` tells us how large2198each field will be in the ``HashData`` and the ``Atom.type`` tells us how this data2199should be interpreted.2200 2201For the current implementations of the "``.apple_names``" (all functions +2202globals), the "``.apple_types``" (names of all types that are defined), and2203the "``.apple_namespaces``" (all namespaces), we currently set the ``Atom``2204array to be:2205 2206.. code-block:: c2207 2208  HeaderData.atom_count = 1;2209  HeaderData.atoms[0].type = eAtomTypeDIEOffset;2210  HeaderData.atoms[0].form = DW_FORM_data4;2211 2212This defines the contents to be the DIE offset (``eAtomTypeDIEOffset``) that is2213encoded as a 32-bit value (``DW_FORM_data4``).  This allows a single name to have2214multiple matching DIEs in a single file, which could come up with an inlined2215function for instance.  Future tables could include more information about the2216DIE such as flags indicating if the DIE is a function, method, block,2217or inlined.2218 2219The KeyType for the DWARF table is a 32-bit string table offset into the2220".debug_str" table.  The ".debug_str" is the string table for the DWARF which2221may already contain copies of all of the strings.  This helps make sure, with2222help from the compiler, that we reuse the strings between all of the DWARF2223sections and keeps the hash table size down.  Another benefit to having the2224compiler generate all strings as ``DW_FORM_strp`` in the debug info, is that2225DWARF parsing can be made much faster.2226 2227After a lookup is made, we get an offset into the hash data.  The hash data2228needs to be able to deal with 32-bit hash collisions, so the chunk of data2229at the offset in the hash data consists of a triple:2230 2231.. code-block:: c2232 2233  uint32_t str_offset2234  uint32_t hash_data_count2235  HashData[hash_data_count]2236 2237If "str_offset" is zero, then the bucket contents are done. 99.9% of the2238hash data chunks contain a single item (no 32-bit hash collision):2239 2240.. code-block:: none2241 2242  .------------.2243  | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")2244  | 0x00000004 | uint32_t HashData count2245  | 0x........ | uint32_t HashData[0] DIE offset2246  | 0x........ | uint32_t HashData[1] DIE offset2247  | 0x........ | uint32_t HashData[2] DIE offset2248  | 0x........ | uint32_t HashData[3] DIE offset2249  | 0x00000000 | uint32_t KeyType (end of hash chain)2250  `------------'2251 2252If there are collisions, you will have multiple valid string offsets:2253 2254.. code-block:: none2255 2256  .------------.2257  | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")2258  | 0x00000004 | uint32_t HashData count2259  | 0x........ | uint32_t HashData[0] DIE offset2260  | 0x........ | uint32_t HashData[1] DIE offset2261  | 0x........ | uint32_t HashData[2] DIE offset2262  | 0x........ | uint32_t HashData[3] DIE offset2263  | 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print")2264  | 0x00000002 | uint32_t HashData count2265  | 0x........ | uint32_t HashData[0] DIE offset2266  | 0x........ | uint32_t HashData[1] DIE offset2267  | 0x00000000 | uint32_t KeyType (end of hash chain)2268  `------------'2269 2270Current testing with real world C++ binaries has shown that there is around 1227132-bit hash collision per 100,000 name entries.2272 2273Contents2274^^^^^^^^2275 2276As we said, we want to strictly define exactly what is included in the2277different tables.  For DWARF, we have 3 tables: "``.apple_names``",2278"``.apple_types``", and "``.apple_namespaces``".2279 2280"``.apple_names``" sections should contain an entry for each DWARF DIE whose2281``DW_TAG`` is a ``DW_TAG_label``, ``DW_TAG_inlined_subroutine``, or2282``DW_TAG_subprogram`` that has address attributes: ``DW_AT_low_pc``,2283``DW_AT_high_pc``, ``DW_AT_ranges`` or ``DW_AT_entry_pc``.  It also contains2284``DW_TAG_variable`` DIEs that have a ``DW_OP_addr`` in the location (global and2285static variables).  All global and static variables should be included,2286including those scoped within functions and classes.  For example using the2287following code:2288 2289.. code-block:: c2290 2291  static int var = 0;2292 2293  void f ()2294  {2295    static int var = 0;2296  }2297 2298Both of the static ``var`` variables would be included in the table.  All2299functions should emit both their full names and their basenames.  For C or C++,2300the full name is the mangled name (if available) which is usually in the2301``DW_AT_MIPS_linkage_name`` attribute, and the ``DW_AT_name`` contains the2302function basename.  If global or static variables have a mangled name in a2303``DW_AT_MIPS_linkage_name`` attribute, this should be emitted along with the2304simple name found in the ``DW_AT_name`` attribute.2305 2306"``.apple_types``" sections should contain an entry for each DWARF DIE whose2307tag is one of:2308 2309* DW_TAG_array_type2310* DW_TAG_class_type2311* DW_TAG_enumeration_type2312* DW_TAG_pointer_type2313* DW_TAG_reference_type2314* DW_TAG_string_type2315* DW_TAG_structure_type2316* DW_TAG_subroutine_type2317* DW_TAG_typedef2318* DW_TAG_union_type2319* DW_TAG_ptr_to_member_type2320* DW_TAG_set_type2321* DW_TAG_subrange_type2322* DW_TAG_base_type2323* DW_TAG_const_type2324* DW_TAG_immutable_type2325* DW_TAG_file_type2326* DW_TAG_namelist2327* DW_TAG_packed_type2328* DW_TAG_volatile_type2329* DW_TAG_restrict_type2330* DW_TAG_atomic_type2331* DW_TAG_interface_type2332* DW_TAG_unspecified_type2333* DW_TAG_shared_type2334 2335Only entries with a ``DW_AT_name`` attribute are included, and the entry must2336not be a forward declaration (``DW_AT_declaration`` attribute with a non-zero2337value).  For example, using the following code:2338 2339.. code-block:: c2340 2341  int main ()2342  {2343    int *b = 0;2344    return *b;2345  }2346 2347We get a few type DIEs:2348 2349.. code-block:: none2350 2351  0x00000067:     TAG_base_type [5]2352                  AT_encoding( DW_ATE_signed )2353                  AT_name( "int" )2354                  AT_byte_size( 0x04 )2355 2356  0x0000006e:     TAG_pointer_type [6]2357                  AT_type( {0x00000067} ( int ) )2358                  AT_byte_size( 0x08 )2359 2360The ``DW_TAG_pointer_type`` is not included because it does not have a ``DW_AT_name``.2361 2362"``.apple_namespaces``" section should contain all ``DW_TAG_namespace`` DIEs.2363If we run into a namespace that has no name this is an anonymous namespace, and2364the name should be output as "``(anonymous namespace)``" (without the quotes).2365Why?  This matches the output of the ``abi::cxa_demangle()`` that is in the2366standard C++ library that demangles mangled names.2367 2368 2369Language Extensions and File Format Changes2370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2371 2372Objective-C Extensions2373""""""""""""""""""""""2374 2375"``.apple_objc``" section should contain all ``DW_TAG_subprogram`` DIEs for an2376Objective-C class.  The name used in the hash table is the name of the2377Objective-C class itself.  If the Objective-C class has a category, then an2378entry is made for both the class name without the category, and for the class2379name with the category.  So if we have a DIE at offset 0x1234 with a name of2380method "``-[NSString(my_additions) stringWithSpecialString:]``", we would add2381an entry for "``NSString``" that points to DIE 0x1234, and an entry for2382"``NSString(my_additions)``" that points to 0x1234.  This allows us to quickly2383track down all Objective-C methods for an Objective-C class when doing2384expressions.  It is needed because of the dynamic nature of Objective-C where2385anyone can add methods to a class.  The DWARF for Objective-C methods is also2386emitted differently from C++ classes where the methods are not usually2387contained in the class definition, they are scattered about across one or more2388compile units.  Categories can also be defined in different shared libraries.2389So we need to be able to quickly find all of the methods and class functions2390given the Objective-C class name, or quickly find all methods and class2391functions for a class + category name.  This table does not contain any2392selector names, it just maps Objective-C class names (or class names +2393category) to all of the methods and class functions.  The selectors are added2394as function basenames in the "``.debug_names``" section.2395 2396In the "``.apple_names``" section for Objective-C functions, the full name is2397the entire function name with the brackets ("``-[NSString2398stringWithCString:]``") and the basename is the selector only2399("``stringWithCString:``").2400 2401Mach-O Changes2402""""""""""""""2403 2404The sections names for the apple hash tables are for non-mach-o files.  For2405mach-o files, the sections should be contained in the ``__DWARF`` segment with2406names as follows:2407 2408* "``.apple_names``" -> "``__apple_names``"2409* "``.apple_types``" -> "``__apple_types``"2410* "``.apple_namespaces``" -> "``__apple_namespac``" (16 character limit)2411* "``.apple_objc``" -> "``__apple_objc``"2412 2413.. _codeview:2414 2415CodeView Debug Info Format2416==========================2417 2418LLVM supports emitting CodeView, the Microsoft debug info format, and this2419section describes the design and implementation of that support.2420 2421Format Background2422-----------------2423 2424CodeView as a format is clearly oriented around C++ debugging, and in C++, the2425majority of debug information tends to be type information. Therefore, the2426overriding design constraint of CodeView is the separation of type information2427from other "symbol" information so that type information can be efficiently2428merged across translation units. Both type information and symbol information is2429generally stored as a sequence of records, where each record begins with a243016-bit record size and a 16-bit record kind.2431 2432Type information is usually stored in the ``.debug$T`` section of the object2433file.  All other debug info, such as line info, string table, symbol info, and2434inlinee info, is stored in one or more ``.debug$S`` sections. There may only be2435one ``.debug$T`` section per object file, since all other debug info refers to2436it. If a PDB (enabled by the ``/Zi`` MSVC option) was used during compilation,2437the ``.debug$T`` section will contain only an ``LF_TYPESERVER2`` record pointing2438to the PDB. When using PDBs, symbol information appears to remain in the object2439file ``.debug$S`` sections.2440 2441Type records are referred to by their index, which is the number of records in2442the stream before a given record plus ``0x1000``. Many common basic types, such2443as the basic integral types and unqualified pointers to them, are represented2444using type indices less than ``0x1000``. Such basic types are built in to2445CodeView consumers and do not require type records.2446 2447Each type record may only contain type indices that are less than its own type2448index. This ensures that the graph of type stream references is acyclic. While2449the source-level type graph may contain cycles through pointer types (consider a2450linked list struct), these cycles are removed from the type stream by always2451referring to the forward declaration record of user-defined record types. Only2452"symbol" records in the ``.debug$S`` streams may refer to complete,2453non-forward-declaration type records.2454 2455Working with CodeView2456---------------------2457 2458These are instructions for some common tasks for developers working to improve2459LLVM's CodeView support. Most of them revolve around using the CodeView dumper2460embedded in ``llvm-readobj``.2461 2462* Testing MSVC's output::2463 2464    $ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file2465    $ llvm-readobj --codeview foo.obj2466 2467* Getting LLVM IR debug info out of Clang::2468 2469    $ clang -g -gcodeview --target=x86_64-windows-msvc foo.cpp -S -emit-llvm2470 2471  Use this to generate LLVM IR for LLVM test cases.2472 2473* Generate and dump CodeView from LLVM IR metadata::2474 2475    $ llc foo.ll -filetype=obj -o foo.obj2476    $ llvm-readobj --codeview foo.obj > foo.txt2477 2478  Use this pattern in lit test cases and FileCheck the output of llvm-readobj2479 2480Improving LLVM's CodeView support is a process of finding interesting type2481records, constructing a C++ test case that makes MSVC emit those records,2482dumping the records, understanding them, and then generating equivalent records2483in LLVM's backend.2484