diff --git a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst --- a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst +++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst @@ -15,8 +15,8 @@ .. _amdgpu-dwarf-introduction: -Introduction -============ +1. Introduction +=============== AMD [:ref:`AMD `] has been working on supporting heterogeneous computing through the AMD Radeon Open Compute Platform (ROCm) [:ref:`AMD-ROCm @@ -74,8 +74,8 @@ .. _amdgpu-dwarf-motivation: -Motivation -========== +2. Motivation +============= This document presents a set of backwards compatible extensions to DWARF Version 5 [:ref:`DWARF `] to support heterogeneous debugging. @@ -393,7 +393,7 @@ Support is added for the HIP programming language [:ref:`HIP `] which is supported by the AMDGPU. See -:ref:`amdgpu-dwarf-language-names`. +:ref:`amdgpu-dwarf-language-names-table`. The following sections provide the definitions for the additional operations, as well as clarifying how existing expression operations, CFI operations, and @@ -419,21 +419,31 @@ .. _amdgpu-dwarf-changes-relative-to-dwarf-version-5: -Changes Relative to DWARF Version 5 -=================================== +A. Changes Relative to DWARF Version 5 +====================================== -General Description -------------------- +.. note:: + + This section provides changes relative to DWARF Version 5. The section numbers + generally correspond to those in the DWARF Version 5 standard. + + .. note:: -Attribute Types -~~~~~~~~~~~~~~~ + Notes are included to describe how the changes are to be applied to the + DWARF Version 5 standard. They also describe rational and issues that may + need further consideration. + +A.2 General Description +----------------------- + +A.2.2 Attribute Types +~~~~~~~~~~~~~~~~~~~~~ .. note:: This augments DWARF Version 5 section 2.2 and Table 2.2. -The following table provides the additional attributes. See -:ref:`amdgpu-dwarf-debugging-information-entry-attributes`. +The following table provides the additional attributes. .. table:: Attribute names :name: amdgpu-dwarf-attribute-names-table @@ -441,17 +451,17 @@ =========================== ==================================== Attribute Usage =========================== ==================================== - ``DW_AT_LLVM_active_lane`` SIMD or SIMT active lanes - ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string - ``DW_AT_LLVM_lane_pc`` SIMD or SIMT lane program location - ``DW_AT_LLVM_lanes`` SIMD or SIMT thread lane count - ``DW_AT_LLVM_vector_size`` Base type vector size + ``DW_AT_LLVM_active_lane`` SIMD or SIMT active lanes (see :ref:`amdgpu-dwarf-low-level-information`) + ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string (see :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`) + ``DW_AT_LLVM_lane_pc`` SIMD or SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`) + ``DW_AT_LLVM_lanes`` SIMD or SIMT thread lane count (see :ref:`amdgpu-dwarf-low-level-information`) + ``DW_AT_LLVM_vector_size`` Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`) =========================== ==================================== .. _amdgpu-dwarf-expressions: -DWARF Expressions -~~~~~~~~~~~~~~~~~ +A.2.5 DWARF Expressions +~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -506,8 +516,8 @@ .. _amdgpu-dwarf-expression-evaluation-context: -DWARF Expression Evaluation Context -+++++++++++++++++++++++++++++++++++ +A.2.5.1 DWARF Expression Evaluation Context ++++++++++++++++++++++++++++++++++++++++++++ A DWARF expression is evaluated in a context that can include a number of context elements. If multiple context elements are specified then they must be @@ -526,9 +536,9 @@ It is required for operations that are related to target architecture threads. - *For example, the* ``DW_OP_form_tls_address`` *operation and* - ``DW_OP_LLVM_form_aspace_address`` *operation when given an address space that - is thread specific.* + *For example, the* ``DW_OP_regval_type`` *operation, or the* + ``DW_OP_form_tls_address`` *and* ``DW_OP_LLVM_form_aspace_address`` + *operations when given an address space that is thread specific.* *A current lane* @@ -618,10 +628,10 @@ *Note that this compilation unit may not be the same as the compilation unit determined from the loaded code object corresponding to the current program - location. For example, the evaluation of the expression E associated with a - ``DW_AT_location`` attribute of the debug information entry operand of the - ``DW_OP_call*`` operations is evaluated with the compilation unit that - contains E and not the one that contains the ``DW_OP_call*`` operation + location. For example, the evaluation of the expression E associated with a* + ``DW_AT_location`` *attribute of the debug information entry operand of the* + ``DW_OP_call*`` *operations is evaluated with the compilation unit that + contains E and not the one that contains the* ``DW_OP_call*`` *operation expression.* *A current target architecture* @@ -641,7 +651,7 @@ must be the same as the target architecture of the current thread. * If the current compilation unit is specified, then the current target - architecture default address space address size must be the same as he + architecture default address space address size must be the same as the ``address_size`` field in the header of the current compilation unit and any associated entry in the ``.debug_aranges`` section. @@ -651,7 +661,7 @@ corresponding to the current program location. * If the current program location is specified, then the current target - architecture default address space address size must be the same as he + architecture default address space address size must be the same as the ``address_size`` field in the header of any entry corresponding to the current program location in the ``.debug_addr``, ``.debug_line``, ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and @@ -666,9 +676,8 @@ It is required for the ``DW_OP_push_object_address`` operation. *For example, the* ``DW_AT_data_location`` *attribute on type debug - information entries specifies the the program object corresponding to a - runtime descriptor as the current object when it evaluates its associated - expression.* + information entries specifies the program object corresponding to a runtime + descriptor as the current object when it evaluates its associated expression.* The result is undefined if the location descriptor is invalid (see :ref:`amdgpu-dwarf-location-description`). @@ -689,7 +698,7 @@ If the evaluation requires a context element that is not specified, then the result of the evaluation is an error. -*A DWARF expression for the location description may be able to be evaluated +*A DWARF expression for a location description may be able to be evaluated without a thread, lane, call frame, program location, or architecture context. For example, the location of a global variable may be able to be evaluated without such context. If the expression evaluates with an error then it may @@ -707,8 +716,8 @@ .. _amdgpu-dwarf-expression-value: -DWARF Expression Value -++++++++++++++++++++++ +A.2.5.2 DWARF Expression Value +++++++++++++++++++++++++++++++ A value has a type and a literal value. It can represent a literal value of any supported base type of the target architecture. The base type specifies the @@ -744,8 +753,8 @@ .. _amdgpu-dwarf-location-description: -DWARF Location Description -++++++++++++++++++++++++++ +A.2.5.3 DWARF Location Description +++++++++++++++++++++++++++++++++++ *Debugging information must provide consumers a way to find the location of program variables, determine the bounds of dynamic arrays and strings, and @@ -799,16 +808,19 @@ provided by the operations. *Location descriptions are a language independent representation of addressing -rules. They are created using DWARF operation expressions of arbitrary -complexity. They can be the result of evaluating a debugger information entry -attribute that specifies an operation expression. In this usage they can -describe the location of an object as long as its lifetime is either static or -the same as the lexical block (see DWARF Version 5 section 3.5) that owns it, -and it does not move during its lifetime. They can be the result of evaluating a -debugger information entry attribute that specifies a location list expression. -In this usage they can describe the location of an object that has a limited -lifetime, changes its location during its lifetime, or has multiple locations -over part or all of its lifetime.* +rules.* + +* *They can be the result of evaluating a debugger information entry attribute + that specifies an operation expression of arbitrary complexity. In this usage + they can describe the location of an object as long as its lifetime is either + static or the same as the lexical block (see + :ref:`amdgpu-dwarf-lexical-block-entries`) that owns it, and it does not move + during its lifetime.* + +* *They can be the result of evaluating a debugger information entry attribute + that specifies a location list expression. In this usage they can describe the + location of an object that has a limited lifetime, changes its location during + its lifetime, or has multiple locations over part or all of its lifetime.* If a location description has more than one single location description, the DWARF expression is ill-formed if the object value held in each single location @@ -884,8 +896,8 @@ .. _amdgpu-dwarf-operation-expressions: -DWARF Operation Expressions -+++++++++++++++++++++++++++ +A.2.5.4 DWARF Operation Expressions ++++++++++++++++++++++++++++++++++++ An operation expression is comprised of a stream of operations, each consisting of an opcode followed by zero or more operands. The number of operands is @@ -963,7 +975,7 @@ specifies the byte count. It can be used: * as the value of a debugging information entry attribute that is encoded using - class ``exprloc`` (see DWARF Version 5 section 7.5.5), + class ``exprloc`` (see :ref:`amdgpu-dwarf-classes-and-forms`), * as the operand to certain operation expression operations, @@ -975,8 +987,12 @@ .. _amdgpu-dwarf-stack-operations: -Stack Operations -################ +A.2.5.4.1 Stack Operations +########################## + +.. note:: + + This section replaces DWARF Version 5 section 2.5.1.3. The following operations manipulate the DWARF stack. Operations that index the stack assume that the top of the stack (most recently added entry) has index 0. @@ -1018,7 +1034,7 @@ ``DW_OP_over`` pushes a copy of the entry with index 1. - *This is equivalent to a ``DW_OP_pick 1`` operation.* + *This is equivalent to a* ``DW_OP_pick 1`` *operation.* 5. ``DW_OP_swap`` @@ -1034,8 +1050,12 @@ .. _amdgpu-dwarf-control-flow-operations: -Control Flow Operations -####################### +A.2.5.4.2 Control Flow Operations +################################# + +.. note:: + + This section replaces DWARF Version 5 section 2.5.1.5. The following operations provide simple control of the flow of a DWARF operation expression. @@ -1097,7 +1117,7 @@ relative to the beginning of the ``.debug_info`` section that contains the current compilation unit. D may not be in the current compilation unit. - .. note: + .. note:: DWARF Version 5 states that DR can be an offset in a ``.debug_info`` section other than the one that contains the current compilation unit. It @@ -1176,14 +1196,14 @@ entry is to push just one location description on the stack. That location description may have more than one single location description. - The previous rule for ``exprloc`` also has the same problem as normally + The previous rule for ``exprloc`` also has the same problem, as normally a variable or formal parameter location expression may leave multiple entries on the stack and only return the top entry. GDB implements ``DW_OP_call*`` by always executing E on the same stack. If the location list has multiple matching entries, it simply picks the first one and ignores the rest. This seems fundamentally at odds with - the desire to supporting multiple places for variables. + the desire to support multiple places for variables. So, it feels like ``DW_OP_call*`` should both support pushing a location description on the stack for a variable or formal parameter, and also @@ -1234,8 +1254,8 @@ *This allows a call operation to be used to compute the location description for any variable or formal parameter regardless of whether the - producer has optimized it to a constant. This is consistent with the - ``DW_OP_implicit_pointer`` operation.* + producer has optimized it to a constant. This is consistent with the* + ``DW_OP_implicit_pointer`` *operation.* .. note:: @@ -1264,12 +1284,12 @@ .. _amdgpu-dwarf-value-operations: -Value Operations -################ +A.2.5.4.3 Value Operations +########################## This section describes the operations that push values on the stack. -Each value stack entry has a type and a literal value and can represent a +Each value stack entry has a type and a literal value. It can represent a literal value of any supported base type of the target architecture. The base type specifies the size, encoding, and endianity of the literal value. @@ -1277,8 +1297,12 @@ .. _amdgpu-dwarf-literal-operations: -Literal Operations -^^^^^^^^^^^^^^^^^^ +A.2.5.4.3.1 Literal Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces DWARF Version 5 section 2.5.1.1. The following operations all push a literal value onto the DWARF stack. @@ -1325,7 +1349,7 @@ link-time relocation but should not be interpreted by the consumer as a relocatable address (for example, offsets to thread-local storage).* -9. ``DW_OP_const_type`` +7. ``DW_OP_const_type`` ``DW_OP_const_type`` has three operands. The first is an unsigned LEB128 integer DR that represents the byte offset of a debugging information entry @@ -1346,7 +1370,7 @@ operation can be parsed easily without reference to the* ``.debug_info`` *section.* -10. ``DW_OP_LLVM_push_lane`` *New* +8. ``DW_OP_LLVM_push_lane`` *New* ``DW_OP_LLVM_push_lane`` pushes the target architecture lane identifier of the current lane as a value with the generic type. @@ -1357,8 +1381,8 @@ .. _amdgpu-dwarf-arithmetic-logical-operations: -Arithmetic and Logical Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.3.2 Arithmetic and Logical Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -1366,8 +1390,8 @@ .. _amdgpu-dwarf-type-conversions-operations: -Type Conversion Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.3.3 Type Conversion Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -1375,8 +1399,13 @@ .. _amdgpu-dwarf-general-operations: -Special Value Operations -^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.3.4 Special Value Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces parts of DWARF Version 5 sections 2.5.1.2, 2.5.1.3, and + 2.5.1.7. There are these special value operations currently defined: @@ -1511,8 +1540,8 @@ undefined location storage or the offset of any bit exceeds the size of the location storage LS specified by any single location description SL of L. - See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules - concerning implicit location descriptions created by the + See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special + rules concerning implicit location descriptions created by the ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_implicit_aspace_pointer`` operations. @@ -1559,8 +1588,8 @@ represents a target architecture specific address space identifier AS. The operation is equivalent to performing ``DW_OP_swap; - DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S R``. The value V - retrieved is left on the stack with the type D. + DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S DR``. The value V + retrieved is left on the stack with the type T. *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address`` *operation can be used and provides greater expressiveness.* @@ -1585,17 +1614,17 @@ frame information (see :ref:`amdgpu-dwarf-call-frame-information`). If the result of E is a location description L (see - :ref:`amdgpu-dwarf-register-location-descriptions`), and the last operation - executed by E is a ``DW_OP_reg*`` for register R with a target architecture - specific base type of T, then the contents of the register are retrieved as - if a ``DW_OP_deref_type DR`` operation was performed where DR is the offset - of a hypothetical debug information entry in the current compilation unit - for T. The resulting value V s pushed on the stack. + :ref:`amdgpu-dwarf-register-location-description-operations`), and the last + operation executed by E is a ``DW_OP_reg*`` for register R with a target + architecture specific base type of T, then the contents of the register are + retrieved as if a ``DW_OP_deref_type DR`` operation was performed where DR + is the offset of a hypothetical debug information entry in the current + compilation unit for T. The resulting value V s pushed on the stack. *Using* ``DW_OP_reg*`` *provides a more compact form for the case where the value was in a register on entry to the subprogram.* - .. note: + .. note:: It is unclear how this provides a more compact expression, as ``DW_OP_regval_type`` could be used which is marginally larger. @@ -1621,14 +1650,20 @@ .. _amdgpu-dwarf-location-description-operations: -Location Description Operations -############################### +A.2.5.4.4 Location Description Operations +######################################### This section describes the operations that push location descriptions on the stack. -General Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _amdgpu-dwarf-general-location-description-operations: + +A.2.5.4.4.1 General Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces part of DWARF Version 5 section 2.5.1.3. 1. ``DW_OP_LLVM_offset`` *New* @@ -1687,15 +1722,33 @@ expression evaluation.* *This operation provides explicit functionality (especially for arrays - involving descriptions) that is analogous to the implicit push of the base - location description of a structure prior to evaluation of a - ``DW_AT_data_member_location`` to access a data member of a structure.* + involving descriptors) that is analogous to the implicit push of the base + location description of a structure prior to evaluation of a* + ``DW_AT_data_member_location`` *to access a data member of a structure.* .. note:: This operation could be removed and the object location description specified as the initial stack as for ``DW_AT_data_member_location``. + Or this operation could be used instead of needing to specify an initial + stack. The latter approach is more composable as access to the object may + be needed at any point of the expression, and passing it as the initial + stack requires the entire expression to be aware where on the stack it is. + If this were done, ``DW_AT_use_location`` would require a + ``DW_OP_push_object2_address`` operation for the second object. + + Or a more general way to pass an arbitrary number of arguments in and an + operation to get the Nth one such as ``DW_OP_arg N``. A vector of + arguments would then be passed in the expression context rather than an + initial stack. This could also resolve the issues with ``DW_OP_call*`` by + allowing a specific number of arguments passed in and returned to be + specified. The ``DW_OP_call*`` operation could then always execute on a + separate stack: the number of arguments would be specified in a new call + operation and taken from the callers stack, and similarly the number of + return results specified and copied from the called stack back to the + callee stack when the called expression was complete. + The only attribute that specifies a current object is ``DW_AT_data_location`` so the non-normative text seems to overstate how this is being used. Or are there other attributes that need to state they @@ -1717,8 +1770,12 @@ .. _amdgpu-dwarf-undefined-location-description-operations: -Undefined Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.4.2 Undefined Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces DWARF Version 5 section 2.6.1.1.1. *The undefined location storage represents a piece or all of an object that is present in the source but not in the object code (perhaps due to optimization). @@ -1739,8 +1796,13 @@ .. _amdgpu-dwarf-memory-location-description-operations: -Memory Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.4.3 Memory Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2, + 2.5.1.3, and 2.6.1.1.2. Each of the target architecture specific address spaces has a corresponding memory location storage that denotes the linear addressable memory of that @@ -1796,10 +1858,9 @@ description L with a one memory location description SL. If the type size of V is less than the generic type size, then the value V is zero extended to the size of the generic type. The least significant generic type size bits - are treated as a twos-complement unsigned value to be used as an address A. - SL specifies memory location storage corresponding to the target - architecture default address space with a bit offset equal to A scaled by 8 - (the byte size). + are treated as an unsigned value to be used as an address A. SL specifies + memory location storage corresponding to the target architecture default + address space with a bit offset equal to A scaled by 8 (the byte size). The implicit conversion could also be defined as target architecture specific. For example, GDB checks if V is an integral type. If it is not it gives an @@ -1812,7 +1873,7 @@ pointer value IPV with the target architecture default address space, then it is implicitly converted to a location description with one single location description specified by IPV. See -:ref:`amdgpu-dwarf-implicit-location-descriptions`. +:ref:`amdgpu-dwarf-implicit-location-description-operations`. .. note:: @@ -1869,8 +1930,8 @@ The address size S is defined as the address bit size of the target architecture specific address space that corresponds to AS. - A is adjusted to S bits by zero extending if necessary, and then treating the - least significant S bits as a twos-complement unsigned value A'. + A is adjusted to S bits by zero extending if necessary, and then treating + the least significant S bits as an unsigned value A'. It pushes a location description L with one memory location description SL on the stack. SL specifies the memory location storage LS that corresponds @@ -1890,8 +1951,8 @@ The DWARF expression is ill-formed if AS is not one of the values defined by the target architecture specific ``DW_ASPACE_*`` values. - See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules - concerning implicit pointer values produced by dereferencing implicit + See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special + rules concerning implicit pointer values produced by dereferencing implicit location descriptions created by the ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_implicit_aspace_pointer`` operations. @@ -1950,7 +2011,7 @@ The location description L for the *frame base* of the current subprogram is obtained from the ``DW_AT_frame_base`` attribute of the debugger information entry corresponding to the current subprogram as described in - :ref:`amdgpu-dwarf-debugging-information-entry-attributes`. + :ref:`amdgpu-dwarf-low-level-information`. The location description L is updated as if the ``DW_OP_LLVM_offset_uconst B`` operation was applied. The updated L is pushed on the stack. @@ -2010,10 +2071,14 @@ Could also consider adding ``DW_OP_aspace_breg0, DW_OP_aspace_breg1, ..., DW_OP_aspace_bref31`` which would save encoding size. -.. _amdgpu-dwarf-register-location-descriptions: +.. _amdgpu-dwarf-register-location-description-operations: + +A.2.5.4.4.4 Register Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Register Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: + + This section replaces DWARF Version 5 section 2.6.1.1.3. There is a register location storage that corresponds to each of the target architecture registers. The size of each register location storage corresponds @@ -2062,10 +2127,14 @@ ``DW_OP_breg*`` *register-based addressing operations, or use* ``DW_OP_deref*`` *on a register location description.* -.. _amdgpu-dwarf-implicit-location-descriptions: +.. _amdgpu-dwarf-implicit-location-description-operations: + +A.2.5.4.4.5 Implicit Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: -Implicit Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This section replaces DWARF Version 5 section 2.6.1.1.4. Implicit location storage represents a piece or all of an object which has no actual location in the program but whose contents are nonetheless known, either @@ -2103,8 +2172,8 @@ location description specifies the actual value of the object, rather than specifying the memory or register storage that holds the value.* - See :ref:`amdgpu-dwarf-implicit-location-descriptions` for special rules - concerning implicit pointer values produced by dereferencing implicit + See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special + rules concerning implicit pointer values produced by dereferencing implicit location descriptions created by the ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_implicit_aspace_pointer`` operations. @@ -2218,7 +2287,7 @@ *The restrictions on how an implicit pointer location description created by* ``DW_OP_implicit_pointer`` *and* ``DW_OP_LLVM_aspace_implicit_pointer`` *can be used are to simplify the DWARF consumer. Similarly, for an implicit - pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ .* + pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ *.* 4. ``DW_OP_LLVM_aspace_implicit_pointer`` *New* @@ -2259,13 +2328,17 @@ ``DW_AT_location`` *or* ``DW_AT_const_value`` *attribute (for example,* ``DW_TAG_dwarf_procedure``\ *). By using E*\ :sub:`2`\ *, a consumer can reconstruct the value of the object when asked to dereference the pointer -described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` or +described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` *or* ``DW_OP_LLVM_aspace_implicit_pointer`` *operation.* .. _amdgpu-dwarf-composite-location-description-operations: -Composite Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A.2.5.4.4.6 Composite Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + This section replaces DWARF Version 5 section 2.6.1.2. A composite location storage represents an object or value which may be contained in part of another location storage or contained in parts of more @@ -2480,8 +2553,12 @@ .. _amdgpu-dwarf-location-list-expressions: -DWARF Location List Expressions -+++++++++++++++++++++++++++++++ +A.2.5.5 DWARF Location List Expressions ++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + This section replaces DWARF Version 5 section 2.6.2. *To meet the needs of recent computer architectures and optimization techniques, debugging information must be able to describe the location of an object whose @@ -2573,10 +2650,10 @@ A location list expression can only be used as the value of a debugger information entry attribute that is encoded using class ``loclist`` or -``loclistsptr`` (see DWARF Version 5 section 7.5.5). The value of the attribute -provides an index into a separate object file section called ``.debug_loclists`` -or ``.debug_loclists.dwo`` (for split DWARF object files) that contains the -location list entries. +``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the +attribute provides an index into a separate object file section called +``.debug_loclists`` or ``.debug_loclists.dwo`` (for split DWARF object files) +that contains the location list entries. A ``DW_OP_call*`` and ``DW_OP_implicit_pointer`` operation can be used to specify a debugger information entry attribute that has a location list @@ -2596,8 +2673,8 @@ .. _amdgpu-dwarf-segment_addresses: -Segmented Addresses -~~~~~~~~~~~~~~~~~~~ +A.2.12 Segmented Addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -2798,69 +2875,106 @@ operations may be needed. The legal casts between address classes may need to be defined on a per language address class basis. -.. _amdgpu-dwarf-debugging-information-entry-attributes: - -Debugging Information Entry Attributes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A.3 Program Scope Entries +------------------------- .. note:: This section provides changes to existing debugger information entry - attributes and defines attributes added by these extensions. These would be - incorporated into the appropriate DWARF Version 5 chapter 2 sections. + attributes. These would be incorporated into the corresponding DWARF Version 5 + chapter 3 sections. -1. ``DW_AT_location`` +A.3.1 Unit Entries +~~~~~~~~~~~~~~~~~~ - Any debugging information entry describing a data object (which includes - variables and parameters) or common blocks may have a ``DW_AT_location`` - attribute, whose value is a DWARF expression E. +.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries: - The result of the attribute is obtained by evaluating E with a context that - has a result kind of a location description, an unspecified object, the - compilation unit that contains E, an empty initial stack, and other context - elements corresponding to the source language thread of execution upon which - the user is focused, if any. The result of the evaluation is the location - description of the base of the data object. +A.3.1.1 Full and Partial Compilation Unit Entries ++++++++++++++++++++++++++++++++++++++++++++++++++ - See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules - used by the ``DW_OP_call*`` operations. +.. note:: - .. note:: + This augments DWARF Version 5 section 3.1.1 and Table 3.1. - Delete the description of how the ``DW_OP_call*`` operations evaluate a - ``DW_AT_location`` attribute as that is now described in the operations. +Additional language codes defined for use with the ``DW_AT_language`` attribute +are defined in :ref:`amdgpu-dwarf-language-names-table`. - .. note:: +.. table:: Language Names + :name: amdgpu-dwarf-language-names-table - See the discussion about the ``DW_AT_location`` attribute in the - ``DW_OP_call*`` operation. Having each attribute only have a single - purpose and single execution semantics seems desirable. It makes it easier - for the consumer that no longer have to track the context. It makes it - easier for the producer as it can rely on a single semantics for each - attribute. + ==================== ============================= + Language Name Meaning + ==================== ============================= + ``DW_LANG_LLVM_HIP`` HIP Language. + ==================== ============================= - For that reason, limiting the ``DW_AT_location`` attribute to only - supporting evaluating the location description of an object, and using a - different attribute and encoding class for the evaluation of DWARF - expression *procedures* on the same operation expression stack seems - desirable. +The HIP language [:ref:`HIP `] can be supported by extending +the C++ language. -2. ``DW_AT_const_value`` +.. note:: - .. note:: + The following new attribute is added. - Could deprecate using the ``DW_AT_const_value`` attribute for - ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information - entries that have been optimized to a constant. Instead, - ``DW_AT_location`` could be used with a DWARF expression that produces an - implicit location description now that any location description can be - used within a DWARF expression. This allows the ``DW_OP_call*`` operations - to be used to push the location description of any variable regardless of - how it is optimized. +1. A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit + may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an + augmentation string. + + *The augmentation string allows producers to indicate that there is + additional vendor or target specific information in the debugging + information entries. For example, this might be information about the + version of vendor specific extensions that are being used.* + + If not present, or if the string is empty, then the compilation unit has no + augmentation string. + + The format for the augmentation string is: + + | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * + + Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y + version number of the extensions used, and *options* is an optional string + providing additional information about the extensions. The version number + must conform to semantic versioning [:ref:`SEMVER `]. + The *options* string must not contain the "\ ``]``\ " character. + + For example: + + :: + + [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] + +A.3.3 Subroutine and Entry Point Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _amdgpu-dwarf-low-level-information: + +A.3.3.5 Low-Level Information ++++++++++++++++++++++++++++++ + +1. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or + ``DW_TAG_entry_point`` debugger information entry may have a + ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E. -3. ``DW_AT_frame_base`` + The result of the attribute is obtained by evaluating E with a context that + has a result kind of a location description, an unspecified object, the + compilation unit that contains E, an empty initial stack, and other context + elements corresponding to the source language thread of execution upon which + the user is focused, if any. The result of the evaluation is the location + description L of the place where the return address for the current call + frame's subprogram or entry point is stored. + + The DWARF is ill-formed if L is not comprised of one memory location + description for one of the target architecture specific address spaces. + + .. note:: + + It is unclear why ``DW_TAG_inlined_subroutine`` has a + ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or + ``DW_AT_static_link`` attribute. Seems it would either have all of them or + none. Since inlined subprograms do not have a call frame it seems they + would have none of these attributes. - A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry +2. A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry may have a ``DW_AT_frame_base`` attribute, whose value is a DWARF expression E. @@ -2874,12 +2988,12 @@ resulting location description L is not comprised of one single location description SL. - If SL a register location description for register R, then L is replaced + If SL is a register location description for register R, then L is replaced with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This computes the frame base memory location description in the target architecture default address space. - *This allows the more compact* ``DW_OPreg*`` *to be used instead of* + *This allows the more compact* ``DW_OP_reg*`` *to be used instead of* ``DW_OP_breg* 0``\ *.* .. note:: @@ -2897,165 +3011,103 @@ *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a stack pointer register plus or minus some offset.* -4. ``DW_AT_data_member_location`` - - For a ``DW_AT_data_member_location`` attribute there are two cases: - - 1. If the attribute is an integer constant B, it provides the offset in - bytes from the beginning of the containing entity. - - The result of the attribute is obtained by evaluating a - ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the - location description of the beginning of the containing entity. The - result of the evaluation is the location description of the base of the - member entry. +3. If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information + entry is lexically nested, it may have a ``DW_AT_static_link`` attribute, + whose value is a DWARF expression E. - *If the beginning of the containing entity is not byte aligned, then the - beginning of the member entry has the same bit displacement within a - byte.* + The result of the attribute is obtained by evaluating E with a context that + has a result kind of a location description, an unspecified object, the + compilation unit that contains E, an empty initial stack, and other context + elements corresponding to the source language thread of execution upon which + the user is focused, if any. The result of the evaluation is the location + description L of the *canonical frame address* (see + :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of + the subprogram instance that immediately lexically encloses the current call + frame's subprogram or entry point. - 2. Otherwise, the attribute must be a DWARF expression E which is evaluated - with a context that has a result kind of a location description, an - unspecified object, the compilation unit that contains E, an initial - stack comprising the location description of the beginning of the - containing entity, and other context elements corresponding to the - source language thread of execution upon which the user is focused, if - any. The result of the evaluation is the location description of the - base of the member entry. + The DWARF is ill-formed if L is is not comprised of one memory location + description for one of the target architecture specific address spaces. .. note:: - The beginning of the containing entity can now be any location - description, including those with more than one single location - description, and those with single location descriptions that are of any - kind and have any bit offset. + The following new attributes are added. -5. ``DW_AT_use_location`` +4. For languages that are implemented using a SIMD or SIMT execution model, a + ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or + ``DW_TAG_entry_point`` debugger information entry may have a + ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is + the number of lanes per thread. This is the static number of lanes per + thread. It is not the dynamic number of lanes with which the thread was + initiated, for example, due to smaller or partial work-groups. - The ``DW_TAG_ptr_to_member_type`` debugging information entry has a - ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is - used to compute the location description of the member of the class to which - the pointer to member entry points. + If not present, the default value of 1 is used. - *The method used to find the location description of a given member of a - class, structure, or union is common to any instance of that class, - structure, or union and to any instance of the pointer to member type. The - method is thus associated with the pointer to member type, rather than with - each object that has a pointer to member type.* + The DWARF is ill-formed if the value is 0. - The ``DW_AT_use_location`` DWARF expression is used in conjunction with the - location description for a particular object of the given pointer to member - type and for a particular structure or class instance. +5. For languages that are implemented using a SIMD or SIMT execution model, a + ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or + ``DW_TAG_entry_point`` debugging information entry may have a + ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E. The result of the attribute is obtained by evaluating E with a context that has a result kind of a location description, an unspecified object, the - compilation unit that contains E, an initial stack comprising two entries, - and other context elements corresponding to the source language thread of - execution upon which the user is focused, if any. The first stack entry is - the value of the pointer to member object itself. The second stack entry is - the location description of the base of the entire class, structure, or - union instance containing the member whose location is being calculated. The - result of the evaluation is the location description of the member of the - class to which the pointer to member entry points. - -6. ``DW_AT_data_location`` + compilation unit that contains E, an empty initial stack, and other context + elements corresponding to the source language thread of execution upon which + the user is focused, if any. - The ``DW_AT_data_location`` attribute may be used with any type that - provides one or more levels of hidden indirection and/or run-time parameters - in its representation. Its value is a DWARF operation expression E which - computes the location description of the data for an object. When this - attribute is omitted, the location description of the data is the same as - the location description of the object. + The resulting location description L is for a thread lane count sized vector + of generic type elements. The thread lane count is the value of the + ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program + location of the corresponding lane, where the least significant element + corresponds to the first target architecture specific lane identifier and so + forth. If the lane was not active when the current subprogram was called, + its element is an undefined location description. - The result of the attribute is obtained by evaluating E with a context that - has a result kind of a location description, an object that is the location - description of the data descriptor, the compilation unit that contains E, an - empty initial stack, and other context elements corresponding to the source - language thread of execution upon which the user is focused, if any. The - result of the evaluation is the location description of the base of the - member entry. + ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where + each lane of a SIMT thread is positioned even when it is in divergent + control flow that is not active.* - *E will typically involve an operation expression that begins with a* - ``DW_OP_push_object_address`` *operation which loads the location - description of the object which can then serve as a description in - subsequent calculation.* - - .. note:: - - Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and - ``DW_AT_vtable_elem_location`` allow both operation expressions and - location list expressions, why does ``DW_AT_data_location`` not allow - both? In all cases they apply to data objects so less likely that - optimization would cause different operation expressions for different - program location ranges. But if supporting for some then should be for - all. - - It seems odd this attribute is not the same as - ``DW_AT_data_member_location`` in having an initial stack with the - location description of the object since the expression has to need it. + *Typically, the result is a location description with one composite location + description with each part being a location description with either one + undefined location description or one memory location description.* -7. ``DW_AT_vtable_elem_location`` + If not present, the thread is not being used in a SIMT manner, and the + thread's current program location is used. - An entry for a virtual function also has a ``DW_AT_vtable_elem_location`` - attribute whose value is a DWARF expression E. +6. For languages that are implemented using a SIMD or SIMT execution model, a + ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or + ``DW_TAG_entry_point`` debugger information entry may have a + ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E. The result of the attribute is obtained by evaluating E with a context that - has a result kind of a location description, an unspecified object, the - compilation unit that contains E, an initial stack comprising the location - description of the object of the enclosing type, and other context elements + has a result kind of a value, an unspecified object, the compilation unit + that contains E, an empty initial stack, and other context elements corresponding to the source language thread of execution upon which the user - is focused, if any. The result of the evaluation is the location description - of the slot for the function within the virtual function table for the - enclosing class. - -8. ``DW_AT_static_link`` - - If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information - entry is lexically nested, it may have a ``DW_AT_static_link`` attribute, - whose value is a DWARF expression E. - - The result of the attribute is obtained by evaluating E with a context that - has a result kind of a location description, an unspecified object, the - compilation unit that contains E, an empty initial stack, and other context - elements corresponding to the source language thread of execution upon which - the user is focused, if any. The result of the evaluation is the location - description L of the *canonical frame address* (see - :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of - the subprogram instance that immediately lexically encloses the current call - frame's subprogram or entry point. - - The DWARF is ill-formed if L is is not comprised of one memory location - description for one of the target architecture specific address spaces. - -9. ``DW_AT_return_addr`` + is focused, if any. - A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or - ``DW_TAG_entry_point`` debugger information entry may have a - ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E. + The DWARF is ill-formed if the resulting value V is not an integral value. - The result of the attribute is obtained by evaluating E with a context that - has a result kind of a location description, an unspecified object, the - compilation unit that contains E, an empty initial stack, and other context - elements corresponding to the source language thread of execution upon which - the user is focused, if any. The result of the evaluation is the location - description L of the place where the return address for the current call - frame's subprogram or entry point is stored. + The resulting V is a bit mask of active lanes for the current program + location. The N\ :sup:`th` least significant bit of the mask corresponds to + the N\ :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is + inactive. - The DWARF is ill-formed if L is not comprised of one memory location - description for one of the target architecture specific address spaces. + *Some targets may update the target architecture execution mask for regions + of code that must execute with different sets of lanes than the current + active lanes. For example, some code must execute with all lanes made + temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to + provide the means to determine the source language active lanes.* - .. note:: + If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target + architecture execution mask is used. - It is unclear why ``DW_TAG_inlined_subroutine`` has a - ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or - ``DW_AT_static_link`` attribute. Seems it would either have all of them or - none. Since inlined subprograms do not have a call frame it seems they - would have none of these attributes. +A.3.4 Call Site Entries and Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -10. ``DW_AT_call_value``, ``DW_AT_call_data_location``, and - ``DW_AT_call_data_value`` +A.3.4.2 Call Site Parameters +++++++++++++++++++++++++++++ - A ``DW_TAG_call_site_parameter`` debugger information entry may have a +1. A ``DW_TAG_call_site_parameter`` debugger information entry may have a ``DW_AT_call_value`` attribute, whose value is a DWARF operation expression E\ :sub:`1`\ . @@ -3084,6 +3136,13 @@ :sub:`2` would just be a ``DW_OP_push_object_address``, then the ``DW_AT_call_data_location`` attribute may be omitted. + .. note:: + + The DWARF Version 5 implies that `DW_OP_push_object_address` may be used + but does not state what object must be specified in the context. Either + `DW_OP_push_object_address` cannot be used, or the object to be passed in + the context must be defined. + The value of the ``DW_AT_call_data_value`` attribute is obtained by evaluating E\ :sub:`3` with a context that has a result kind of a value, an unspecified object, the compilation unit that contains E, an empty initial @@ -3092,11 +3151,11 @@ value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made by the call site. - The result of these attributes is undefined if the current call frame is - not for the subprogram containing the ``DW_TAG_call_site_parameter`` - debugger information entry or the current program location is not for the - call site containing the ``DW_TAG_call_site_parameter`` debugger information - entry in the current call frame. + The result of these attributes is undefined if the current call frame is not + for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger + information entry or the current program location is not for the call site + containing the ``DW_TAG_call_site_parameter`` debugger information entry in + the current call frame. *The consumer may have to virtually unwind to the call site (see* :ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these @@ -3117,84 +3176,93 @@ registers that have been clobbered, and clobbered memory will no longer have the value at the time of the call.* -11. ``DW_AT_LLVM_lanes`` *New* +.. _amdgpu-dwarf-lexical-block-entries: - For languages that are implemented using a SIMD or SIMT execution model, a - ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or - ``DW_TAG_entry_point`` debugger information entry may have a - ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is - the number of lanes per thread. This is the static number of lanes per - thread. It is not the dynamic number of lanes with which the thread was - initiated, for example, due to smaller or partial work-groups. +A.3.5 Lexical Block Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If not present, the default value of 1 is used. +.. note:: - The DWARF is ill-formed if the value is 0. + This section is the same as DWARF Version 5 section 3.5. -12. ``DW_AT_LLVM_lane_pc`` *New* +A.4 Data Object and Object List Entries +--------------------------------------- - For languages that are implemented using a SIMD or SIMT execution model, a - ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or - ``DW_TAG_entry_point`` debugging information entry may have a - ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E. +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the corresponding DWARF Version 5 + chapter 4 sections. + +A.4.1 Data Object Entries +~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Any debugging information entry describing a data object (which includes + variables and parameters) or common blocks may have a ``DW_AT_location`` + attribute, whose value is a DWARF expression E. The result of the attribute is obtained by evaluating E with a context that has a result kind of a location description, an unspecified object, the compilation unit that contains E, an empty initial stack, and other context elements corresponding to the source language thread of execution upon which - the user is focused, if any. + the user is focused, if any. The result of the evaluation is the location + description of the base of the data object. - The resulting location description L is for a thread lane count sized vector - of generic type elements. The thread lane count is the value of the - ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program - location of the corresponding lane, where the least significant element - corresponds to the first target architecture specific lane identifier and so - forth. If the lane was not active when the current subprogram was called, - its element is an undefined location description. + See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules + used by the ``DW_OP_call*`` operations. - ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where - each lane of a SIMT thread is positioned even when it is in divergent - control flow that is not active.* + .. note:: - *Typically, the result is a location description with one composite location - description with each part being a location description with either one - undefined location description or one memory location description.* + Delete the description of how the ``DW_OP_call*`` operations evaluate a + ``DW_AT_location`` attribute as that is now described in the operations. - If not present, the thread is not being used in a SIMT manner, and the - thread's current program location is used. + .. note:: -13. ``DW_AT_LLVM_active_lane`` *New* + See the discussion about the ``DW_AT_location`` attribute in the + ``DW_OP_call*`` operation. Having each attribute only have a single + purpose and single execution semantics seems desirable. It makes it easier + for the consumer that no longer have to track the context. It makes it + easier for the producer as it can rely on a single semantics for each + attribute. - For languages that are implemented using a SIMD or SIMT execution model, a - ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or - ``DW_TAG_entry_point`` debugger information entry may have a - ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E. + For that reason, limiting the ``DW_AT_location`` attribute to only + supporting evaluating the location description of an object, and using a + different attribute and encoding class for the evaluation of DWARF + expression *procedures* on the same operation expression stack seems + desirable. - The result of the attribute is obtained by evaluating E with a context that - has a result kind of a value, an unspecified object, the compilation unit - that contains E, an empty initial stack, and other context elements - corresponding to the source language thread of execution upon which the user - is focused, if any. +2. ``DW_AT_const_value`` - The DWARF is ill-formed if the resulting value V is not an integral value. + .. note:: - The resulting V is a bit mask of active lanes for the current program - location. The N\ :sup:`th` least significant bit of the mask corresponds to - the N\ :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is - inactive. + Could deprecate using the ``DW_AT_const_value`` attribute for + ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information + entries that have been optimized to a constant. Instead, + ``DW_AT_location`` could be used with a DWARF expression that produces an + implicit location description now that any location description can be + used within a DWARF expression. This allows the ``DW_OP_call*`` operations + to be used to push the location description of any variable regardless of + how it is optimized. - *Some targets may update the target architecture execution mask for regions - of code that must execute with different sets of lanes than the current - active lanes. For example, some code must execute with all lanes made - temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to - provide the means to determine the source language active lanes.* +A.5 Type Entries +---------------- - If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target - architecture execution mask is used. +.. note:: -14. ``DW_AT_LLVM_vector_size`` *New* + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the corresponding DWARF Version 5 + chapter 5 sections. + +.. _amdgpu-dwarf-base-type-entries: + +A.5.1 Base Type Entries +~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: - A ``DW_TAG_base_type`` debugger information entry for a base type T may have + The following new attribute is added. + +1. A ``DW_TAG_base_type`` debugger information entry for a base type T may have a ``DW_AT_LLVM_vector_size`` attribute whose value is an integer constant that is the vector type size N. @@ -3215,76 +3283,143 @@ would not be suitable as the type of a stack value entry. But perhaps that could be replaced by using this attribute. -15. ``DW_AT_LLVM_augmentation`` *New* +A.5.7 Structure, Union, Class and Interface Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit - may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an - augmentation string. +A.5.7.3 Derived or Extended Structures, Classes and Interfaces +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - *The augmentation string allows producers to indicate that there is - additional vendor or target specific information in the debugging - information entries. For example, this might be information about the - version of vendor specific extensions that are being used.* +1. For a ``DW_AT_data_member_location`` attribute there are two cases: - If not present, or if the string is empty, then the compilation unit has no - augmentation string. + 1. If the attribute is an integer constant B, it provides the offset in + bytes from the beginning of the containing entity. - The format for the augmentation string is: + The result of the attribute is obtained by evaluating a + ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the + location description of the beginning of the containing entity. The + result of the evaluation is the location description of the base of the + member entry. - | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * + *If the beginning of the containing entity is not byte aligned, then the + beginning of the member entry has the same bit displacement within a + byte.* - Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y - version number of the extensions used, and *options* is an optional string - providing additional information about the extensions. The version number - must conform to semantic versioning [:ref:`SEMVER `]. - The *options* string must not contain the "\ ``]``\ " character. + 2. Otherwise, the attribute must be a DWARF expression E which is evaluated + with a context that has a result kind of a location description, an + unspecified object, the compilation unit that contains E, an initial + stack comprising the location description of the beginning of the + containing entity, and other context elements corresponding to the + source language thread of execution upon which the user is focused, if + any. The result of the evaluation is the location description of the + base of the member entry. - For example: + .. note:: - :: + The beginning of the containing entity can now be any location + description, including those with more than one single location + description, and those with single location descriptions that are of any + kind and have any bit offset. - [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] +A.5.7.8 Member Function Entries ++++++++++++++++++++++++++++++++ -Program Scope Entities ----------------------- +1. An entry for a virtual function also has a ``DW_AT_vtable_elem_location`` + attribute whose value is a DWARF expression E. -.. _amdgpu-dwarf-language-names: + The result of the attribute is obtained by evaluating E with a context that + has a result kind of a location description, an unspecified object, the + compilation unit that contains E, an initial stack comprising the location + description of the object of the enclosing type, and other context elements + corresponding to the source language thread of execution upon which the user + is focused, if any. The result of the evaluation is the location description + of the slot for the function within the virtual function table for the + enclosing class. -Unit Entities -~~~~~~~~~~~~~ +A.5.14 Pointer to Member Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: +1. The ``DW_TAG_ptr_to_member_type`` debugging information entry has a + ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is + used to compute the location description of the member of the class to which + the pointer to member entry points. - This augments DWARF Version 5 section 3.1.1 and Table 3.1. + *The method used to find the location description of a given member of a + class, structure, or union is common to any instance of that class, + structure, or union and to any instance of the pointer to member type. The + method is thus associated with the pointer to member type, rather than with + each object that has a pointer to member type.* -Additional language codes defined for use with the ``DW_AT_language`` attribute -are defined in :ref:`amdgpu-dwarf-language-names-table`. + The ``DW_AT_use_location`` DWARF expression is used in conjunction with the + location description for a particular object of the given pointer to member + type and for a particular structure or class instance. -.. table:: Language Names - :name: amdgpu-dwarf-language-names-table + The result of the attribute is obtained by evaluating E with a context that + has a result kind of a location description, an unspecified object, the + compilation unit that contains E, an initial stack comprising two entries, + and other context elements corresponding to the source language thread of + execution upon which the user is focused, if any. The first stack entry is + the value of the pointer to member object itself. The second stack entry is + the location description of the base of the entire class, structure, or + union instance containing the member whose location is being calculated. The + result of the evaluation is the location description of the member of the + class to which the pointer to member entry points. - ==================== ============================= - Language Name Meaning - ==================== ============================= - ``DW_LANG_LLVM_HIP`` HIP Language. - ==================== ============================= +A.5.16 Dynamic Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The HIP language [:ref:`HIP `] can be supported by extending -the C++ language. +1. The ``DW_AT_data_location`` attribute may be used with any type that + provides one or more levels of hidden indirection and/or run-time parameters + in its representation. Its value is a DWARF operation expression E which + computes the location description of the data for an object. When this + attribute is omitted, the location description of the data is the same as + the location description of the object. -Other Debugger Information --------------------------- + The result of the attribute is obtained by evaluating E with a context that + has a result kind of a location description, an object that is the location + description of the data descriptor, the compilation unit that contains E, an + empty initial stack, and other context elements corresponding to the source + language thread of execution upon which the user is focused, if any. The + result of the evaluation is the location description of the base of the + member entry. -Accelerated Access -~~~~~~~~~~~~~~~~~~ + *E will typically involve an operation expression that begins with a* + ``DW_OP_push_object_address`` *operation which loads the location + description of the object which can then serve as a descriptor in subsequent + calculation.* + + .. note:: + + Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and + ``DW_AT_vtable_elem_location`` allow both operation expressions and + location list expressions, why does ``DW_AT_data_location`` not allow + both? In all cases they apply to data objects so less likely that + optimization would cause different operation expressions for different + program location ranges. But if supporting for some then should be for + all. + + It seems odd this attribute is not the same as + ``DW_AT_data_member_location`` in having an initial stack with the + location description of the object since the expression has to need it. + +A.6 Other Debugging Information +------------------------------- + +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the corresponding DWARF Version 5 + chapter 6 sections. + +A.6.1 Accelerated Access +~~~~~~~~~~~~~~~~~~~~~~~~ .. _amdgpu-dwarf-lookup-by-name: -Lookup By Name -++++++++++++++ +A.6.1.1 Lookup By Name +++++++++++++++++++++++ -Contents of the Name Index -########################## +A.6.1.1.1 Contents of the Name Index +#################################### .. note:: @@ -3304,11 +3439,11 @@ or ``DW_OP_form_tls_address`` operation are included; otherwise, they are excluded. -Data Representation of the Name Index -##################################### +A.6.1.1.4 Data Representation of the Name Index +############################################### -Section Header -^^^^^^^^^^^^^^ +A.6.1.1.4.1 Section Header +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -3342,14 +3477,14 @@ .. _amdgpu-dwarf-line-number-information: -Line Number Information -~~~~~~~~~~~~~~~~~~~~~~~ +A.6.2 Line Number Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Line Number Program Header -++++++++++++++++++++++++++++++ +A.6.2.4 The Line Number Program Header +++++++++++++++++++++++++++++++++++++++ -Standard Content Descriptions -############################# +A.6.2.4.1 Standard Content Descriptions +####################################### .. note:: @@ -3392,8 +3527,8 @@ .. _amdgpu-dwarf-call-frame-information: -Call Frame Information -~~~~~~~~~~~~~~~~~~~~~~ +A.6.4 Call Frame Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -3403,12 +3538,12 @@ location description, including those with composite and implicit location descriptions. - These changes would be incorporated into the DWARF Version 5 section 6.1. + These changes would be incorporated into the DWARF Version 5 section 6.4. .. _amdgpu-dwarf-structure_of-call-frame-information: -Structure of Call Frame Information -+++++++++++++++++++++++++++++++++++ +A.6.4.1 Structure of Call Frame Information ++++++++++++++++++++++++++++++++++++++++++++ The register rules are: @@ -3682,8 +3817,8 @@ .. _amdgpu-dwarf-call-frame-instructions: -Call Frame Instructions -+++++++++++++++++++++++ +A.6.4.2 Call Frame Instructions ++++++++++++++++++++++++++++++++ Some call frame instructions have operands that are encoded as DWARF operation expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF @@ -3720,8 +3855,8 @@ .. _amdgpu-dwarf-row-creation-instructions: -Row Creation Instructions -######################### +A.6.4.2.1 Row Creation Instructions +################################### .. note:: @@ -3729,8 +3864,8 @@ .. _amdgpu-dwarf-cfa-definition-instructions: -CFA Definition Instructions -########################### +A.6.4.2.2 CFA Definition Instructions +##################################### 1. ``DW_CFA_def_cfa`` @@ -3748,7 +3883,7 @@ displacement B. AS is set to the target architecture default address space identifier. The required action is to define the current CFA rule to be the result of evaluating the DWARF operation expression ``DW_OP_constu AS; - DW_OP_aspace_bregx R, B*data_alignment_factor`` as a location description. + DW_OP_aspace_bregx R, B * data_alignment_factor`` as a location description. *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second operand is signed and factored.* @@ -3773,7 +3908,7 @@ architecture specific address space identifier AS. The required action is to define the current CFA rule to be the result of evaluating the DWARF operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, - B*data_alignment_factor`` as a location description. + B * data_alignment_factor`` as a location description. If AS is not one of the values defined by the target architecture specific ``DW_ASPACE_*`` values, then the DWARF expression is ill-formed. @@ -3810,9 +3945,9 @@ The ``DW_CFA_def_cfa_offset_sf`` instruction takes a signed LEB128 operand representing a factored byte displacement B. The required action is to define the current CFA rule to be the result of evaluating the DWARF - operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, - B*data_alignment_factor`` as a location description. R and AS are the old - CFA register number and address space respectively. + operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, B * + data_alignment_factor`` as a location description. R and AS are the old CFA + register number and address space respectively. If the subprogram has no current CFA rule, or the rule was defined by a ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed. @@ -3837,8 +3972,8 @@ .. _amdgpu-dwarf-register-rule-instructions: -Register Rule Instructions -########################## +A.6.4.2.3 Register Rule Instructions +#################################### 1. ``DW_CFA_undefined`` @@ -3857,7 +3992,7 @@ The ``DW_CFA_offset`` instruction takes two operands: a register number R (encoded with the opcode) and an unsigned LEB128 constant representing a factored displacement B. The required action is to change the rule for the - register specified by R to be an *offset(B\*data_alignment_factor)* rule. + register specified by R to be an *offset(B \* data_alignment_factor)* rule. .. note:: @@ -3888,7 +4023,7 @@ The ``DW_CFA_val_offset`` instruction takes two unsigned LEB128 operands representing a register number R and a factored displacement B. The required action is to change the rule for the register indicated by R to be a - *val_offset(B\*data_alignment_factor)* rule. + *val_offset(B \* data_alignment_factor)* rule. .. note:: @@ -3958,22 +4093,22 @@ to ``DW_CFA_restore``, except for the encoding and size of the register operand. -Row State Instructions -###################### +A.6.4.2.4 Row State Instructions +################################ .. note:: These instructions are the same as in DWARF Version 5 section 6.4.2.4. -Padding Instruction -################### +A.6.4.2.5 Padding Instruction +############################# .. note:: These instructions are the same as in DWARF Version 5 section 6.4.2.5. -Call Frame Instruction Usage -++++++++++++++++++++++++++++ +A.6.4.3 Call Frame Instruction Usage +++++++++++++++++++++++++++++++++++++ .. note:: @@ -3981,53 +4116,45 @@ .. _amdgpu-dwarf-call-frame-calling-address: -Call Frame Calling Address -++++++++++++++++++++++++++ +A.6.4.4 Call Frame Calling Address +++++++++++++++++++++++++++++++++++ .. note:: The same as in DWARF Version 5 section 6.4.4. -Data Representation -------------------- +A.7 Data Representation +----------------------- + +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the corresponding DWARF Version 5 + chapter 7 sections. .. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats: -32-Bit and 64-Bit DWARF Formats -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A.7.4 32-Bit and 64-Bit DWARF Formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: - This augments DWARF Version 5 section 7.4. - -1. Within the body of the ``.debug_info`` section, certain forms of attribute - value depend on the choice of DWARF format as follows. For the 32-bit DWARF - format, the value is a 4-byte unsigned integer; for the 64-bit DWARF format, - the value is an 8-byte unsigned integer. - - .. table:: ``.debug_info`` section attribute form roles - :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table - - ================================== =================================== - Form Role - ================================== =================================== - DW_FORM_line_strp offset in ``.debug_line_str`` - DW_FORM_ref_addr offset in ``.debug_info`` - DW_FORM_sec_offset offset in a section other than - ``.debug_info`` or ``.debug_str`` - DW_FORM_strp offset in ``.debug_str`` - DW_FORM_strp_sup offset in ``.debug_str`` section of - supplementary object file - DW_OP_call_ref offset in ``.debug_info`` - DW_OP_implicit_pointer offset in ``.debug_info`` - DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info`` - ================================== =================================== - -Format of Debugging Information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Attribute Encodings -+++++++++++++++++++ + This augments DWARF Version 5 section 7.4 list item 3's table. + +.. table:: ``.debug_info`` section attribute form roles + :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table + + ================================== =================================== + Form Role + ================================== =================================== + DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info`` + ================================== =================================== + +A.7.5 Format of Debugging Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A.7.5.4 Attribute Encodings ++++++++++++++++++++++++++++ .. note:: @@ -4049,16 +4176,25 @@ DW_AT_LLVM_vector_size 0x3e0c constant ================================== ====== =================================== -DWARF Expressions -~~~~~~~~~~~~~~~~~ +.. _amdgpu-dwarf-classes-and-forms: + +A.7.5.5 Classes and Forms ++++++++++++++++++++++++++ + +.. note:: + + The same as in DWARF Version 5 section 7.5.5. + +A.7.7 DWARF Expressions +~~~~~~~~~~~~~~~~~~~~~~~ .. note:: Rename DWARF Version 5 section 7.7 to reflect the unification of location descriptions into DWARF expressions. -Operation Expressions -+++++++++++++++++++++ +A.7.7.1 Operation Expressions ++++++++++++++++++++++++++++++ .. note:: @@ -4096,16 +4232,16 @@ ULEB128 count ================================== ===== ======== =============================== -Location List Expressions -+++++++++++++++++++++++++ +A.7.7.3 Location List Expressions ++++++++++++++++++++++++++++++++++ .. note:: Rename DWARF Version 5 section 7.7.3 to reflect that location lists are a kind of DWARF expression. -Source Languages -~~~~~~~~~~~~~~~~ +A.7.12 Source Languages +~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4122,8 +4258,8 @@ ``DW_LANG_LLVM_HIP`` 0x8100 0 ==================== ====== =================== -Address Class and Address Space Encodings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A.7.13 Address Class and Address Space Encodings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4147,8 +4283,8 @@ ``DW_ADDR_LLVM_hi_user`` 0xffff ========================== ====== -Line Number Information -~~~~~~~~~~~~~~~~~~~~~~~ +A.7.22 Line Number Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4167,8 +4303,8 @@ ``DW_LNCT_LLVM_is_MD5`` 0x2002 ==================================== ==================== -Call Frame Information -~~~~~~~~~~~~~~~~~~~~~~ +A.7.24 Call Frame Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4188,8 +4324,8 @@ DW_CFA_LLVM_def_aspace_cfa_sf 0 0x31 ULEB128 register SLEB128 offset ULEB128 address space ============================= ====== ====== ================ ================ ===================== -Attributes by Tag Value (Informative) -------------------------------------- +A. Attributes by Tag Value (Informative) +---------------------------------------- .. note:: @@ -4219,8 +4355,8 @@ .. _amdgpu-dwarf-examples: -Examples -======== +B. Examples +=========== The AMD GPU specific usage of the features in these extensions, including examples, is available at *User Guide for AMDGPU Backend* section @@ -4235,8 +4371,8 @@ .. _amdgpu-dwarf-references: -References -========== +C. References +============= .. _amdgpu-dwarf-AMD: diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -2016,9 +2016,10 @@ ------------------------------------- This section describes how certain debugger information entry attributes are -used by AMDGPU. See the sections in DWARF Version 5 section 2 which are updated -by *DWARF Extensions For Heterogeneous Debugging* section -:ref:`amdgpu-dwarf-debugging-information-entry-attributes`. +used by AMDGPU. See the sections in DWARF Version 5 section 3.3.5 and 3.1.1 +which are updated by *DWARF Extensions For Heterogeneous Debugging* section +:ref:`amdgpu-dwarf-low-level-information` and +:ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`. .. _amdgpu-dwarf-dw-at-llvm-lane-pc: