diff --git a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst --- a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst +++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst @@ -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 @@ -422,18 +422,28 @@ 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:: + + 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. + +2 General Description +--------------------- -Attribute Types -~~~~~~~~~~~~~~~ +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 -~~~~~~~~~~~~~~~~~ +2.5 DWARF Expressions +~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -506,8 +516,8 @@ .. _amdgpu-dwarf-expression-evaluation-context: -DWARF Expression Evaluation Context -+++++++++++++++++++++++++++++++++++ +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* @@ -707,8 +717,8 @@ .. _amdgpu-dwarf-expression-value: -DWARF Expression Value -++++++++++++++++++++++ +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 +754,8 @@ .. _amdgpu-dwarf-location-description: -DWARF Location Description -++++++++++++++++++++++++++ +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 @@ -884,8 +894,8 @@ .. _amdgpu-dwarf-operation-expressions: -DWARF Operation Expressions -+++++++++++++++++++++++++++ +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 @@ -975,8 +985,12 @@ .. _amdgpu-dwarf-stack-operations: -Stack Operations -################ +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 +1032,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 +1048,12 @@ .. _amdgpu-dwarf-control-flow-operations: -Control Flow Operations -####################### +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 +1115,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 @@ -1234,8 +1252,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,8 +1282,8 @@ .. _amdgpu-dwarf-value-operations: -Value Operations -################ +2.5.4.3 Value Operations +######################## This section describes the operations that push values on the stack. @@ -1277,8 +1295,12 @@ .. _amdgpu-dwarf-literal-operations: -Literal Operations -^^^^^^^^^^^^^^^^^^ +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. @@ -1357,8 +1379,8 @@ .. _amdgpu-dwarf-arithmetic-logical-operations: -Arithmetic and Logical Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.5.4.3.2 Arithmetic and Logical Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -1366,8 +1388,8 @@ .. _amdgpu-dwarf-type-conversions-operations: -Type Conversion Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.5.4.3.3 Type Conversion Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -1375,8 +1397,13 @@ .. _amdgpu-dwarf-general-operations: -Special Value Operations -^^^^^^^^^^^^^^^^^^^^^^^^ +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 +1538,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 +1586,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 +1612,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 +1648,20 @@ .. _amdgpu-dwarf-location-description-operations: -Location Description Operations -############################### +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: + +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* @@ -1688,8 +1721,8 @@ *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.* + location description of a structure prior to evaluation of a* + ``DW_AT_data_member_location`` *to access a data member of a structure.* .. note:: @@ -1717,8 +1750,12 @@ .. _amdgpu-dwarf-undefined-location-description-operations: -Undefined Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 +1776,13 @@ .. _amdgpu-dwarf-memory-location-description-operations: -Memory Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 @@ -1812,7 +1854,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:: @@ -1890,8 +1932,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 +1992,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 +2052,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: + +2.5.4.4.4 Register Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: -Register Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 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 +2108,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: -Implicit Location Description Operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.5.4.4.5 Implicit Location Description Operations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + 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 +2153,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 +2268,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 +2309,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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 +2534,12 @@ .. _amdgpu-dwarf-location-list-expressions: -DWARF Location List Expressions -+++++++++++++++++++++++++++++++ +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 @@ -2596,8 +2654,8 @@ .. _amdgpu-dwarf-segment_addresses: -Segmented Addresses -~~~~~~~~~~~~~~~~~~~ +2.12 Segmented Addresses +~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -2798,493 +2856,514 @@ 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: +3 Program Scope Entries +----------------------- + +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the appropriate DWARF Version 5 + chapter 3 sections. + +3.1 Unit Entries +~~~~~~~~~~~~~~~~ + +.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries: + +3.1.1 Full and Partial Compilation Unit Entries ++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + This augments DWARF Version 5 section 3.1.1 and Table 3.1. + +Additional language codes defined for use with the ``DW_AT_language`` attribute +are defined in :ref:`amdgpu-dwarf-language-names-table`. + +.. table:: Language Names + :name: amdgpu-dwarf-language-names-table + + ==================== ============================= + Language Name Meaning + ==================== ============================= + ``DW_LANG_LLVM_HIP`` HIP Language. + ==================== ============================= + +The HIP language [:ref:`HIP `] can be supported by extending +the C++ language. + +.. note:: + + The following new attribute is added. + +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] -Debugging Information Entry Attributes +3.3 Subroutine and Entry Point Entries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _amdgpu-dwarf-low-level-information: + +3.3.5 Low-Level Information ++++++++++++++++++++++++++++ + +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 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:: - 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. + 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. -1. ``DW_AT_location`` +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. - 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 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. +The DWARF is ill-formed if E contains an ``DW_OP_fbreg`` operation, or the +resulting location description L is not comprised of one single location +description SL. - See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules - used by the ``DW_OP_call*`` operations. +If SL 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. - .. note:: +*This allows the more compact* ``DW_OP_reg*`` *to be used instead of* +``DW_OP_breg* 0``\ *.* - Delete the description of how the ``DW_OP_call*`` operations evaluate a - ``DW_AT_location`` attribute as that is now described in the operations. +.. note:: - .. note:: + This rule could be removed and require the producer to create the required + location description directly using ``DW_OP_call_frame_cfa``, ``DW_OP_breg*``, + or ``DW_OP_LLVM_aspace_bregx``. This would also then allow a target to + implement the call frames within a large register. - 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. +Otherwise, the DWARF is ill-formed if SL is not a memory location description in +any of the target architecture specific address spaces. - 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 resulting L is the *frame base* for the subprogram or entry point. -2. ``DW_AT_const_value`` +*Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a stack +pointer register plus or minus some offset.* - .. note:: +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. - 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. +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. -3. ``DW_AT_frame_base`` +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. - 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. +.. note:: - 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 following new attributes are added. - The DWARF is ill-formed if E contains an ``DW_OP_fbreg`` operation, or the - resulting location description L is not comprised of one single location - description SL. +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. - If SL 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. +If not present, the default value of 1 is used. - *This allows the more compact* ``DW_OPreg*`` *to be used instead of* - ``DW_OP_breg* 0``\ *.* +The DWARF is ill-formed if the value is 0. - .. note:: +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. - This rule could be removed and require the producer to create the required - location description directly using ``DW_OP_call_frame_cfa``, - ``DW_OP_breg*``, or ``DW_OP_LLVM_aspace_bregx``. This would also then - allow a target to implement the call frames within a large register. +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. - Otherwise, the DWARF is ill-formed if SL is not a memory location - description in any of the target architecture specific address spaces. +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 resulting L is the *frame base* for the subprogram or entry point. +``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.* - *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a - stack pointer register plus or minus some offset.* +*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.* -4. ``DW_AT_data_member_location`` +If not present, the thread is not being used in a SIMT manner, and the thread's +current program location is used. - For a ``DW_AT_data_member_location`` attribute there are two cases: +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. - 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 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. - 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. +The DWARF is ill-formed if the resulting value V is not an integral value. - *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 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. - 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. +*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. - 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. - -5. ``DW_AT_use_location`` - - 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. - - *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 ``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. - - 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`` - - 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 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. - - *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.* +3.4 Call Site Entries and Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. note:: +3.4.2 Call Site Parameters +++++++++++++++++++++++++++ - 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. - -7. ``DW_AT_vtable_elem_location`` - - An entry for a virtual function also has a ``DW_AT_vtable_elem_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 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. - -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`` - - 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 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. +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`\ . + +The result of the ``DW_AT_call_value`` attribute is obtained by evaluating E\ +:sub:`1` 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. The resulting value V\ :sub:`1` is the value +of the parameter at the time of the call made by the call site. + +For parameters passed by reference, where the code passes a pointer to a +location which contains the parameter, or for reference type parameters, the +``DW_TAG_call_site_parameter`` debugger information entry may also have a +``DW_AT_call_data_location`` attribute whose value is a DWARF operation +expression E\ :sub:`2`\ , and a ``DW_AT_call_data_value`` attribute whose value +is a DWARF operation expression E\ :sub:`3`\ . + +The value of the ``DW_AT_call_data_location`` attribute is obtained by +evaluating E\ :sub:`2` 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 +resulting location description L\ :sub:`2` is the location where the referenced +parameter lives during the call made by the call site. If E\ :sub:`2` would just +be a ``DW_OP_push_object_address``, then the ``DW_AT_call_data_location`` +attribute may be omitted. + +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 stack, and other +context elements corresponding to the source language thread of execution upon +which the user is focused, if any. The resulting 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 consumer may have to virtually unwind to the call site (see* +:ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these +attributes. This will ensure the source language thread of execution upon which +the user is focused corresponds to the call site needed to evaluate the +expression.* + +If it is not possible to avoid the expressions of these attributes from +accessing registers or memory locations that might be clobbered by the +subprogram being called by the call site, then the associated attribute should +not be provided. + +*The reason for the restriction is that the parameter may need to be accessed +during the execution of the callee. The consumer may virtually unwind from the +called subprogram back to the caller and then evaluate the attribute +expressions. The call frame information (see* +:ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore +registers that have been clobbered, and clobbered memory will no longer have the +value at the time of the call.* + +4 Data Object and Object List Entries +------------------------------------- - .. note:: +.. 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. - -10. ``DW_AT_call_value``, ``DW_AT_call_data_location``, and - ``DW_AT_call_data_value`` - - 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`\ . - - The result of the ``DW_AT_call_value`` attribute is obtained by evaluating - E\ :sub:`1` 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. The resulting value V\ - :sub:`1` is the value of the parameter at the time of the call made by the - call site. - - For parameters passed by reference, where the code passes a pointer to a - location which contains the parameter, or for reference type parameters, the - ``DW_TAG_call_site_parameter`` debugger information entry may also have a - ``DW_AT_call_data_location`` attribute whose value is a DWARF operation - expression E\ :sub:`2`\ , and a ``DW_AT_call_data_value`` attribute whose - value is a DWARF operation expression E\ :sub:`3`\ . - - The value of the ``DW_AT_call_data_location`` attribute is obtained by - evaluating E\ :sub:`2` 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 - resulting location description L\ :sub:`2` is the location where the - referenced parameter lives during the call made by the call site. If E\ - :sub:`2` would just be a ``DW_OP_push_object_address``, then the - ``DW_AT_call_data_location`` attribute may be omitted. - - 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 - stack, and other context elements corresponding to the source language - thread of execution upon which the user is focused, if any. The resulting - 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 consumer may have to virtually unwind to the call site (see* - :ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these - attributes. This will ensure the source language thread of execution upon - which the user is focused corresponds to the call site needed to evaluate - the expression.* - - If it is not possible to avoid the expressions of these attributes from - accessing registers or memory locations that might be clobbered by the - subprogram being called by the call site, then the associated attribute - should not be provided. - - *The reason for the restriction is that the parameter may need to be - accessed during the execution of the callee. The consumer may virtually - unwind from the called subprogram back to the caller and then evaluate the - attribute expressions. The call frame information (see* - :ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore - 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* - - 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. - - If not present, the default value of 1 is used. - - The DWARF is ill-formed if the value is 0. - -12. ``DW_AT_LLVM_lane_pc`` *New* - - 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 empty initial stack, and other context - elements corresponding to the source language thread of execution upon which - the user is focused, if any. - - 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. - - ``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.* - - *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.* - - If not present, the thread is not being used in a SIMT manner, and the - thread's current program location is used. - -13. ``DW_AT_LLVM_active_lane`` *New* - - 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 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 DWARF is ill-formed if the resulting value V is not an integral value. - - 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. - - *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.* - - If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target - architecture execution mask is used. - -14. ``DW_AT_LLVM_vector_size`` *New* - - 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. - - The representation of a vector base type is as N contiguous elements, each - one having the representation of a base type T' that is the same as T - without the ``DW_AT_LLVM_vector_size`` attribute. - - If a ``DW_TAG_base_type`` debugger information entry does not have a - ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector - type. + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the appropriate DWARF Version 5 + chapter 4 sections. - The DWARF is ill-formed if N is not greater than 0. +4.1 Data Object Entries +~~~~~~~~~~~~~~~~~~~~~~~ - .. note:: +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. - LLVM has mention of a non-upstreamed debugger information entry that is - intended to support vector types. However, that was not for a base type so - would not be suitable as the type of a stack value entry. But perhaps that - could be replaced by using this attribute. +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. -15. ``DW_AT_LLVM_augmentation`` *New* +See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules +used by the ``DW_OP_call*`` operations. - 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. +.. note:: - *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.* + 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, or if the string is empty, then the compilation unit has no - augmentation string. +.. note:: - The format for the augmentation string is: + 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. - | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * + 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. - 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. +.. note:: - For example: + 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. - :: +5 Type Entries +-------------- - [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] +.. note:: -Program Scope Entities ----------------------- + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the appropriate DWARF Version 5 + chapter 5 sections. -.. _amdgpu-dwarf-language-names: +.. _amdgpu-dwarf-base-type-entries: -Unit Entities -~~~~~~~~~~~~~ +5.1 Base Type Entries +~~~~~~~~~~~~~~~~~~~~~ .. note:: - This augments DWARF Version 5 section 3.1.1 and Table 3.1. + The following new attribute is added. -Additional language codes defined for use with the ``DW_AT_language`` attribute -are defined in :ref:`amdgpu-dwarf-language-names-table`. +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. -.. table:: Language Names - :name: amdgpu-dwarf-language-names-table +The representation of a vector base type is as N contiguous elements, each one +having the representation of a base type T' that is the same as T without the +``DW_AT_LLVM_vector_size`` attribute. - ==================== ============================= - Language Name Meaning - ==================== ============================= - ``DW_LANG_LLVM_HIP`` HIP Language. - ==================== ============================= +If a ``DW_TAG_base_type`` debugger information entry does not have a +``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector type. -The HIP language [:ref:`HIP `] can be supported by extending -the C++ language. +The DWARF is ill-formed if N is not greater than 0. + +.. note:: + + LLVM has mention of a non-upstreamed debugger information entry that is + intended to support vector types. However, that was not for a base type so + would not be suitable as the type of a stack value entry. But perhaps that + could be replaced by using this attribute. + +5.7 Structure, Union, Class and Interface Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +5.7.3 Derived or Extended Structures, Classes and Interfaces +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +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. + + *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.* -Other Debugger Information --------------------------- +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. -Accelerated Access -~~~~~~~~~~~~~~~~~~ +.. 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. + +5.7.8 Member Function Entries ++++++++++++++++++++++++++++++ + +An entry for a virtual function also has a ``DW_AT_vtable_elem_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 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. + +5.14 Pointer to Member Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +*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 ``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. + +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. + +5.16 Dynamic Type Entries +~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 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. + +*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. + +6 Other Debugging Information +----------------------------- + +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the appropriate DWARF Version 5 + chapter 6 sections. + +6.1 Accelerated Access +~~~~~~~~~~~~~~~~~~~~~~ .. _amdgpu-dwarf-lookup-by-name: -Lookup By Name -++++++++++++++ +6.1.1 Lookup By Name +++++++++++++++++++++ -Contents of the Name Index -########################## +6.1.1.1 Contents of the Name Index +################################## .. note:: @@ -3304,11 +3383,11 @@ or ``DW_OP_form_tls_address`` operation are included; otherwise, they are excluded. -Data Representation of the Name Index -##################################### +6.1.1.4 Data Representation of the Name Index +############################################# -Section Header -^^^^^^^^^^^^^^ +6.1.1.4.1 Section Header +^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -3342,14 +3421,14 @@ .. _amdgpu-dwarf-line-number-information: -Line Number Information -~~~~~~~~~~~~~~~~~~~~~~~ +6.2 Line Number Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Line Number Program Header -++++++++++++++++++++++++++++++ +6.2.4 The Line Number Program Header +++++++++++++++++++++++++++++++++++++ -Standard Content Descriptions -############################# +6.2.4.1 Standard Content Descriptions +##################################### .. note:: @@ -3392,8 +3471,8 @@ .. _amdgpu-dwarf-call-frame-information: -Call Frame Information -~~~~~~~~~~~~~~~~~~~~~~ +6.4 Call Frame Information +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -3403,12 +3482,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 -+++++++++++++++++++++++++++++++++++ +6.4.1 Structure of Call Frame Information ++++++++++++++++++++++++++++++++++++++++++ The register rules are: @@ -3682,8 +3761,8 @@ .. _amdgpu-dwarf-call-frame-instructions: -Call Frame Instructions -+++++++++++++++++++++++ +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 +3799,8 @@ .. _amdgpu-dwarf-row-creation-instructions: -Row Creation Instructions -######################### +6.4.2.1 Row Creation Instructions +################################# .. note:: @@ -3729,8 +3808,8 @@ .. _amdgpu-dwarf-cfa-definition-instructions: -CFA Definition Instructions -########################### +6.4.2.2 CFA Definition Instructions +################################### 1. ``DW_CFA_def_cfa`` @@ -3748,7 +3827,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 +3852,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 +3889,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 +3916,8 @@ .. _amdgpu-dwarf-register-rule-instructions: -Register Rule Instructions -########################## +6.4.2.3 Register Rule Instructions +################################## 1. ``DW_CFA_undefined`` @@ -3857,7 +3936,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 +3967,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 +4037,22 @@ to ``DW_CFA_restore``, except for the encoding and size of the register operand. -Row State Instructions -###################### +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 -################### +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 -++++++++++++++++++++++++++++ +6.4.3 Call Frame Instruction Usage +++++++++++++++++++++++++++++++++++ .. note:: @@ -3981,20 +4060,26 @@ .. _amdgpu-dwarf-call-frame-calling-address: -Call Frame Calling Address -++++++++++++++++++++++++++ +6.4.4 Call Frame Calling Address +++++++++++++++++++++++++++++++++ .. note:: The same as in DWARF Version 5 section 6.4.4. -Data Representation -------------------- +7 Data Representation +--------------------- + +.. note:: + + This section provides changes to existing debugger information entry + attributes. These would be incorporated into the appropriate DWARF Version 5 + chapter 7 sections. .. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats: -32-Bit and 64-Bit DWARF Formats -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +7.4 32-Bit and 64-Bit DWARF Formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4023,11 +4108,11 @@ DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info`` ================================== =================================== -Format of Debugging Information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +7.5 Format of Debugging Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Attribute Encodings -+++++++++++++++++++ +7.5.4 Attribute Encodings ++++++++++++++++++++++++++ .. note:: @@ -4049,16 +4134,16 @@ DW_AT_LLVM_vector_size 0x3e0c constant ================================== ====== =================================== -DWARF Expressions -~~~~~~~~~~~~~~~~~ +7.7 DWARF Expressions +~~~~~~~~~~~~~~~~~~~~~ .. note:: Rename DWARF Version 5 section 7.7 to reflect the unification of location descriptions into DWARF expressions. -Operation Expressions -+++++++++++++++++++++ +7.7.1 Operation Expressions ++++++++++++++++++++++++++++ .. note:: @@ -4096,16 +4181,16 @@ ULEB128 count ================================== ===== ======== =============================== -Location List Expressions -+++++++++++++++++++++++++ +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 -~~~~~~~~~~~~~~~~ +7.12 Source Languages +~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4122,8 +4207,8 @@ ``DW_LANG_LLVM_HIP`` 0x8100 0 ==================== ====== =================== -Address Class and Address Space Encodings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +7.13 Address Class and Address Space Encodings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4147,8 +4232,8 @@ ``DW_ADDR_LLVM_hi_user`` 0xffff ========================== ====== -Line Number Information -~~~~~~~~~~~~~~~~~~~~~~~ +7.22 Line Number Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4167,8 +4252,8 @@ ``DW_LNCT_LLVM_is_MD5`` 0x2002 ==================================== ==================== -Call Frame Information -~~~~~~~~~~~~~~~~~~~~~~ +7.24 Call Frame Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -4188,8 +4273,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:: 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: