5383 lines · plain
1.. _amdgpu-dwarf-extensions-for-heterogeneous-debugging:2 3********************************************4DWARF Extensions For Heterogeneous Debugging5********************************************6 7.. contents::8 :local:9 10.. warning::11 12 This document describes **provisional extensions** to DWARF Version 513 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] to support heterogeneous debugging. It is14 not currently fully implemented and is subject to change.15 16.. _amdgpu-dwarf-introduction:17 181. Introduction19===============20 21AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] has been working on supporting heterogeneous22computing. A heterogeneous computing program can be written in a high level23language such as C++ or Fortran with OpenMP pragmas, OpenCL, or HIP (a portable24C++ programming environment for heterogeneous computing [:ref:`HIP25<amdgpu-dwarf-HIP>`]). A heterogeneous compiler and runtime allows a program to26execute on multiple devices within the same native process. Devices could27include CPUs, GPUs, DSPs, FPGAs, or other special purpose accelerators.28Currently HIP programs execute on systems with CPUs and GPUs.29 30The AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] ROCm platform [:ref:`AMD-ROCm31<amdgpu-dwarf-AMD-ROCm>`] is an implementation of the industry standard for32heterogeneous computing devices defined by the Heterogeneous System Architecture33(HSA) Foundation [:ref:`HSA <amdgpu-dwarf-HSA>`]. It is open sourced and34includes contributions to open source projects such as LLVM [:ref:`LLVM35<amdgpu-dwarf-LLVM>`] for compilation and GDB for debugging [:ref:`GDB36<amdgpu-dwarf-GDB>`].37 38The LLVM compiler has upstream support for commercially available AMD GPU39hardware (AMDGPU) [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The open40source ROCgdb [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`] GDB-based debugger41also has support for AMDGPU which is being upstreamed. Support for AMDGPU is42also being added by third parties to the GCC [:ref:`GCC <amdgpu-dwarf-GCC>`]43compiler and the Perforce TotalView HPC Debugger [:ref:`Perforce-TotalView44<amdgpu-dwarf-Perforce-TotalView>`].45 46To support debugging heterogeneous programs, several features that are not47provided by current DWARF Version 5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] have48been identified. The :ref:`amdgpu-dwarf-extensions` section gives an overview of49the extensions devised to address the missing features. The extensions seek to50be general in nature and backwards compatible with DWARF Version 5. Their goal51is to be applicable to meeting the needs of any heterogeneous system and not be52vendor or architecture specific. That is followed by appendix53:ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` which contains the54textual changes for the extensions relative to the DWARF Version 5 standard.55There are a number of notes included that raise open questions, or provide56alternative approaches that may be worth considering. Then appendix57:ref:`amdgpu-dwarf-further-examples` links to the AMD GPU specific usage of the58extensions that includes an example. Finally, appendix59:ref:`amdgpu-dwarf-references` provides references to further information.60 61.. _amdgpu-dwarf-extensions:62 632. Extensions64=============65 66The extensions continue to evolve through collaboration with many individuals and67active prototyping within the GDB debugger and LLVM compiler. Input has also68been very much appreciated from the developers working on the Perforce TotalView69HPC Debugger and GCC compiler.70 71The inputs provided and insights gained so far have been incorporated into this72current version. The plan is to participate in upstreaming the work and73addressing any feedback. If there is general interest then some or all of these74extensions could be submitted as future DWARF standard proposals.75 76The general principles in designing the extensions have been:77 781. Be backwards compatible with the DWARF Version 5 [:ref:`DWARF79 <amdgpu-dwarf-DWARF>`] standard.80 812. Be vendor and architecture neutral. They are intended to apply to other82 heterogeneous hardware devices including GPUs, DSPs, FPGAs, and other83 specialized hardware. These collectively include similar characteristics and84 requirements as AMDGPU devices.85 863. Provide improved optimization support for non-GPU code. For example, some87 extensions apply to traditional CPU hardware that supports large vector88 registers. Compilers can map source languages, and source language89 extensions, that describe large scale parallel execution, onto the lanes of90 the vector registers. This is common in programming languages used in ML and91 HPC.92 934. Fully define well-formed DWARF in a consistent style based on the DWARF94 Version 5 specification.95 96It is possible that some of the generalizations may also benefit other DWARF97issues that have been raised.98 99The remainder of this section enumerates the extensions and provides motivation100for each in terms of heterogeneous debugging.101 102.. _amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack:103 1042.1 Allow Location Description on the DWARF Expression Stack105------------------------------------------------------------106 107DWARF Version 5 does not allow location descriptions to be entries on the DWARF108expression stack. They can only be the final result of the evaluation of a DWARF109expression. However, by allowing a location description to be a first-class110entry on the DWARF expression stack, it becomes possible to compose expressions111containing both values and location descriptions naturally. It allows objects to112be located in any kind of memory address space, in registers, be implicit113values, be undefined, or a composite of any of these.114 115By extending DWARF carefully, all existing DWARF expressions can retain their116current semantic meaning. DWARF has implicit conversions that convert from a117value that represents an address in the default address space to a memory118location description. This can be extended to allow a default address space119memory location description to be implicitly converted back to its address120value. This allows all DWARF Version 5 expressions to retain their same meaning,121while enabling the ability to explicitly create memory location descriptions in122non-default address spaces and generalizing the power of composite location123descriptions to any kind of location description.124 125For those familiar with the definition of location descriptions in DWARF Version1265, the definitions in these extensions are presented differently, but do in127fact define the same concept with the same fundamental semantics. However, it128does so in a way that allows the concept to extend to support address spaces,129bit addressing, the ability for composite location descriptions to be composed130of any kind of location description, and the ability to support objects located131at multiple places. Collectively these changes expand the set of architectures132that can be supported and improve support for optimized code.133 134Several approaches were considered, and the one presented, together with the135extensions it enables, appears to be the simplest and cleanest one that offers136the greatest improvement of DWARF's ability to support debugging optimized GPU137and non-GPU code. Examining the GDB debugger and LLVM compiler, it appears only138to require modest changes as they both already have to support general use of139location descriptions. It is anticipated that this will also be the case for other140debuggers and compilers.141 142GDB has been modified to evaluate DWARF Version 5 expressions with location143descriptions as stack entries and with implicit conversions. All GDB tests have144passed, except one that turned out to be an invalid test case by DWARF Version 5145rules. The code in GDB actually became simpler as all evaluation is done on a146single stack and there was no longer a need to maintain a separate structure for147the location description results. This gives confidence in backwards148compatibility.149 150See :ref:`amdgpu-dwarf-expressions` and nested sections.151 152This extension is separately described at *Allow Location Descriptions on the153DWARF Expression Stack* [:ref:`AMDGPU-DWARF-LOC154<amdgpu-dwarf-AMDGPU-DWARF-LOC>`].155 1562.2 Generalize CFI to Allow Any Location Description Kind157---------------------------------------------------------158 159CFI describes restoring callee saved registers that are spilled. Currently, CFI160only allows a location description that is a register, memory address, or161implicit location description. AMDGPU optimized code may spill scalar registers162into portions of vector registers. This requires extending CFI to allow any163location description kind to be supported.164 165See :ref:`amdgpu-dwarf-call-frame-information`.166 1672.3 Generalize DWARF Operation Expressions to Support Multiple Places168---------------------------------------------------------------------169 170In DWARF Version 5 a location description is defined as a single location171description or a location list. A location list is defined as either172effectively an undefined location description or as one or more single173location descriptions to describe an object with multiple places.174 175With176:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`,177the ``DW_OP_push_object_address`` and ``DW_OP_call*`` operations can put a178location description on the stack. Furthermore, debugger information entry179attributes such as ``DW_AT_data_member_location``, ``DW_AT_use_location``, and180``DW_AT_vtable_elem_location`` are defined as pushing a location description on181the expression stack before evaluating the expression.182 183DWARF Version 5 only allows the stack to contain values and so only a single184memory address can be on the stack. This makes these operations and attributes185incapable of handling location descriptions with multiple places, or places186other than memory.187 188Since189:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`190allows the stack to contain location descriptions, the operations are191generalized to support location descriptions that can have multiple places. This192is backwards compatible with DWARF Version 5 and allows objects with multiple193places to be supported. For example, the expression that describes how to access194the field of an object can be evaluated with a location description that has195multiple places and will result in a location description with multiple places.196 197With this change, the separate DWARF Version 5 sections that described DWARF198expressions and location lists are unified into a single section that describes199DWARF expressions in general. This unification is a natural consequence of, and200a necessity of, allowing location descriptions to be part of the evaluation201stack.202 203See :ref:`amdgpu-dwarf-location-description`.204 2052.4 Generalize Offsetting of Location Descriptions206--------------------------------------------------207 208The ``DW_OP_plus`` and ``DW_OP_minus`` operations can be defined to operate on a209memory location description in the default target architecture specific address210space and a generic type value to produce an updated memory location211description. This allows them to continue to be used to offset an address.212 213To generalize offsetting to any location description, including location214descriptions that describe when bytes are in registers, are implicit, or a215composite of these, the ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and216``DW_OP_LLVM_bit_offset`` offset operations are added.217 218The offset operations can operate on location storage of any size. For example,219implicit location storage could be any number of bits in size. It is simpler to220define offsets that exceed the size of the location storage as being an221evaluation error, than having to force an implementation to support potentially222infinite precision offsets to allow it to correctly track a series of positive223and negative offsets that may transiently overflow or underflow, but end up in224range. This is simple for the arithmetic operations as they are defined in terms225of two's complement arithmetic on a base type of a fixed size. Therefore, the226offset operation defines that integer overflow is ill-formed. This is in contrast227to the ``DW_OP_plus``, ``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic228operations which define that it causes wrap-around.229 230Having the offset operations allows ``DW_OP_push_object_address`` to push a231location description that may be in a register, or be an implicit value. The232DWARF expression of ``DW_TAG_ptr_to_member_type`` can use the offset operations233without regard to what kind of location description was pushed.234 235Since236:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` has237generalized location storage to be bit indexable, ``DW_OP_LLVM_bit_offset``238generalizes DWARF to work with bit fields. This is generally not possible in239DWARF Version 5.240 241The ``DW_OP_*piece`` operations only allow literal indices. A way to use a242computed offset of an arbitrary location description (such as a vector register)243is required. The offset operations provide this ability since they can be used244to compute a location description on the stack.245 246It could be possible to define ``DW_OP_plus``, ``DW_OP_plus_uconst``, and247``DW_OP_minus`` to operate on location descriptions to avoid needing248``DW_OP_LLVM_offset`` and ``DW_OP_LLVM_offset_uconst``. However, this is not249proposed since currently the arithmetic operations are defined to require values250of the same base type and produces a result with the same base type. Allowing251these operations to act on location descriptions would permit the first operand252to be a location description and the second operand to be an integral value253type, or vice versa, and return a location description. This complicates the254rules for implicit conversions between default address space memory location255descriptions and generic base type values. Currently the rules would convert256such a location description to the memory address value and then perform two's257compliment wrap around arithmetic. If the result was used as a location258description, it would be implicitly converted back to a default address space259memory location description. This is different to the overflow rules on location260descriptions. To allow control, an operation that converts a memory location261description to an address integral type value would be required. Keeping a262separation of location description operations and arithmetic operations avoids263this semantic complexity.264 265See ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and266``DW_OP_LLVM_bit_offset`` in267:ref:`amdgpu-dwarf-general-location-description-operations`.268 2692.5 Generalize Creation of Undefined Location Descriptions270----------------------------------------------------------271 272Current DWARF uses an empty expression to indicate an undefined location273description. Since274:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`275allows location descriptions to be created on the stack, it is necessary to have276an explicit way to specify an undefined location description.277 278For example, the ``DW_OP_LLVM_select_bit_piece`` (see279:ref:`amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware`)280operation takes more than one location description on the stack. Without this281ability, it is not possible to specify that a particular one of the input282location descriptions is undefined.283 284See the ``DW_OP_LLVM_undefined`` operation in285:ref:`amdgpu-dwarf-undefined-location-description-operations`.286 2872.6 Generalize Creation of Composite Location Descriptions288----------------------------------------------------------289 290To allow composition of composite location descriptions, an explicit operation291that indicates the end of the definition of a composite location description is292required. This can be implied if the end of a DWARF expression is reached,293allowing current DWARF expressions to remain legal.294 295See ``DW_OP_LLVM_piece_end`` in296:ref:`amdgpu-dwarf-composite-location-description-operations`.297 2982.7 Generalize DWARF Base Objects to Allow Any Location Description Kind299------------------------------------------------------------------------300 301The number of registers and the cost of memory operations is much higher for302AMDGPU than a typical CPU. The compiler attempts to optimize whole variables and303arrays into registers.304 305Currently DWARF only allows ``DW_OP_push_object_address`` and related operations306to work with a global memory location. To support AMDGPU optimized code it is307required to generalize DWARF to allow any location description to be used. This308allows registers, or composite location descriptions that may be a mixture of309memory, registers, or even implicit values.310 311See ``DW_OP_push_object_address`` in312:ref:`amdgpu-dwarf-general-location-description-operations`.313 3142.8 General Support for Address Spaces315--------------------------------------316 317AMDGPU needs to be able to describe addresses that are in different kinds of318memory. Optimized code may need to describe a variable that resides in pieces319that are in different kinds of storage which may include parts of registers,320memory that is in a mixture of memory kinds, implicit values, or be undefined.321 322DWARF has the concept of segment addresses. However, the segment cannot be323specified within a DWARF expression, which is only able to specify the offset324portion of a segment address. The segment index is only provided by the entity325that specifies the DWARF expression. Therefore, the segment index is a property326that can only be put on complete objects, such as a variable. That makes it only327suitable for describing an entity (such as variable or subprogram code) that is328in a single kind of memory.329 330AMDGPU uses multiple address spaces. For example, a variable may be allocated in331a register that is partially spilled to the call stack which is in the private332address space, and partially spilled to the local address space. DWARF mentions333address spaces, for example as an argument to the ``DW_OP_xderef*`` operations.334A new section that defines address spaces is added (see335:ref:`amdgpu-dwarf-address-spaces`).336 337A new attribute ``DW_AT_LLVM_address_space`` is added to pointer and reference338types (see :ref:`amdgpu-dwarf-type-modifier-entries`). This allows the compiler339to specify which address space is being used to represent the pointer or340reference type.341 342DWARF uses the concept of an address in many expression operations but does not343define how it relates to address spaces. For example,344``DW_OP_push_object_address`` pushes the address of an object. Other contexts345implicitly push an address on the stack before evaluating an expression. For346example, the ``DW_AT_use_location`` attribute of the347``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type348which may apply to objects allocated in different kinds of storage. Therefore,349it is desirable that the expression that uses the address can do so without350regard to what kind of storage it specifies, including the address space of a351memory location description. For example, a pointer to member value may want to352be applied to an object that may reside in any address space.353 354The DWARF ``DW_OP_xderef*`` operations allow a value to be converted into an355address of a specified address space which is then read. But it provides no356way to create a memory location description for an address in the non-default357address space. For example, AMDGPU variables can be allocated in the local358address space at a fixed address.359 360The ``DW_OP_LLVM_form_aspace_address`` (see361:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is defined362to create a memory location description from an address and address space. It363can be used to specify the location of a variable that is allocated in a364specific address space. This allows the size of addresses in an address space to365be larger than the generic type. It also allows a consumer great implementation366freedom. It allows the implicit conversion back to a value to be limited only to367the default address space to maintain compatibility with DWARF Version 5. For368other address spaces the producer can use the new operations that explicitly369specify the address space.370 371In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been372defined to produce a value, and an implicit conversion to a memory location373description was defined, then it would be limited to the size of the generic374type (which matches the size of the default address space). An implementation375would likely have to use *reserved ranges* of values to represent different376address spaces. Such a value would likely not match any address value in the377actual hardware. That would require the consumer to have special treatment for378such values.379 380``DW_OP_breg*`` treats the register as containing an address in the default381address space. A ``DW_OP_LLVM_aspace_bregx`` (see382:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is added383to allow the address space of the address held in a register to be specified.384 385Similarly, ``DW_OP_implicit_pointer`` treats its implicit pointer value as being386in the default address space. A ``DW_OP_LLVM_aspace_implicit_pointer``387(:ref:`amdgpu-dwarf-implicit-location-description-operations`) operation is388added to allow the address space to be specified.389 390Almost all uses of addresses in DWARF are limited to defining location391descriptions, or to be dereferenced to read memory. The exception is392``DW_CFA_val_offset`` which uses the address to set the value of a register. In393order to support address spaces, the CFA DWARF expression is defined to be a394memory location description. This allows it to specify an address space which is395used to convert the offset address back to an address in that address space. See396:ref:`amdgpu-dwarf-call-frame-information`.397 398This approach of extending memory location descriptions to support address399spaces, allows all existing DWARF Version 5 expressions to have the identical400semantics. It allows the compiler to explicitly specify the address space it is401using. For example, a compiler could choose to access private memory in a402swizzled manner when mapping a source language thread to the lane of a wavefront403in a SIMT manner. Or a compiler could choose to access it in an unswizzled404manner if mapping the same language with the wavefront being the thread.405 406It also allows the compiler to mix the address space it uses to access private407memory. For example, for SIMT it can still spill entire vector registers in an408unswizzled manner, while using a swizzled private memory for SIMT variable409access.410 411This approach also allows memory location descriptions for different address412spaces to be combined using the regular ``DW_OP_*piece`` operations.413 414Location descriptions are an abstraction of storage. They give freedom to the415consumer on how to implement them. They allow the address space to encode lane416information so they can be used to read memory with only the memory location417description and no extra information. The same set of operations can operate on418locations independent of their kind of storage. The ``DW_OP_deref*`` therefore419can be used on any storage kind, including memory location descriptions of420different address spaces. Therefore, the ``DW_OP_xderef*`` operations are421unnecessary, except to become a more compact way to encode a non-default address422space address followed by dereferencing it. See423:ref:`amdgpu-dwarf-general-operations`.424 4252.9 Support for Vector Base Types426---------------------------------427 428The vector registers of the AMDGPU are represented as their full wavefront429size, meaning the wavefront size times the dword size. This reflects the430actual hardware and allows the compiler to generate DWARF for languages that431map a thread to the complete wavefront. It also allows more efficient DWARF to432be generated to describe the CFI as only a single expression is required for433the whole vector register, rather than a separate expression for each lane's434dword of the vector register. It also allows the compiler to produce DWARF435that indexes the vector register if it spills scalar registers into portions436of a vector register.437 438Since DWARF stack value entries have a base type and AMDGPU registers are a439vector of dwords, the ability to specify that a base type is a vector is440required.441 442See ``DW_AT_LLVM_vector_size`` in :ref:`amdgpu-dwarf-base-type-entries`.443 444.. _amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions:445 4462.10 DWARF Operations to Create Vector Composite Location Descriptions447----------------------------------------------------------------------448 449AMDGPU optimized code may spill vector registers to non-global address space450memory, and this spilling may be done only for SIMT lanes that are active on451entry to the subprogram. To support this the CFI rule for the partially spilled452register needs to use an expression that uses the EXEC register as a bit mask to453select between the register (for inactive lanes) and the stack spill location454(for active lanes that are spilled). This needs to evaluate to a location455description, and not a value, as a debugger needs to change the value if the456user assigns to the variable.457 458Another usage is to create an expression that evaluates to provide a vector of459logical PCs for active and inactive lanes in a SIMT execution model. Again the460EXEC register is used to select between active and inactive PC values. In order461to represent a vector of PC values, a way to create a composite location462description that is a vector of a single location is used.463 464It may be possible to use existing DWARF to incrementally build the composite465location description, possibly using the DWARF operations for control flow to466create a loop. However, for the AMDGPU that would require loop iteration of 64.467A concern is that the resulting DWARF would have a significant size and would be468reasonably common as it is needed for every vector register that is spilled in a469function. AMDGPU can have up to 512 vector registers. Another concern is the470time taken to evaluate such non-trivial expressions repeatedly.471 472To avoid these issues, a composite location description that can be created as a473masked select is proposed. In addition, an operation that creates a composite474location description that is a vector on another location description is needed.475These operations generate the composite location description using a single476DWARF operation that combines all lanes of the vector in one step. The DWARF477expression is more compact, and can be evaluated by a consumer far more478efficiently.479 480An example that uses these operations is referenced in the481:ref:`amdgpu-dwarf-further-examples` appendix.482 483See ``DW_OP_LLVM_select_bit_piece`` and ``DW_OP_LLVM_extend`` in484:ref:`amdgpu-dwarf-composite-location-description-operations`.485 4862.11 DWARF Operation to Access Call Frame Entry Registers487---------------------------------------------------------488 489As described in490:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`,491a DWARF expression involving the set of SIMT lanes active on entry to a492subprogram is required. The SIMT active lane mask may be held in a register that493is modified as the subprogram executes. However, its value may be saved on entry494to the subprogram.495 496The Call Frame Information (CFI) already encodes such register saving, so it is497more efficient to provide an operation to return the location of a saved498register than have to generate a loclist to describe the same information. This499is now possible since500:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`501allows location descriptions on the stack.502 503See ``DW_OP_LLVM_call_frame_entry_reg`` in504:ref:`amdgpu-dwarf-general-location-description-operations` and505:ref:`amdgpu-dwarf-call-frame-information`.506 5072.12 Support for Source Languages Mapped to SIMT Hardware508---------------------------------------------------------509 510If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner,511then the variable DWARF location expressions must compute the location for a512single lane of the wavefront. Therefore, a DWARF operation is required to denote513the current lane, much like ``DW_OP_push_object_address`` denotes the current514object. See ``DW_OP_LLVM_push_lane`` in :ref:`amdgpu-dwarf-literal-operations`.515 516In addition, a way is needed for the compiler to communicate how many source517language threads of execution are mapped to a target architecture thread's SIMT518lanes. See ``DW_AT_LLVM_lanes`` in :ref:`amdgpu-dwarf-low-level-information`.519 520.. _amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware:521 5222.13 Support for Divergent Control Flow of SIMT Hardware523--------------------------------------------------------524 525If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner the526compiler can use the AMDGPU execution mask register to control which lanes are527active. To describe the conceptual location of non-active lanes requires an528attribute that has an expression that computes the source location PC for each529lane.530 531For efficiency, the expression calculates the source location of the wavefront as a532whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see533:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`)534operation.535 536The AMDGPU may update the execution mask to perform whole wavefront operations.537Therefore, there is a need for an attribute that computes the current active538lane mask. This can have an expression that may evaluate to the SIMT active lane539mask register or to a saved mask when in whole wavefront execution mode.540 541An example that uses these attributes is referenced in the542:ref:`amdgpu-dwarf-further-examples` appendix.543 544See ``DW_AT_LLVM_lane_pc`` and ``DW_AT_LLVM_active_lane`` in545:ref:`amdgpu-dwarf-composite-location-description-operations`.546 5472.14 Define Source Language Memory Classes548-------------------------------------------549 550AMDGPU supports languages, such as OpenCL [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`],551that define source language memory classes. Support is added to define language552specific memory spaces so they can be used in a consistent way by consumers.553 554Support for using memory spaces in defining source language types and data555object allocation is also added.556 557See :ref:`amdgpu-dwarf-memory-spaces`.558 5592.15 Define Augmentation Strings to Support Multiple Extensions560---------------------------------------------------------------561 562A ``DW_AT_LLVM_augmentation`` attribute is added to a compilation unit debugger563information entry to indicate that there is additional target architecture564specific information in the debugging information entries of that compilation565unit. This allows a consumer to know what extensions are present in the debugger566information entries as is possible with the augmentation string of other567sections.568 569The format that should be used for an augmentation string is also recommended.570This allows a consumer to parse the string when it contains information from571multiple vendors. Augmentation strings occur in the ``DW_AT_LLVM_augmentation``572attribute, in the lookup by name table, and in the CFI Common Information Entry573(CIE).574 575See :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`,576:ref:`amdgpu-dwarf-name-index-section-header`, and577:ref:`amdgpu-dwarf-structure_of-call-frame-information`.578 5792.16 Support Embedding Source Text for Online Compilation580---------------------------------------------------------581 582AMDGPU supports programming languages that include online compilation where the583source text may be created at runtime. For example, the OpenCL and HIP language584runtimes support online compilation. To support this, a way to embed the source585text in the debug information is provided.586 587See :ref:`amdgpu-dwarf-line-number-information`.588 5892.17 Allow MD5 Checksums to be Optionally Present590-------------------------------------------------591 592In DWARF Version 5, the file timestamp and file size can be optional, but if the593MD5 checksum is present, it must be valid for all files. This is a problem if594using link time optimization to combine compilation units where some have MD5595checksums, and others do not. Therefore, the line table is extended to allow MD5596checksums to be optional.597 598See :ref:`amdgpu-dwarf-line-number-information`.599 6002.18 Add the HIP Programming Language601-------------------------------------602 603The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported604by the AMDGPU, is added.605 606See :ref:`amdgpu-dwarf-language-names-table`.607 6082.19 Support for Source Language Optimizations that Result in Concurrent Iteration Execution609--------------------------------------------------------------------------------------------610 611A compiler can perform loop optimizations that result in the generated code612executing multiple iterations concurrently. For example, software pipelining613schedules multiple iterations in an interleaved fashion to allow the614instructions of one iteration to hide the latencies of the instructions of615another iteration. Another example is vectorization that can exploit SIMD616hardware to allow a single instruction to execute multiple iterations using617vector registers.618 619Note that although this is similar to SIMT execution, the way a client debugger620uses the information is fundamentally different. In SIMT execution, the debugger621needs to present the concurrent execution as distinct source language threads622that the user can list and switch focus between. With iteration concurrency623optimizations, such as software pipelining and vectorized SIMD, the debugger624must not present the concurrency as distinct source language threads. Instead,625it must inform the user that multiple loop iterations are executing in parallel626and allow the user to select between them.627 628In general, SIMT execution fixes the number of concurrent executions per target629architecture thread. However, both software pipelining and SIMD vectorization630may vary the number of concurrent iterations for different loops executed by a631single source language thread.632 633It is possible for the compiler to use both SIMT concurrency and iteration634concurrency techniques in the code of a single source language thread.635 636Therefore, a DWARF operation is required to denote the current concurrent637iteration instance, much like ``DW_OP_push_object_address`` denotes the current638object. See ``DW_OP_LLVM_push_iteration`` in639:ref:`amdgpu-dwarf-literal-operations`.640 641In addition, a way is needed for the compiler to communicate how many source642language loop iterations are executing concurrently. See643``DW_AT_LLVM_iterations`` in :ref:`amdgpu-dwarf-low-level-information`.644 6452.20 DWARF Operation to Create Runtime Overlay Composite Location Description646-----------------------------------------------------------------------------647 648It is common in SIMD vectorization for the compiler to generate code that649promotes portions of an array into vector registers. For example, if the650hardware has vector registers with 8 elements, and 8 wide SIMD instructions, the651compiler may vectorize a loop so that it executes 8 iterations concurrently for652each vectorized loop iteration.653 654On the first iteration of the generated vectorized loop, iterations 0 to 7 of655the source language loop will be executed using SIMD instructions. Then on the656next iteration of the generated vectorized loop, iteration 8 to 15 will be657executed, and so on.658 659If the source language loop accesses an array element based on the loop660iteration index, the compiler may read the element into a register for the661duration of that iteration. Next iteration it will read the next element into662the register, and so on. With SIMD, this generalizes to the compiler reading663array elements 0 to 7 into a vector register on the first vectorized loop664iteration, then array elements 8 to 15 on the next iteration, and so on.665 666The DWARF location description for the array needs to express that all elements667are in memory, except the slice that has been promoted to the vector register.668The starting position of the slice is a runtime value based on the iteration669index modulo the vectorization size. This cannot be expressed by ``DW_OP_piece``670and ``DW_OP_bit_piece`` which only allow constant offsets to be expressed.671 672Therefore, a new operator is defined that takes two location descriptions, an673offset and a size, and creates a composite that effectively uses the second674location description as an overlay of the first, positioned according to the675offset and size. See ``DW_OP_LLVM_overlay`` and ``DW_OP_LLVM_bit_overlay`` in676:ref:`amdgpu-dwarf-composite-location-description-operations`.677 678Consider an array that has been partially registerized such that the currently679processed elements are held in registers, whereas the remainder of the array680remains in memory. Consider the loop in this C function, for example:681 682.. code::683 :number-lines:684 685 extern void foo(uint32_t dst[], uint32_t src[], int len) {686 for (int i = 0; i < len; ++i)687 dst[i] += src[i];688 }689 690Inside the loop body, the machine code loads ``src[i]`` and ``dst[i]`` into691registers, adds them, and stores the result back into ``dst[i]``.692 693Considering the location of ``dst`` and ``src`` in the loop body, the elements694``dst[i]`` and ``src[i]`` would be located in registers; all other elements are695located in memory. Let register ``R0`` contain the base address of ``dst``,696register ``R1`` contain ``i``, and register ``R2`` contain the registerized697``dst[i]`` element. We can describe the location of ``dst`` as a memory location698with a register location overlaid at a runtime offset involving ``i``:699 700.. code::701 :number-lines:702 703 // 1. Memory location description of dst elements located in memory:704 DW_OP_breg0 0705 706 // 2. Register location description of element dst[i] is located in R2:707 DW_OP_reg2708 709 // 3. Offset of the register within the memory of dst:710 DW_OP_breg1 0711 DW_OP_lit4712 DW_OP_mul713 714 // 4. The size of the register element:715 DW_OP_lit4716 717 // 5. Make a composite location description for dst that is the memory #1 with718 // the register #2 positioned as an overlay at offset #3 of size #4:719 DW_OP_LLVM_overlay720 7212.21 Support for Source Language Memory Spaces722----------------------------------------------723 724AMDGPU supports languages, such as OpenCL, that define source language memory725spaces. Support is added to define language-specific memory spaces so they can726be used in a consistent way by consumers. See :ref:`amdgpu-dwarf-memory-spaces`.727 728A new attribute ``DW_AT_LLVM_memory_space`` is added to support using memory729spaces in defining source language pointer and reference types (see730:ref:`amdgpu-dwarf-type-modifier-entries`) and data object allocation (see731:ref:`amdgpu-dwarf-data-object-entries`).732 7332.22 Expression Operation Vendor Extensibility Opcode734-----------------------------------------------------735 736The vendor extension encoding space for DWARF expression operations737accommodates only 32 unique operations. In practice, the lack of a central738registry and a desire for backwards compatibility means vendor extensions are739never retired, even when standard versions are accepted into DWARF proper. This740has produced a situation where the effective encoding space available for new741vendor extensions is minuscule today.742 743To expand this encoding space, a new DWARF operation ``DW_OP_LLVM_user`` is744added which acts as a "prefix" for vendor extensions. It is followed by a745ULEB128 encoded vendor extension opcode, which is then followed by the operands746of the corresponding vendor extension operation.747 748This approach allows all remaining operations defined in these extensions to be749encoded without conflicting with existing vendor extensions.750 751See ``DW_OP_LLVM_user`` in :ref:`amdgpu-dwarf-vendor-extensions-operations`.752 753.. _amdgpu-dwarf-changes-relative-to-dwarf-version-5:754 755A. Changes Relative to DWARF Version 5756======================================757 758.. note::759 760 This appendix provides changes relative to DWARF Version 5. It has been761 defined such that it is backwards compatible with DWARF Version 5.762 Non-normative text is shown in *italics*. The section numbers generally763 correspond to those in the DWARF Version 5 standard unless specified764 otherwise. Definitions are given for the additional operations, as well as765 clarifying how existing expression operations, CFI operations, and attributes766 behave with respect to generalized location descriptions that support address767 spaces and multiple places.768 769 The names for the new operations, attributes, and constants include "\770 ``LLVM``\ " and are encoded with vendor specific codes so these extensions771 can be implemented as an LLVM vendor extension to DWARF Version 5. New772 operations other than ``DW_OP_LLVM_user`` are "prefixed" by773 ``DW_OP_LLVM_user`` to make enough encoding space available for their774 implementation.775 776 .. note::777 778 Notes are included to describe how the changes are to be applied to the779 DWARF Version 5 standard. They also describe rationale and issues that may780 need further consideration.781 782A.2 General Description783-----------------------784 785A.2.2 Attribute Types786~~~~~~~~~~~~~~~~~~~~~787 788.. note::789 790 This augments DWARF Version 5 section 2.2 and Table 2.2.791 792The following table provides the additional attributes.793 794.. table:: Attribute names795 :name: amdgpu-dwarf-attribute-names-table796 797 ============================ ====================================798 Attribute Usage799 ============================ ====================================800 ``DW_AT_LLVM_active_lane`` SIMT active lanes (see :ref:`amdgpu-dwarf-low-level-information`)801 ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string (see :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`)802 ``DW_AT_LLVM_lane_pc`` SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`)803 ``DW_AT_LLVM_lanes`` SIMT lane count (see :ref:`amdgpu-dwarf-low-level-information`)804 ``DW_AT_LLVM_iterations`` Concurrent iteration count (see :ref:`amdgpu-dwarf-low-level-information`)805 ``DW_AT_LLVM_vector_size`` Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`)806 ``DW_AT_LLVM_address_space`` Architecture specific address space (see :ref:`amdgpu-dwarf-address-spaces`)807 ``DW_AT_LLVM_memory_space`` Pointer or reference types (see 5.3 "Type Modifier Entries")808 Data objects (see 4.1 "Data Object Entries")809 ============================ ====================================810 811.. _amdgpu-dwarf-expressions:812 813A.2.5 DWARF Expressions814~~~~~~~~~~~~~~~~~~~~~~~815 816.. note::817 818 This section, and its nested sections, replaces DWARF Version 5 section 2.5819 and section 2.6. The new DWARF expression operation extensions are defined as820 well as clarifying the extensions to already existing DWARF Version 5821 operations. It is based on the text of the existing DWARF Version 5 standard.822 823DWARF expressions describe how to compute a value or specify a location.824 825*The evaluation of a DWARF expression can provide the location of an object, the826value of an array bound, the length of a dynamic string, the desired value827itself, and so on.*828 829If the evaluation of a DWARF expression does not encounter an error, then it can830either result in a value (see :ref:`amdgpu-dwarf-expression-value`) or a831location description (see :ref:`amdgpu-dwarf-location-description`). When a832DWARF expression is evaluated, it may be specified whether a value or location833description is required as the result kind.834 835If a result kind is specified, and the result of the evaluation does not match836the specified result kind, then the implicit conversions described in837:ref:`amdgpu-dwarf-memory-location-description-operations` are performed if838valid. Otherwise, the DWARF expression is ill-formed.839 840If the evaluation of a DWARF expression encounters an evaluation error, then the841result is an evaluation error.842 843.. note::844 845 Decided to define the concept of an evaluation error. An alternative is to846 introduce an undefined value base type in a similar way to location847 descriptions having an undefined location description. Then operations that848 encounter an evaluation error can return the undefined location description or849 value with an undefined base type.850 851 All operations that act on values would return an undefined entity if given an852 undefined value. The expression would then always evaluate to completion, and853 can be tested to determine if it is an undefined entity.854 855 However, this would add considerable additional complexity and does not match856 that GDB throws an exception when these evaluation errors occur.857 858If a DWARF expression is ill-formed, then the result is undefined.859 860The following sections detail the rules for when a DWARF expression is861ill-formed or results in an evaluation error.862 863A DWARF expression can either be encoded as an operation expression (see864:ref:`amdgpu-dwarf-operation-expressions`), or as a location list expression865(see :ref:`amdgpu-dwarf-location-list-expressions`).866 867.. _amdgpu-dwarf-expression-evaluation-context:868 869A.2.5.1 DWARF Expression Evaluation Context870+++++++++++++++++++++++++++++++++++++++++++871 872A DWARF expression is evaluated in a context that can include a number of873context elements. If multiple context elements are specified then they must be874self consistent or the result of the evaluation is undefined. The context875elements that can be specified are:876 877*A current result kind*878 879 The kind of result required by the DWARF expression evaluation. If specified880 it can be a location description or a value.881 882*A current thread*883 884 The target architecture thread identifier. For source languages that are not885 implemented using a SIMT execution model, this corresponds to the source886 program thread of execution for which a user presented expression is currently887 being evaluated. For source languages that are implemented using a SIMT888 execution model, this together with the current lane corresponds to the source889 program thread of execution for which a user presented expression is currently890 being evaluated.891 892 It is required for operations that are related to target architecture threads.893 894 *For example, the* ``DW_OP_regval_type`` *operation, or the*895 ``DW_OP_form_tls_address`` *and* ``DW_OP_LLVM_form_aspace_address``896 *operations when given an address space that is target architecture thread897 specific.*898 899*A current lane*900 901 The 0-based SIMT lane identifier to be used in evaluating a user presented902 expression. This applies to source languages that are implemented for a target903 architecture using a SIMT execution model. These implementations map source904 language threads of execution to lanes of the target architecture threads.905 906 It is required for operations that are related to SIMT lanes.907 908 *For example, the* ``DW_OP_LLVM_push_lane`` *operation and*909 ``DW_OP_LLVM_form_aspace_address`` *operation when given an address space that910 is SIMT lane specific.*911 912 If specified, it must be consistent with the value of the ``DW_AT_LLVM_lanes``913 attribute of the subprogram corresponding to context's frame and program914 location. It is consistent if the value is greater than or equal to 0 and less915 than the, possibly default, value of the ``DW_AT_LLVM_lanes`` attribute.916 Otherwise the result is undefined.917 918*A current iteration*919 920 The 0-based source language iteration instance to be used in evaluating a user921 presented expression. This applies to target architectures that support922 optimizations that result in executing multiple source language loop iterations923 concurrently.924 925 *For example, software pipelining and SIMD vectorization.*926 927 It is required for operations that are related to source language loop928 iterations.929 930 *For example, the* ``DW_OP_LLVM_push_iteration`` *operation.*931 932 If specified, it must be consistent with the value of the933 ``DW_AT_LLVM_iterations`` attribute of the subprogram corresponding to934 context's frame and program location. It is consistent if the value is greater935 than or equal to 0 and less than the, possibly default, value of the936 ``DW_AT_LLVM_iterations`` attribute. Otherwise the result is undefined.937 938*A current call frame*939 940 The target architecture call frame identifier. It identifies a call frame that941 corresponds to an active invocation of a subprogram in the current thread. It942 is identified by its address on the call stack. The address is referred to as943 the Canonical Frame Address (CFA). The call frame information is used to944 determine the CFA for the call frames of the current thread's call stack (see945 :ref:`amdgpu-dwarf-call-frame-information`).946 947 It is required for operations that specify target architecture registers to948 support virtual unwinding of the call stack.949 950 *For example, the* ``DW_OP_*reg*`` *operations.*951 952 If specified, it must be an active call frame in the current thread. If the953 current lane is specified, then that lane must have been active on entry to954 the call frame (see the ``DW_AT_LLVM_lane_pc`` attribute). Otherwise the955 result is undefined.956 957 If it is the currently executing call frame, then it is termed the top call958 frame.959 960*A current program location*961 962 The target architecture program location corresponding to the current call963 frame of the current thread.964 965 The program location of the top call frame is the target architecture program966 counter for the current thread. The call frame information is used to obtain967 the value of the return address register to determine the program location of968 the other call frames (see :ref:`amdgpu-dwarf-call-frame-information`).969 970 It is required for the evaluation of location list expressions to select971 amongst multiple program location ranges. It is required for operations that972 specify target architecture registers to support virtual unwinding of the call973 stack (see :ref:`amdgpu-dwarf-call-frame-information`).974 975 If specified:976 977 * If the current lane is not specified:978 979 * If the current call frame is the top call frame, it must be the current980 target architecture program location.981 982 * If the current call frame F is not the top call frame, it must be the983 program location associated with the call site in the current caller frame984 F that invoked the callee frame.985 986 * If the current lane is specified and the architecture program location LPC987 computed by the ``DW_AT_LLVM_lane_pc`` attribute for the current lane is not988 the undefined location description (indicating the lane was not active on989 entry to the call frame), it must be LPC.990 991 * Otherwise the result is undefined.992 993*A current compilation unit*994 995 The compilation unit debug information entry that contains the DWARF expression996 being evaluated.997 998 It is required for operations that reference debug information associated with999 the same compilation unit, including indicating if such references use the1000 32-bit or 64-bit DWARF format. It can also provide the default address space1001 address size if no current target architecture is specified.1002 1003 *For example, the* ``DW_OP_constx`` *and* ``DW_OP_addrx`` *operations.*1004 1005 *Note that this compilation unit may not be the same as the compilation unit1006 determined from the loaded code object corresponding to the current program1007 location. For example, the evaluation of the expression E associated with a*1008 ``DW_AT_location`` *attribute of the debug information entry operand of the*1009 ``DW_OP_call*`` *operations is evaluated with the compilation unit that1010 contains E and not the one that contains the* ``DW_OP_call*`` *operation1011 expression.*1012 1013*A current target architecture*1014 1015 The target architecture.1016 1017 It is required for operations that specify target architecture specific1018 entities.1019 1020 *For example, target architecture specific entities include DWARF register1021 identifiers, DWARF lane identifiers, DWARF address space identifiers, the1022 default address space, and the address space address sizes.*1023 1024 If specified:1025 1026 * If the current frame is specified, then the current target architecture must1027 be the same as the target architecture of the current frame.1028 1029 * If the current frame is specified and is the top frame, and if the current1030 thread is specified, then the current target architecture must be the same1031 as the target architecture of the current thread.1032 1033 * If the current compilation unit is specified, then the current target1034 architecture default address space address size must be the same as the1035 ``address_size`` field in the header of the current compilation unit and any1036 associated entry in the ``.debug_aranges`` section.1037 1038 * If the current program location is specified, then the current target1039 architecture must be the same as the target architecture of any line number1040 information entry (see :ref:`amdgpu-dwarf-line-number-information`)1041 corresponding to the current program location.1042 1043 * If the current program location is specified, then the current target1044 architecture default address space address size must be the same as the1045 ``address_size`` field in the header of any entry corresponding to the1046 current program location in the ``.debug_addr``, ``.debug_line``,1047 ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and1048 ``.debug_loclists.dwo`` sections.1049 1050 * Otherwise the result is undefined.1051 1052*A current object*1053 1054 The location description of a program object.1055 1056 It is required for the ``DW_OP_push_object_address`` operation.1057 1058 *For example, the* ``DW_AT_data_location`` *attribute on type debug1059 information entries specifies the program object corresponding to a runtime1060 descriptor as the current object when it evaluates its associated expression.*1061 1062 The result is undefined if the location description is invalid (see1063 :ref:`amdgpu-dwarf-location-description`).1064 1065*An initial stack*1066 1067 This is a list of values or location descriptions that will be pushed on the1068 operation expression evaluation stack in the order provided before evaluation1069 of an operation expression starts.1070 1071 Some debugger information entries have attributes that evaluate their DWARF1072 expression value with initial stack entries. In all other cases the initial1073 stack is empty.1074 1075 The result is undefined if any location descriptions are invalid (see1076 :ref:`amdgpu-dwarf-location-description`).1077 1078If the evaluation requires a context element that is not specified, then the1079result of the evaluation is an error.1080 1081*A DWARF expression for a location description may be able to be evaluated1082without a thread, lane, call frame, program location, or architecture context.1083For example, the location of a global variable may be able to be evaluated1084without such context. If the expression evaluates with an error then it may1085indicate the variable has been optimized and so requires more context.*1086 1087*The DWARF expression for call frame information (see*1088:ref:`amdgpu-dwarf-call-frame-information`\ *) operations are restricted to1089those that do not require the compilation unit context to be specified.*1090 1091The DWARF is ill-formed if all the ``address_size`` fields in the headers of all1092the entries in the ``.debug_info``, ``.debug_addr``, ``.debug_line``,1093``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and1094``.debug_loclists.dwo`` sections corresponding to any given program location do1095not match.1096 1097.. _amdgpu-dwarf-expression-value:1098 1099A.2.5.2 DWARF Expression Value1100++++++++++++++++++++++++++++++1101 1102A value has a type and a literal value. It can represent a literal value of any1103supported base type of the target architecture. The base type specifies the1104size, encoding, and endianity of the literal value.1105 1106.. note::1107 1108 It may be desirable to add an implicit pointer base type encoding. It would be1109 used for the type of the value that is produced when the ``DW_OP_deref*``1110 operation retrieves the full contents of an implicit pointer location storage1111 created by the ``DW_OP_implicit_pointer`` or1112 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. The literal value would1113 record the debugging information entry and byte displacement specified by the1114 associated ``DW_OP_implicit_pointer`` or1115 ``DW_OP_LLVM_aspace_implicit_pointer`` operations.1116 1117There is a distinguished base type termed the generic type, which is an integral1118type that has the size of an address in the target architecture default address1119space, a target architecture defined endianity, and unspecified signedness.1120 1121*The generic type is the same as the unspecified type used for stack operations1122defined in DWARF Version 4 and before.*1123 1124An integral type is a base type that has an encoding of ``DW_ATE_signed``,1125``DW_ATE_signed_char``, ``DW_ATE_unsigned``, ``DW_ATE_unsigned_char``,1126``DW_ATE_boolean``, or any target architecture defined integral encoding in the1127inclusive range ``DW_ATE_lo_user`` to ``DW_ATE_hi_user``.1128 1129.. note::1130 1131 It is unclear if ``DW_ATE_address`` is an integral type. GDB does not seem to1132 consider it as integral.1133 1134.. _amdgpu-dwarf-location-description:1135 1136A.2.5.3 DWARF Location Description1137++++++++++++++++++++++++++++++++++1138 1139*Debugging information must provide consumers a way to find the location of1140program variables, determine the bounds of dynamic arrays and strings, and1141possibly to find the base address of a subprogram’s call frame or the return1142address of a subprogram. Furthermore, to meet the needs of recent computer1143architectures and optimization techniques, debugging information must be able to1144describe the location of an object whose location changes over the object’s1145lifetime, and may reside at multiple locations simultaneously during parts of an1146object's lifetime.*1147 1148Information about the location of program objects is provided by location1149descriptions.1150 1151Location descriptions can consist of one or more single location descriptions.1152 1153A single location description specifies the location storage that holds a1154program object and a position within the location storage where the program1155object starts. The position within the location storage is expressed as a bit1156offset relative to the start of the location storage.1157 1158A location storage is a linear stream of bits that can hold values. Each1159location storage has a size in bits and can be accessed using a zero-based bit1160offset. The ordering of bits within a location storage uses the bit numbering1161and direction conventions that are appropriate to the current language on the1162target architecture.1163 1164There are five kinds of location storage:1165 1166*memory location storage*1167 Corresponds to the target architecture memory address spaces.1168 1169*register location storage*1170 Corresponds to the target architecture registers.1171 1172*implicit location storage*1173 Corresponds to fixed values that can only be read.1174 1175*undefined location storage*1176 Indicates no value is available and therefore cannot be read or written.1177 1178*composite location storage*1179 Allows a mixture of these where some bits come from one location storage and1180 some from another location storage, or from disjoint parts of the same1181 location storage.1182 1183.. note::1184 1185 It may be better to add an implicit pointer location storage kind used by the1186 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer``1187 operations. It would specify the debugger information entry and byte offset1188 provided by the operations.1189 1190*Location descriptions are a language-independent representation of addressing1191rules.*1192 1193* *They can be the result of evaluating a debugger information entry attribute1194 that specifies an operation expression of arbitrary complexity. In this usage1195 they can describe the location of an object as long as its lifetime is either1196 static or the same as the lexical block (see1197 :ref:`amdgpu-dwarf-lexical-block-entries`) that owns it, and it does not move1198 during its lifetime.*1199 1200* *They can be the result of evaluating a debugger information entry attribute1201 that specifies a location list expression. In this usage they can describe the1202 location of an object that has a limited lifetime, changes its location during1203 its lifetime, or has multiple locations over part or all of its lifetime.*1204 1205If a location description has more than one single location description, the1206DWARF expression is ill-formed if the object value held in each single location1207description's position within the associated location storage is not the same1208value, except for the parts of the value that are uninitialized.1209 1210*A location description that has more than one single location description can1211only be created by a location list expression that has overlapping program1212location ranges, or certain expression operations that act on a location1213description that has more than one single location description. There are no1214operation expression operations that can directly create a location description1215with more than one single location description.*1216 1217*A location description with more than one single location description can be1218used to describe objects that reside in more than one piece of storage at the1219same time. An object may have more than one location as a result of1220optimization. For example, a value that is only read may be promoted from memory1221to a register for some region of code, but later code may revert to reading the1222value from memory as the register may be used for other purposes. For the code1223region where the value is in a register, any change to the object value must be1224made in both the register and the memory so both regions of code will read the1225updated value.*1226 1227*A consumer of a location description with more than one single location1228description can read the object's value from any of the single location1229descriptions (since they all refer to location storage that has the same value),1230but must write any changed value to all the single location descriptions.*1231 1232The evaluation of an expression may require context elements to create a1233location description. If such a location description is accessed, the storage it1234denotes is that associated with the context element values specified when the1235location description was created, which may differ from the context at the time1236it is accessed.1237 1238*For example, creating a register location description requires the thread1239context: the location storage is for the specified register of that thread.1240Creating a memory location description for an address space may required a1241thread and a lane context: the location storage is the memory associated with1242that thread and lane.*1243 1244If any of the context elements required to create a location description change,1245the location description becomes invalid and accessing it is undefined.1246 1247*Examples of context that can invalidate a location description are:*1248 1249* *The thread context is required and execution causes the thread to terminate.*1250* *The call frame context is required and further execution causes the call1251 frame to return to the calling frame.*1252* *The program location is required and further execution of the thread occurs.1253 That could change the location list entry or call frame information entry that1254 applies.*1255* *An operation uses call frame information:*1256 1257 * *Any of the frames used in the virtual call frame unwinding return.*1258 * *The top call frame is used, the program location is used to select the call1259 frame information entry, and further execution of the thread occurs.*1260 1261*A DWARF expression can be used to compute a location description for an object.1262A subsequent DWARF expression evaluation can be given the object location1263description as the object context or initial stack context to compute a1264component of the object. The final result is undefined if the object location1265description becomes invalid between the two expression evaluations.*1266 1267A change of a thread's program location may not make a location description1268invalid, yet may still render it as no longer meaningful. Accessing such a1269location description, or using it as the object context or initial stack context1270of an expression evaluation, may produce an undefined result.1271 1272*For example, a location description may specify a register that no longer holds1273the intended program object after a program location change. One way to avoid1274such problems is to recompute location descriptions associated with threads when1275their program locations change.*1276 1277.. _amdgpu-dwarf-operation-expressions:1278 1279A.2.5.4 DWARF Operation Expressions1280+++++++++++++++++++++++++++++++++++1281 1282An operation expression is comprised of a stream of operations, each consisting1283of an opcode followed by zero or more operands. The number of operands is1284implied by the opcode.1285 1286Operations represent a postfix operation on a simple stack machine. Each stack1287entry can hold either a value or a location description. Operations can act on1288entries on the stack, including adding entries and removing entries. If the kind1289of a stack entry does not match the kind required by the operation and is not1290implicitly convertible to the required kind (see1291:ref:`amdgpu-dwarf-memory-location-description-operations`), then the DWARF1292operation expression is ill-formed.1293 1294Evaluation of an operation expression starts with an empty stack on which the1295entries from the initial stack provided by the context are pushed in the order1296provided. Then the operations are evaluated, starting with the first operation1297of the stream. Evaluation continues until either an operation has an evaluation1298error, or until one past the last operation of the stream is reached.1299 1300The result of the evaluation is:1301 1302* If an operation has an evaluation error, or an operation evaluates an1303 expression that has an evaluation error, then the result is an evaluation1304 error.1305 1306* If the current result kind specifies a location description, then:1307 1308 * If the stack is empty, the result is a location description with one1309 undefined location description.1310 1311 *This rule is for backwards compatibility with DWARF Version 5 which has no1312 explicit operation to create an undefined location description, and uses an1313 empty operation expression for this purpose.*1314 1315 * If the top stack entry is a location description, or can be converted1316 to one (see :ref:`amdgpu-dwarf-memory-location-description-operations`),1317 then the result is that, possibly converted, location description. Any other1318 entries on the stack are discarded.1319 1320 * Otherwise the DWARF expression is ill-formed.1321 1322 .. note::1323 1324 Could define this case as returning an implicit location description as1325 if the ``DW_OP_implicit`` operation is performed.1326 1327* If the current result kind specifies a value, then:1328 1329 * If the top stack entry is a value, or can be converted to one (see1330 :ref:`amdgpu-dwarf-memory-location-description-operations`), then the result1331 is that, possibly converted, value. Any other entries on the stack are1332 discarded.1333 1334 * Otherwise the DWARF expression is ill-formed.1335 1336* If the current result kind is not specified, then:1337 1338 * If the stack is empty, the result is a location description with one1339 undefined location description.1340 1341 *This rule is for backwards compatibility with DWARF Version 5 which has no1342 explicit operation to create an undefined location description, and uses an1343 empty operation expression for this purpose.*1344 1345 .. note::1346 1347 This rule is consistent with the rule above for when a location1348 description is requested. However, GDB appears to report this as an error1349 and no GDB tests appear to cause an empty stack for this case.1350 1351 * Otherwise, the top stack entry is returned. Any other entries on the stack1352 are discarded.1353 1354An operation expression is encoded as a byte block with some form of prefix that1355specifies the byte count. It can be used:1356 1357* as the value of a debugging information entry attribute that is encoded using1358 class ``exprloc`` (see :ref:`amdgpu-dwarf-classes-and-forms`),1359 1360* as the operand to certain operation expression operations,1361 1362* as the operand to certain call frame information operations (see1363 :ref:`amdgpu-dwarf-call-frame-information`),1364 1365* and in location list entries (see1366 :ref:`amdgpu-dwarf-location-list-expressions`).1367 1368.. _amdgpu-dwarf-vendor-extensions-operations:1369 1370A.2.5.4.0 Vendor Extension Operations1371#####################################1372 13731. ``DW_OP_LLVM_user``1374 1375 ``DW_OP_LLVM_user`` encodes a vendor extension operation. It has at least one1376 operand: a ULEB128 constant identifying a vendor extension operation. The1377 remaining operands are defined by the vendor extension. The vendor extension1378 opcode 0 is reserved and cannot be used by any vendor extension.1379 1380 *The DW_OP_user encoding space can be understood to supplement the space1381 defined by DW_OP_lo_user and DW_OP_hi_user that is allocated by the standard1382 for the same purpose.*1383 1384.. _amdgpu-dwarf-stack-operations:1385 1386A.2.5.4.1 Stack Operations1387##########################1388 1389.. note::1390 1391 This section replaces DWARF Version 5 section 2.5.1.3.1392 1393The following operations manipulate the DWARF stack. Operations that index the1394stack assume that the top of the stack (most recently added entry) has index 0.1395They allow the stack entries to be either a value or location description.1396 1397If any stack entry accessed by a stack operation is an incomplete composite1398location description (see1399:ref:`amdgpu-dwarf-composite-location-description-operations`), then the DWARF1400expression is ill-formed.1401 1402.. note::1403 1404 These operations now support stack entries that are values and location1405 descriptions.1406 1407.. note::1408 1409 If it is desired to also make them work with incomplete composite location1410 descriptions, then would need to define that the composite location storage1411 specified by the incomplete composite location description is also replicated1412 when a copy is pushed. This ensures that each copy of the incomplete composite1413 location description can update the composite location storage they specify1414 independently.1415 14161. ``DW_OP_dup``1417 1418 ``DW_OP_dup`` duplicates the stack entry at the top of the stack.1419 14202. ``DW_OP_drop``1421 1422 ``DW_OP_drop`` pops the stack entry at the top of the stack and discards it.1423 14243. ``DW_OP_pick``1425 1426 ``DW_OP_pick`` has a single unsigned 1-byte operand that represents an index1427 I. A copy of the stack entry with index I is pushed onto the stack.1428 14294. ``DW_OP_over``1430 1431 ``DW_OP_over`` pushes a copy of the entry with index 1.1432 1433 *This is equivalent to a* ``DW_OP_pick 1`` *operation.*1434 14355. ``DW_OP_swap``1436 1437 ``DW_OP_swap`` swaps the top two stack entries. The entry at the top of the1438 stack becomes the second stack entry, and the second stack entry becomes the1439 top of the stack.1440 14416. ``DW_OP_rot``1442 1443 ``DW_OP_rot`` rotates the first three stack entries. The entry at the top of1444 the stack becomes the third stack entry, the second entry becomes the top of1445 the stack, and the third entry becomes the second entry.1446 1447*Examples illustrating many of these stack operations are found in Appendix1448D.1.2 on page 289.*1449 1450.. _amdgpu-dwarf-control-flow-operations:1451 1452A.2.5.4.2 Control Flow Operations1453#################################1454 1455.. note::1456 1457 This section replaces DWARF Version 5 section 2.5.1.5.1458 1459The following operations provide simple control of the flow of a DWARF operation1460expression.1461 14621. ``DW_OP_nop``1463 1464 ``DW_OP_nop`` is a place holder. It has no effect on the DWARF stack1465 entries.1466 14672. ``DW_OP_le``, ``DW_OP_ge``, ``DW_OP_eq``, ``DW_OP_lt``, ``DW_OP_gt``,1468 ``DW_OP_ne``1469 1470 .. note::1471 1472 The same as in DWARF Version 5 section 2.5.1.5.1473 14743. ``DW_OP_skip``1475 1476 ``DW_OP_skip`` is an unconditional branch. Its single operand is a 2-byte1477 signed integer constant. The 2-byte constant is the number of bytes of the1478 DWARF expression to skip forward or backward from the current operation,1479 beginning after the 2-byte constant.1480 1481 If the updated position is at one past the end of the last operation, then1482 the operation expression evaluation is complete.1483 1484 Otherwise, the DWARF expression is ill-formed if the updated operation1485 position is not in the range of the first to last operation inclusive, or1486 not at the start of an operation.1487 14884. ``DW_OP_bra``1489 1490 ``DW_OP_bra`` is a conditional branch. Its single operand is a 2-byte signed1491 integer constant. This operation pops the top of stack. If the value popped1492 is not the constant 0, the 2-byte constant operand is the number of bytes of1493 the DWARF operation expression to skip forward or backward from the current1494 operation, beginning after the 2-byte constant.1495 1496 If the updated position is at one past the end of the last operation, then1497 the operation expression evaluation is complete.1498 1499 Otherwise, the DWARF expression is ill-formed if the updated operation1500 position is not in the range of the first to last operation inclusive, or1501 not at the start of an operation.1502 15035. ``DW_OP_call2, DW_OP_call4, DW_OP_call_ref``1504 1505 ``DW_OP_call2``, ``DW_OP_call4``, and ``DW_OP_call_ref`` perform DWARF1506 procedure calls during evaluation of a DWARF operation expression.1507 1508 ``DW_OP_call2`` and ``DW_OP_call4``, have one operand that is, respectively,1509 a 2-byte or 4-byte unsigned offset DR that represents the byte offset of a1510 debugging information entry D relative to the beginning of the current1511 compilation unit.1512 1513 ``DW_OP_call_ref`` has one operand that is a 4-byte unsigned value in the1514 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format,1515 that represents the byte offset DR of a debugging information entry D1516 relative to the beginning of the ``.debug_info`` section that contains the1517 current compilation unit. D may not be in the current compilation unit.1518 1519 .. note::1520 1521 DWARF Version 5 states that DR can be an offset in a ``.debug_info``1522 section other than the one that contains the current compilation unit. It1523 states that relocation of references from one executable or shared object1524 file to another must be performed by the consumer. But given that DR is1525 defined as an offset in a ``.debug_info`` section this seems impossible.1526 If DR was defined as an implementation-defined value, then the consumer1527 could choose to interpret the value in an implementation-defined manner to1528 reference a debug information in another executable or shared object.1529 1530 In ELF the ``.debug_info`` section is in a non-\ ``PT_LOAD`` segment so1531 standard dynamic relocations cannot be used. But even if they were loaded1532 segments and dynamic relocations were used, DR would need to be the1533 address of D, not an offset in a ``.debug_info`` section. That would also1534 need DR to be the size of a global address. So it would not be possible to1535 use the 32-bit DWARF format in a 64-bit global address space. In addition,1536 the consumer would need to determine what executable or shared object the1537 relocated address was in so it could determine the containing compilation1538 unit.1539 1540 GDB only interprets DR as an offset in the ``.debug_info`` section that1541 contains the current compilation unit.1542 1543 This comment also applies to ``DW_OP_implicit_pointer`` and1544 ``DW_OP_LLVM_aspace_implicit_pointer``.1545 1546 *Operand interpretation of* ``DW_OP_call2``\ *,* ``DW_OP_call4``\ *, and*1547 ``DW_OP_call_ref`` *is exactly like that for* ``DW_FORM_ref2``\ *,1548 ``DW_FORM_ref4``\ *, and* ``DW_FORM_ref_addr``\ *, respectively.*1549 1550 The call operation is evaluated by:1551 1552 * If D has a ``DW_AT_location`` attribute that is encoded as a ``exprloc``1553 that specifies an operation expression E, then execution of the current1554 operation expression continues from the first operation of E. Execution1555 continues until one past the last operation of E is reached, at which1556 point execution continues with the operation following the call operation.1557 The operations of E are evaluated with the same current context, except1558 current compilation unit is the one that contains D and the stack is the1559 same as that being used by the call operation. After the call operation1560 has been evaluated, the stack is therefore as it is left by the evaluation1561 of the operations of E. Since E is evaluated on the same stack as the call1562 operation, E can use, and/or remove entries already on the stack, and can1563 add new entries to the stack.1564 1565 *Values on the stack at the time of the call may be used as parameters by1566 the called expression and values left on the stack by the called expression1567 may be used as return values by prior agreement between the calling and1568 called expressions.*1569 1570 * If D has a ``DW_AT_location`` attribute that is encoded as a ``loclist`` or1571 ``loclistsptr``, then the specified location list expression E is1572 evaluated. The evaluation of E uses the current context, except the result1573 kind is a location description, the compilation unit is the one that1574 contains D, and the initial stack is empty. The location description1575 result is pushed on the stack.1576 1577 .. note::1578 1579 This rule avoids having to define how to execute a matched location list1580 entry operation expression on the same stack as the call when there are1581 multiple matches. But it allows the call to obtain the location1582 description for a variable or formal parameter which may use a location1583 list expression.1584 1585 An alternative is to treat the case when D has a ``DW_AT_location``1586 attribute that is encoded as a ``loclist`` or ``loclistsptr``, and the1587 specified location list expression E' matches a single location list1588 entry with operation expression E, the same as the ``exprloc`` case and1589 evaluate on the same stack.1590 1591 But this is not attractive as if the attribute is for a variable that1592 happens to end with a non-singleton stack, it will not simply put a1593 location description on the stack. Presumably the intent of using1594 ``DW_OP_call*`` on a variable or formal parameter debugger information1595 entry is to push just one location description on the stack. That1596 location description may have more than one single location description.1597 1598 The previous rule for ``exprloc`` also has the same problem, as normally1599 a variable or formal parameter location expression may leave multiple1600 entries on the stack and only return the top entry.1601 1602 GDB implements ``DW_OP_call*`` by always executing E on the same stack.1603 If the location list has multiple matching entries, it simply picks the1604 first one and ignores the rest. This seems fundamentally at odds with1605 the desire to support multiple places for variables.1606 1607 So, it feels like ``DW_OP_call*`` should both support pushing a location1608 description on the stack for a variable or formal parameter, and also1609 support being able to execute an operation expression on the same stack.1610 Being able to specify a different operation expression for different1611 program locations seems a desirable feature to retain.1612 1613 A solution to that is to have a distinct ``DW_AT_LLVM_proc`` attribute1614 for the ``DW_TAG_dwarf_procedure`` debugging information entry. Then the1615 ``DW_AT_location`` attribute expression is always executed separately1616 and pushes a location description (that may have multiple single1617 location descriptions), and the ``DW_AT_LLVM_proc`` attribute expression1618 is always executed on the same stack and can leave anything on the1619 stack.1620 1621 The ``DW_AT_LLVM_proc`` attribute could have the new classes1622 ``exprproc``, ``loclistproc``, and ``loclistsptrproc`` to indicate that1623 the expression is executed on the same stack. ``exprproc`` is the same1624 encoding as ``exprloc``. ``loclistproc`` and ``loclistsptrproc`` are the1625 same encoding as their non-\ ``proc`` counterparts, except the DWARF is1626 ill-formed if the location list does not match exactly one location list1627 entry and a default entry is required. These forms indicate explicitly1628 that the matched single operation expression must be executed on the1629 same stack. This is better than ad hoc special rules for ``loclistproc``1630 and ``loclistsptrproc`` which are currently clearly defined to always1631 return a location description. The producer then explicitly indicates1632 the intent through the attribute classes.1633 1634 Such a change would be a breaking change for how GDB implements1635 ``DW_OP_call*``. However, are the breaking cases actually occurring in1636 practice? GDB could implement the current approach for DWARF Version 5,1637 and the new semantics for DWARF Version 6 which has been done for some1638 other features.1639 1640 Another option is to limit the execution to be on the same stack only to1641 the evaluation of an expression E that is the value of a1642 ``DW_AT_location`` attribute of a ``DW_TAG_dwarf_procedure`` debugging1643 information entry. The DWARF would be ill-formed if E is a location list1644 expression that does not match exactly one location list entry. In all1645 other cases the evaluation of an expression E that is the value of a1646 ``DW_AT_location`` attribute would evaluate E with the current context,1647 except the result kind is a location description, the compilation unit1648 is the one that contains D, and the initial stack is empty. The location1649 description result is pushed on the stack.1650 1651 * If D has a ``DW_AT_const_value`` attribute with a value V, then it is as1652 if a ``DW_OP_implicit_value V`` operation was executed.1653 1654 *This allows a call operation to be used to compute the location1655 description for any variable or formal parameter regardless of whether the1656 producer has optimized it to a constant. This is consistent with the*1657 ``DW_OP_implicit_pointer`` *operation.*1658 1659 .. note::1660 1661 Alternatively, could deprecate using ``DW_AT_const_value`` for1662 ``DW_TAG_variable`` and ``DW_TAG_formal_parameter`` debugger information1663 entries that are constants and instead use ``DW_AT_location`` with an1664 operation expression that results in a location description with one1665 implicit location description. Then this rule would not be required.1666 1667 * Otherwise, there is no effect and no changes are made to the stack.1668 1669 .. note::1670 1671 In DWARF Version 5, if D does not have a ``DW_AT_location`` then1672 ``DW_OP_call*`` is defined to have no effect. It is unclear that this is1673 the right definition as a producer should be able to rely on using1674 ``DW_OP_call*`` to get a location description for any non-\1675 ``DW_TAG_dwarf_procedure`` debugging information entries. Also, the1676 producer should not be creating DWARF with ``DW_OP_call*`` to a1677 ``DW_TAG_dwarf_procedure`` that does not have a ``DW_AT_location``1678 attribute. So, should this case be defined as an ill-formed DWARF1679 expression?1680 1681 *The* ``DW_TAG_dwarf_procedure`` *debugging information entry can be used to1682 define DWARF procedures that can be called.*1683 1684.. _amdgpu-dwarf-value-operations:1685 1686A.2.5.4.3 Value Operations1687##########################1688 1689This section describes the operations that push values on the stack.1690 1691Each value stack entry has a type and a literal value. It can represent a1692literal value of any supported base type of the target architecture. The base1693type specifies the size, encoding, and endianity of the literal value.1694 1695The base type of value stack entries can be the distinguished generic type.1696 1697.. _amdgpu-dwarf-literal-operations:1698 1699A.2.5.4.3.1 Literal Operations1700^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1701 1702.. note::1703 1704 This section replaces DWARF Version 5 section 2.5.1.1.1705 1706The following operations all push a literal value onto the DWARF stack.1707 1708Operations other than ``DW_OP_const_type`` push a value V with the generic type.1709If V is larger than the generic type, then V is truncated to the generic type1710size and the low-order bits used.1711 17121. ``DW_OP_lit0``, ``DW_OP_lit1``, ..., ``DW_OP_lit31``1713 1714 ``DW_OP_lit<N>`` operations encode an unsigned literal value N from 01715 through 31, inclusive. They push the value N with the generic type.1716 17172. ``DW_OP_const1u``, ``DW_OP_const2u``, ``DW_OP_const4u``, ``DW_OP_const8u``1718 1719 ``DW_OP_const<N>u`` operations have a single operand that is a 1, 2, 4, or1720 8-byte unsigned integer constant U, respectively. They push the value U with1721 the generic type.1722 17233. ``DW_OP_const1s``, ``DW_OP_const2s``, ``DW_OP_const4s``, ``DW_OP_const8s``1724 1725 ``DW_OP_const<N>s`` operations have a single operand that is a 1, 2, 4, or1726 8-byte signed integer constant S, respectively. They push the value S with1727 the generic type.1728 17294. ``DW_OP_constu``1730 1731 ``DW_OP_constu`` has a single unsigned LEB128 integer operand N. It pushes1732 the value N with the generic type.1733 17345. ``DW_OP_consts``1735 1736 ``DW_OP_consts`` has a single signed LEB128 integer operand N. It pushes the1737 value N with the generic type.1738 17396. ``DW_OP_constx``1740 1741 ``DW_OP_constx`` has a single unsigned LEB128 integer operand that1742 represents a zero-based index into the ``.debug_addr`` section relative to1743 the value of the ``DW_AT_addr_base`` attribute of the associated compilation1744 unit. The value N in the ``.debug_addr`` section has the size of the generic1745 type. It pushes the value N with the generic type.1746 1747 *The* ``DW_OP_constx`` *operation is provided for constants that require1748 link-time relocation but should not be interpreted by the consumer as a1749 relocatable address (for example, offsets to thread-local storage).*1750 17517. ``DW_OP_const_type``1752 1753 ``DW_OP_const_type`` has three operands. The first is an unsigned LEB1281754 integer DR that represents the byte offset of a debugging information entry1755 D relative to the beginning of the current compilation unit, that provides1756 the type T of the constant value. The second is a 1-byte unsigned integral1757 constant S. The third is a block of bytes B, with a length equal to S.1758 1759 TS is the bit size of the type T. The least significant TS bits of B are1760 interpreted as a value V of the type D. It pushes the value V with the type1761 D.1762 1763 The DWARF is ill-formed if D is not a ``DW_TAG_base_type`` debugging1764 information entry in the current compilation unit, or if TS divided by 81765 (the byte size) and rounded up to a whole number is not equal to S.1766 1767 *While the size of the byte block B can be inferred from the type D1768 definition, it is encoded explicitly into the operation so that the1769 operation can be parsed easily without reference to the* ``.debug_info``1770 *section.*1771 17728. ``DW_OP_LLVM_push_lane`` *New*1773 1774 ``DW_OP_LLVM_push_lane`` pushes the current lane as a value with the generic1775 type.1776 1777 *For source languages that are implemented using a SIMT execution model,1778 this is the zero-based lane number that corresponds to the source language1779 thread of execution upon which the user is focused.*1780 1781 The value must be greater than or equal to 0 and less than the value of the1782 ``DW_AT_LLVM_lanes`` attribute, otherwise the DWARF expression is1783 ill-formed. See :ref:`amdgpu-dwarf-low-level-information`.1784 17859. ``DW_OP_LLVM_push_iteration`` *New*1786 1787 ``DW_OP_LLVM_push_iteration`` pushes the current iteration as a value with1788 the generic type.1789 1790 *For source language implementations with optimizations that cause multiple1791 loop iterations to execute concurrently, this is the zero-based iteration1792 number that corresponds to the source language concurrent loop iteration1793 upon which the user is focused.*1794 1795 The value must be greater than or equal to 0 and less than the value of the1796 ``DW_AT_LLVM_iterations`` attribute, otherwise the DWARF expression is1797 ill-formed. See :ref:`amdgpu-dwarf-low-level-information`.1798 1799.. _amdgpu-dwarf-arithmetic-logical-operations:1800 1801A.2.5.4.3.2 Arithmetic and Logical Operations1802^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1803 1804.. note::1805 1806 This section is the same as DWARF Version 5 section 2.5.1.4.1807 1808.. _amdgpu-dwarf-type-conversions-operations:1809 1810A.2.5.4.3.3 Type Conversion Operations1811^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1812 1813.. note::1814 1815 This section is the same as DWARF Version 5 section 2.5.1.6.1816 1817.. _amdgpu-dwarf-general-operations:1818 1819A.2.5.4.3.4 Special Value Operations1820^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1821 1822.. note::1823 1824 This section replaces parts of DWARF Version 5 sections 2.5.1.2, 2.5.1.3, and1825 2.5.1.7.1826 1827There are these special value operations currently defined:1828 18291. ``DW_OP_regval_type``1830 1831 ``DW_OP_regval_type`` has two operands. The first is an unsigned LEB1281832 integer that represents a register number R. The second is an unsigned1833 LEB128 integer DR that represents the byte offset of a debugging information1834 entry D relative to the beginning of the current compilation unit, that1835 provides the type T of the register value.1836 1837 The operation is equivalent to performing ``DW_OP_regx R; DW_OP_deref_type1838 DR``.1839 1840 .. note::1841 1842 Should DWARF allow the type T to be a larger size than the size of the1843 register R? Restricting a larger bit size avoids any issue of conversion1844 as the, possibly truncated, bit contents of the register is simply1845 interpreted as a value of T. If a conversion is wanted it can be done1846 explicitly using a ``DW_OP_convert`` operation.1847 1848 GDB has a per register hook that allows a target-specific conversion on a1849 register by register basis. It defaults to truncation of bigger registers.1850 Removing use of the target hook does not cause any test failures in common1851 architectures. If the compiler for a target architecture did want some1852 form of conversion, including a larger result type, it could always1853 explicitly use the ``DW_OP_convert`` operation.1854 1855 If T is a larger type than the register size, then the default GDB1856 register hook reads bytes from the next register (or reads out of bounds1857 for the last register!). Removing use of the target hook does not cause1858 any test failures in common architectures (except an illegal hand-written1859 assembly test). If a target architecture requires this behavior, these1860 extensions allow a composite location description to be used to combine1861 multiple registers.1862 18632. ``DW_OP_deref``1864 1865 S is the bit size of the generic type divided by 8 (the byte size) and1866 rounded up to a whole number. DR is the offset of a hypothetical debug1867 information entry D in the current compilation unit for a base type of the1868 generic type.1869 1870 The operation is equivalent to performing ``DW_OP_deref_type S, DR``.1871 18723. ``DW_OP_deref_size``1873 1874 ``DW_OP_deref_size`` has a single 1-byte unsigned integral constant that1875 represents a byte result size S.1876 1877 TS is the smaller of the generic type bit size and S scaled by 8 (the byte1878 size). If TS is smaller than the generic type bit size then T is an unsigned1879 integral type of bit size TS, otherwise T is the generic type. DR is the1880 offset of a hypothetical debug information entry D in the current1881 compilation unit for a base type T.1882 1883 .. note::1884 1885 Truncating the value when S is larger than the generic type matches what1886 GDB does. This allows the generic type size to not be an integral byte1887 size. It does allow S to be arbitrarily large. Should S be restricted to1888 the size of the generic type rounded up to a multiple of 8?1889 1890 The operation is equivalent to performing ``DW_OP_deref_type S, DR``, except1891 if T is not the generic type, the value V pushed is zero-extended to the1892 generic type bit size and its type changed to the generic type.1893 18944. ``DW_OP_deref_type``1895 1896 ``DW_OP_deref_type`` has two operands. The first is a 1-byte unsigned1897 integral constant S. The second is an unsigned LEB128 integer DR that1898 represents the byte offset of a debugging information entry D relative to1899 the beginning of the current compilation unit, that provides the type T of1900 the result value.1901 1902 TS is the bit size of the type T.1903 1904 *While the size of the pushed value V can be inferred from the type T, it is1905 encoded explicitly as the operand S so that the operation can be parsed1906 easily without reference to the* ``.debug_info`` *section.*1907 1908 .. note::1909 1910 It is unclear why the operand S is needed. Unlike ``DW_OP_const_type``,1911 the size is not needed for parsing. Any evaluation needs to get the base1912 type T to push with the value to know its encoding and bit size.1913 1914 It pops one stack entry that must be a location description L.1915 1916 A value V of TS bits is retrieved from the location storage LS specified by1917 one of the single location descriptions SL of L.1918 1919 *If L, or the location description of any composite location description1920 part that is a subcomponent of L, has more than one single location1921 description, then any one of them can be selected as they are required to1922 all have the same value. For any single location description SL, bits are1923 retrieved from the associated storage location starting at the bit offset1924 specified by SL. For a composite location description, the retrieved bits1925 are the concatenation of the N bits from each composite location part PL,1926 where N is limited to the size of PL.*1927 1928 V is pushed on the stack with the type T.1929 1930 .. note::1931 1932 This definition makes it an evaluation error if L is a register location1933 description that has less than TS bits remaining in the register storage.1934 Particularly since these extensions extend location descriptions to have1935 a bit offset, it would be odd to define this as performing sign extension1936 based on the type, or be target architecture dependent, as the number of1937 remaining bits could be any number. This matches the GDB implementation1938 for ``DW_OP_deref_type``.1939 1940 These extensions define ``DW_OP_*breg*`` in terms of1941 ``DW_OP_regval_type``. ``DW_OP_regval_type`` is defined in terms of1942 ``DW_OP_regx``, which uses a 0 bit offset, and ``DW_OP_deref_type``.1943 Therefore, it requires the register size to be greater or equal to the1944 address size of the address space. This matches the GDB implementation for1945 ``DW_OP_*breg*``.1946 1947 The DWARF is ill-formed if D is not in the current compilation unit, D is1948 not a ``DW_TAG_base_type`` debugging information entry, or if TS divided by1949 8 (the byte size) and rounded up to a whole number is not equal to S.1950 1951 .. note::1952 1953 This definition allows the base type to be a bit size since there seems no1954 reason to restrict it.1955 1956 It is an evaluation error if any bit of the value is retrieved from the1957 undefined location storage or the offset of any bit exceeds the size of the1958 location storage LS specified by any single location description SL of L.1959 1960 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special1961 rules concerning implicit location descriptions created by the1962 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer``1963 operations.1964 19655. ``DW_OP_xderef`` *Deprecated*1966 1967 ``DW_OP_xderef`` pops two stack entries. The first must be an integral type1968 value that represents an address A. The second must be an integral type1969 value that represents a target architecture specific address space1970 identifier AS.1971 1972 The operation is equivalent to performing ``DW_OP_swap;1973 DW_OP_LLVM_form_aspace_address; DW_OP_deref``. The value V retrieved is left1974 on the stack with the generic type.1975 1976 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``1977 *operation can be used and provides greater expressiveness.*1978 19796. ``DW_OP_xderef_size`` *Deprecated*1980 1981 ``DW_OP_xderef_size`` has a single 1-byte unsigned integral constant that1982 represents a byte result size S.1983 1984 It pops two stack entries. The first must be an integral type value that1985 represents an address A. The second must be an integral type value that1986 represents a target architecture specific address space identifier AS.1987 1988 The operation is equivalent to performing ``DW_OP_swap;1989 DW_OP_LLVM_form_aspace_address; DW_OP_deref_size S``. The zero-extended1990 value V retrieved is left on the stack with the generic type.1991 1992 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``1993 *operation can be used and provides greater expressiveness.*1994 19957. ``DW_OP_xderef_type`` *Deprecated*1996 1997 ``DW_OP_xderef_type`` has two operands. The first is a 1-byte unsigned1998 integral constant S. The second operand is an unsigned LEB128 integer DR1999 that represents the byte offset of a debugging information entry D relative2000 to the beginning of the current compilation unit, that provides the type T2001 of the result value.2002 2003 It pops two stack entries. The first must be an integral type value that2004 represents an address A. The second must be an integral type value that2005 represents a target architecture specific address space identifier AS.2006 2007 The operation is equivalent to performing ``DW_OP_swap;2008 DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S DR``. The value V2009 retrieved is left on the stack with the type T.2010 2011 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``2012 *operation can be used and provides greater expressiveness.*2013 20148. ``DW_OP_entry_value`` *Deprecated*2015 2016 ``DW_OP_entry_value`` pushes the value of an expression that is evaluated in2017 the context of the calling frame.2018 2019 *It may be used to determine the value of arguments on entry to the current2020 call frame provided they are not clobbered.*2021 2022 It has two operands. The first is an unsigned LEB128 integer S. The second2023 is a block of bytes, with a length equal S, interpreted as a DWARF2024 operation expression E.2025 2026 E is evaluated with the current context, except the result kind is2027 unspecified, the call frame is the one that called the current frame, the2028 program location is the call site in the calling frame, the object is2029 unspecified, and the initial stack is empty. The calling frame information2030 is obtained by virtually unwinding the current call frame using the call2031 frame information (see :ref:`amdgpu-dwarf-call-frame-information`).2032 2033 If the result of E is a location description L (see2034 :ref:`amdgpu-dwarf-register-location-description-operations`), and the last2035 operation executed by E is a ``DW_OP_reg*`` for register R with a target2036 architecture specific base type of T, then the contents of the register are2037 retrieved as if a ``DW_OP_deref_type DR`` operation was performed where DR2038 is the offset of a hypothetical debug information entry in the current2039 compilation unit for T. The resulting value V s pushed on the stack.2040 2041 *Using* ``DW_OP_reg*`` *provides a more compact form for the case where the2042 value was in a register on entry to the subprogram.*2043 2044 .. note::2045 2046 It is unclear how this provides a more compact expression, as2047 ``DW_OP_regval_type`` could be used which is marginally larger.2048 2049 If the result of E is a value V, then V is pushed on the stack.2050 2051 Otherwise, the DWARF expression is ill-formed.2052 2053 *The* ``DW_OP_entry_value`` *operation is deprecated as its main usage is2054 provided by other means. DWARF Version 5 added the*2055 ``DW_TAG_call_site_parameter`` *debugger information entry for call sites2056 that has* ``DW_AT_call_value``\ *,* ``DW_AT_call_data_location``\ *, and*2057 ``DW_AT_call_data_value`` *attributes that provide DWARF expressions to2058 compute actual parameter values at the time of the call, and requires the2059 producer to ensure the expressions are valid to evaluate even when virtually2060 unwound. The* ``DW_OP_LLVM_call_frame_entry_reg`` *operation provides access2061 to registers in the virtually unwound calling frame.*2062 2063 .. note::2064 2065 GDB only implements ``DW_OP_entry_value`` when E is exactly2066 ``DW_OP_reg*`` or ``DW_OP_breg*; DW_OP_deref*``.2067 2068.. _amdgpu-dwarf-location-description-operations:2069 2070A.2.5.4.4 Location Description Operations2071#########################################2072 2073This section describes the operations that push location descriptions on the2074stack.2075 2076.. _amdgpu-dwarf-general-location-description-operations:2077 2078A.2.5.4.4.1 General Location Description Operations2079^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2080 2081.. note::2082 2083 This section replaces part of DWARF Version 5 section 2.5.1.3.2084 20851. ``DW_OP_LLVM_offset`` *New*2086 2087 ``DW_OP_LLVM_offset`` pops two stack entries. The first must be an integral2088 type value that represents a byte displacement B. The second must be a2089 location description L.2090 2091 It adds the value of B scaled by 8 (the byte size) to the bit offset of each2092 single location description SL of L, and pushes the updated L.2093 2094 It is an evaluation error if the updated bit offset of any SL is less than 02095 or greater than or equal to the size of the location storage specified by2096 SL.2097 20982. ``DW_OP_LLVM_offset_uconst`` *New*2099 2100 ``DW_OP_LLVM_offset_uconst`` has a single unsigned LEB128 integer operand2101 that represents a byte displacement B.2102 2103 The operation is equivalent to performing ``DW_OP_constu B;2104 DW_OP_LLVM_offset``.2105 2106 *This operation is supplied specifically to be able to encode more field2107 displacements in two bytes than can be done with* ``DW_OP_lit*;2108 DW_OP_LLVM_offset``\ *.*2109 2110 .. note::2111 2112 Should this be named ``DW_OP_LLVM_offset_uconst`` to match2113 ``DW_OP_plus_uconst``, or ``DW_OP_LLVM_offset_constu`` to match2114 ``DW_OP_constu``?2115 21163. ``DW_OP_LLVM_bit_offset`` *New*2117 2118 ``DW_OP_LLVM_bit_offset`` pops two stack entries. The first must be an2119 integral type value that represents a bit displacement B. The second must be2120 a location description L.2121 2122 It adds the value of B to the bit offset of each single location description2123 SL of L, and pushes the updated L.2124 2125 It is an evaluation error if the updated bit offset of any SL is less than 02126 or greater than or equal to the size of the location storage specified by2127 SL.2128 21294. ``DW_OP_push_object_address``2130 2131 ``DW_OP_push_object_address`` pushes the location description L of the2132 current object.2133 2134 *This object may correspond to an independent variable that is part of a2135 user presented expression that is being evaluated. The object location2136 description may be determined from the variable's own debugging information2137 entry or it may be a component of an array, structure, or class whose2138 address has been dynamically determined by an earlier step during user2139 expression evaluation.*2140 2141 *This operation provides explicit functionality (especially for arrays2142 involving descriptors) that is analogous to the implicit push of the base2143 location description of a structure prior to evaluation of a*2144 ``DW_AT_data_member_location`` *to access a data member of a structure.*2145 2146 .. note::2147 2148 This operation could be removed and the object location description2149 specified as the initial stack as for ``DW_AT_data_member_location``.2150 2151 Or this operation could be used instead of needing to specify an initial2152 stack. The latter approach is more composable as access to the object may2153 be needed at any point of the expression, and passing it as the initial2154 stack requires the entire expression to be aware where on the stack it is.2155 If this were done, ``DW_AT_use_location`` would require a2156 ``DW_OP_push_object2_address`` operation for the second object.2157 2158 Or a more general way to pass an arbitrary number of arguments in and an2159 operation to get the Nth one such as ``DW_OP_arg N``. A vector of2160 arguments would then be passed in the expression context rather than an2161 initial stack. This could also resolve the issues with ``DW_OP_call*`` by2162 allowing a specific number of arguments passed in and returned to be2163 specified. The ``DW_OP_call*`` operation could then always execute on a2164 separate stack: the number of arguments would be specified in a new call2165 operation and taken from the callers stack, and similarly the number of2166 return results specified and copied from the called stack back to the2167 callee stack when the called expression was complete.2168 2169 The only attribute that specifies a current object is2170 ``DW_AT_data_location`` so the non-normative text seems to overstate how2171 this is being used. Or are there other attributes that need to state they2172 pass an object?2173 21745. ``DW_OP_LLVM_call_frame_entry_reg`` *New*2175 2176 ``DW_OP_LLVM_call_frame_entry_reg`` has a single unsigned LEB128 integer2177 operand that represents a target architecture register number R.2178 2179 It pushes a location description L that holds the value of register R on2180 entry to the current subprogram as defined by the call frame information2181 (see :ref:`amdgpu-dwarf-call-frame-information`).2182 2183 *If there is no call frame information defined, then the default rules for2184 the target architecture are used. If the register rule is* undefined\ *, then2185 the undefined location description is pushed. If the register rule is* same2186 value\ *, then a register location description for R is pushed.*2187 2188.. _amdgpu-dwarf-undefined-location-description-operations:2189 2190A.2.5.4.4.2 Undefined Location Description Operations2191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2192 2193.. note::2194 2195 This section replaces DWARF Version 5 section 2.6.1.1.1.2196 2197*The undefined location storage represents a piece or all of an object that is2198present in the source but not in the object code (perhaps due to optimization).2199Neither reading nor writing to the undefined location storage is meaningful.*2200 2201An undefined location description specifies the undefined location storage.2202There is no concept of the size of the undefined location storage, nor of a bit2203offset for an undefined location description. The ``DW_OP_LLVM_*offset``2204operations leave an undefined location description unchanged. The2205``DW_OP_*piece`` operations can explicitly or implicitly specify an undefined2206location description, allowing any size and offset to be specified, and results2207in a part with all undefined bits.2208 22091. ``DW_OP_LLVM_undefined`` *New*2210 2211 ``DW_OP_LLVM_undefined`` pushes a location description L that comprises one2212 undefined location description SL.2213 2214.. _amdgpu-dwarf-memory-location-description-operations:2215 2216A.2.5.4.4.3 Memory Location Description Operations2217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2218 2219.. note::2220 2221 This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2,2222 2.5.1.3, and 2.6.1.1.2.2223 2224Each of the target architecture specific address spaces has a corresponding2225memory location storage that denotes the linear addressable memory of that2226address space. The size of each memory location storage corresponds to the range2227of the addresses in the corresponding address space.2228 2229*It is target architecture defined how address space location storage maps to2230target architecture physical memory. For example, they may be independent2231memory, or more than one location storage may alias the same physical memory2232possibly at different offsets and with different interleaving. The mapping may2233also be dictated by the source language address classes.*2234 2235A memory location description specifies a memory location storage. The bit2236offset corresponds to a bit position within a byte of the memory. Bits accessed2237using a memory location description, access the corresponding target2238architecture memory starting at the bit position within the byte specified by2239the bit offset.2240 2241A memory location description that has a bit offset that is a multiple of 8 (the2242byte size) is defined to be a byte address memory location description. It has a2243memory byte address A that is equal to the bit offset divided by 8.2244 2245A memory location description that does not have a bit offset that is a multiple2246of 8 (the byte size) is defined to be a bit field memory location description.2247It has a bit position B equal to the bit offset modulo 8, and a memory byte2248address A equal to the bit offset minus B that is then divided by 8.2249 2250The address space AS of a memory location description is defined to be the2251address space that corresponds to the memory location storage associated with2252the memory location description.2253 2254A location description that is comprised of one byte address memory location2255description SL is defined to be a memory byte address location description. It2256has a byte address equal to A and an address space equal to AS of the2257corresponding SL.2258 2259``DW_ASPACE_LLVM_none`` is defined as the target architecture default address2260space. See :ref:`amdgpu-dwarf-address-spaces`.2261 2262If a stack entry is required to be a location description, but it is a value V2263with the generic type, then it is implicitly converted to a location description2264L with one memory location description SL. SL specifies the memory location2265storage that corresponds to the target architecture default address space with a2266bit offset equal to V scaled by 8 (the byte size).2267 2268.. note::2269 2270 If it is wanted to allow any integral type value to be implicitly converted to2271 a memory location description in the target architecture default address2272 space:2273 2274 If a stack entry is required to be a location description, but is a value V2275 with an integral type, then it is implicitly converted to a location2276 description L with a one memory location description SL. If the type size of2277 V is less than the generic type size, then the value V is zero extended to2278 the size of the generic type. The least significant generic type size bits2279 are treated as an unsigned value to be used as an address A. SL specifies2280 memory location storage corresponding to the target architecture default2281 address space with a bit offset equal to A scaled by 8 (the byte size).2282 2283 The implicit conversion could also be defined as target architecture specific.2284 For example, GDB checks if V is an integral type. If it is not it gives an2285 error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a2286 hook function, then it is called. The target-specific hook function can modify2287 the 64-bit value, possibly sign extending based on the original value type.2288 Finally, GDB treats the 64-bit value V as a memory location address.2289 2290If a stack entry is required to be a location description, but it is an implicit2291pointer value IPV with the target architecture default address space, then it is2292implicitly converted to a location description with one single location2293description specified by IPV. See2294:ref:`amdgpu-dwarf-implicit-location-description-operations`.2295 2296.. note::2297 2298 Is this rule required for DWARF Version 5 backwards compatibility? If not, it2299 can be eliminated, and the producer can use2300 ``DW_OP_LLVM_form_aspace_address``.2301 2302If a stack entry is required to be a value, but it is a location description L2303with one memory location description SL in the target architecture default2304address space with a bit offset B that is a multiple of 8, then it is implicitly2305converted to a value equal to B divided by 8 (the byte size) with the generic2306type.2307 23081. ``DW_OP_addr``2309 2310 ``DW_OP_addr`` has a single byte constant value operand, which has the size2311 of the generic type, that represents an address A.2312 2313 It pushes a location description L with one memory location description SL2314 on the stack. SL specifies the memory location storage corresponding to the2315 target architecture default address space with a bit offset equal to A2316 scaled by 8 (the byte size).2317 2318 *If the DWARF is part of a code object, then A may need to be relocated. For2319 example, in the ELF code object format, A must be adjusted by the difference2320 between the ELF segment virtual address and the virtual address at which the2321 segment is loaded.*2322 23232. ``DW_OP_addrx``2324 2325 ``DW_OP_addrx`` has a single unsigned LEB128 integer operand that represents2326 a zero-based index into the ``.debug_addr`` section relative to the value of2327 the ``DW_AT_addr_base`` attribute of the associated compilation unit. The2328 address value A in the ``.debug_addr`` section has the size of the generic2329 type.2330 2331 It pushes a location description L with one memory location description SL2332 on the stack. SL specifies the memory location storage corresponding to the2333 target architecture default address space with a bit offset equal to A2334 scaled by 8 (the byte size).2335 2336 *If the DWARF is part of a code object, then A may need to be relocated. For2337 example, in the ELF code object format, A must be adjusted by the difference2338 between the ELF segment virtual address and the virtual address at which the2339 segment is loaded.*2340 23413. ``DW_OP_LLVM_form_aspace_address`` *New*2342 2343 ``DW_OP_LLVM_form_aspace_address`` pops top two stack entries. The first2344 must be an integral type value that represents a target architecture2345 specific address space identifier AS. The second must be an integral type2346 value that represents an address A.2347 2348 The address size S is defined as the address bit size of the target2349 architecture specific address space that corresponds to AS.2350 2351 A is adjusted to S bits by zero extending if necessary, and then treating2352 the least significant S bits as an unsigned value A'.2353 2354 It pushes a location description L with one memory location description SL2355 on the stack. SL specifies the memory location storage LS that corresponds2356 to AS with a bit offset equal to A' scaled by 8 (the byte size).2357 2358 If AS is an address space that is specific to context elements, then LS2359 corresponds to the location storage associated with the current context.2360 2361 *For example, if AS is for per thread storage then LS is the location2362 storage for the current thread. For languages that are implemented using a2363 SIMT execution model, then if AS is for per lane storage then LS is the2364 location storage for the current lane of the current thread. Therefore, if L2365 is accessed by an operation, the location storage selected when the location2366 description was created is accessed, and not the location storage associated2367 with the current context of the access operation.*2368 2369 The DWARF expression is ill-formed if AS is not one of the values defined by2370 the target architecture specific ``DW_ASPACE_LLVM_*`` values.2371 2372 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special2373 rules concerning implicit pointer values produced by dereferencing implicit2374 location descriptions created by the ``DW_OP_implicit_pointer`` and2375 ``DW_OP_LLVM_aspace_implicit_pointer`` operations.2376 23774. ``DW_OP_form_tls_address``2378 2379 ``DW_OP_form_tls_address`` pops one stack entry that must be an integral2380 type value and treats it as a thread-local storage address TA.2381 2382 It pushes a location description L with one memory location description SL2383 on the stack. SL is the target architecture specific memory location2384 description that corresponds to the thread-local storage address TA.2385 2386 The meaning of the thread-local storage address TA is defined by the2387 run-time environment. If the run-time environment supports multiple2388 thread-local storage blocks for a single thread, then the block2389 corresponding to the executable or shared library containing this DWARF2390 expression is used.2391 2392 *Some implementations of C, C++, Fortran, and other languages, support a2393 thread-local storage class. Variables with this storage class have distinct2394 values and addresses in distinct threads, much as automatic variables have2395 distinct values and addresses in each subprogram invocation. Typically,2396 there is a single block of storage containing all thread-local variables2397 declared in the main executable, and a separate block for the variables2398 declared in each shared library. Each thread-local variable can then be2399 accessed in its block using an identifier. This identifier is typically a2400 byte offset into the block and pushed onto the DWARF stack by one of the*2401 ``DW_OP_const*`` *operations prior to the* ``DW_OP_form_tls_address``2402 *operation. Computing the address of the appropriate block can be complex2403 (in some cases, the compiler emits a function call to do it), and difficult2404 to describe using ordinary DWARF location descriptions. Instead of forcing2405 complex thread-local storage calculations into the DWARF expressions, the*2406 ``DW_OP_form_tls_address`` *allows the consumer to perform the computation2407 based on the target architecture specific run-time environment.*2408 24095. ``DW_OP_call_frame_cfa``2410 2411 ``DW_OP_call_frame_cfa`` pushes the location description L of the Canonical2412 Frame Address (CFA) of the current subprogram, obtained from the call frame2413 information on the stack. See :ref:`amdgpu-dwarf-call-frame-information`.2414 2415 *Although the value of the* ``DW_AT_frame_base`` *attribute of the debugger2416 information entry corresponding to the current subprogram can be computed2417 using a location list expression, in some cases this would require an2418 extensive location list because the values of the registers used in2419 computing the CFA change during a subprogram execution. If the call frame2420 information is present, then it already encodes such changes, and it is2421 space efficient to reference that using the* ``DW_OP_call_frame_cfa``2422 *operation.*2423 24246. ``DW_OP_fbreg``2425 2426 ``DW_OP_fbreg`` has a single signed LEB128 integer operand that represents a2427 byte displacement B.2428 2429 The location description L for the *frame base* of the current subprogram is2430 obtained from the ``DW_AT_frame_base`` attribute of the debugger information2431 entry corresponding to the current subprogram as described in2432 :ref:`amdgpu-dwarf-low-level-information`.2433 2434 The location description L is updated as if the ``DW_OP_LLVM_offset_uconst2435 B`` operation was applied. The updated L is pushed on the stack.2436 24377. ``DW_OP_breg0``, ``DW_OP_breg1``, ..., ``DW_OP_breg31``2438 2439 The ``DW_OP_breg<N>`` operations encode the numbers of up to 32 registers,2440 numbered from 0 through 31, inclusive. The register number R corresponds to2441 the N in the operation name.2442 2443 They have a single signed LEB128 integer operand that represents a byte2444 displacement B.2445 2446 The address space identifier AS is defined as the one corresponding to the2447 target architecture specific default address space.2448 2449 The address size S is defined as the address bit size of the target2450 architecture specific address space corresponding to AS.2451 2452 The contents of the register specified by R are retrieved as if a2453 ``DW_OP_regval_type R, DR`` operation was performed where DR is the offset2454 of a hypothetical debug information entry in the current compilation unit2455 for an unsigned integral base type of size S bits. B is added and the least2456 significant S bits are treated as an unsigned value to be used as an address2457 A.2458 2459 They push a location description L comprising one memory location2460 description LS on the stack. LS specifies the memory location storage that2461 corresponds to AS with a bit offset equal to A scaled by 8 (the byte size).2462 24638. ``DW_OP_bregx``2464 2465 ``DW_OP_bregx`` has two operands. The first is an unsigned LEB128 integer2466 that represents a register number R. The second is a signed LEB1282467 integer that represents a byte displacement B.2468 2469 The action is the same as for ``DW_OP_breg<N>``, except that R is used as2470 the register number and B is used as the byte displacement.2471 24729. ``DW_OP_LLVM_aspace_bregx`` *New*2473 2474 ``DW_OP_LLVM_aspace_bregx`` has two operands. The first is an unsigned2475 LEB128 integer that represents a register number R. The second is a signed2476 LEB128 integer that represents a byte displacement B. It pops one stack2477 entry that is required to be an integral type value that represents a target2478 architecture specific address space identifier AS.2479 2480 The action is the same as for ``DW_OP_breg<N>``, except that R is used as2481 the register number, B is used as the byte displacement, and AS is used as2482 the address space identifier.2483 2484 The DWARF expression is ill-formed if AS is not one of the values defined by2485 the target architecture specific ``DW_ASPACE_LLVM_*`` values.2486 2487 .. note::2488 2489 Could also consider adding ``DW_OP_LLVM_aspace_breg0,2490 DW_OP_LLVM_aspace_breg1, ..., DW_OP_LLVM_aspace_breg31`` which would save2491 encoding size.2492 2493.. _amdgpu-dwarf-register-location-description-operations:2494 2495A.2.5.4.4.4 Register Location Description Operations2496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2497 2498.. note::2499 2500 This section replaces DWARF Version 5 section 2.6.1.1.3.2501 2502There is a register location storage that corresponds to each of the target2503architecture registers. The size of each register location storage corresponds2504to the size of the corresponding target architecture register.2505 2506A register location description specifies a register location storage. The bit2507offset corresponds to a bit position within the register. Bits accessed using a2508register location description access the corresponding target architecture2509register starting at the specified bit offset.2510 25111. ``DW_OP_reg0``, ``DW_OP_reg1``, ..., ``DW_OP_reg31``2512 2513 ``DW_OP_reg<N>`` operations encode the numbers of up to 32 registers,2514 numbered from 0 through 31, inclusive. The target architecture register2515 number R corresponds to the N in the operation name.2516 2517 The operation is equivalent to performing ``DW_OP_regx R``.2518 25192. ``DW_OP_regx``2520 2521 ``DW_OP_regx`` has a single unsigned LEB128 integer operand that represents2522 a target architecture register number R.2523 2524 If the current call frame is the top call frame, it pushes a location2525 description L that specifies one register location description SL on the2526 stack. SL specifies the register location storage that corresponds to R with2527 a bit offset of 0 for the current thread.2528 2529 If the current call frame is not the top call frame, call frame information2530 (see :ref:`amdgpu-dwarf-call-frame-information`) is used to determine the2531 location description that holds the register for the current call frame and2532 current program location of the current thread. The resulting location2533 description L is pushed.2534 2535 *Note that if call frame information is used, the resulting location2536 description may be register, memory, or undefined.*2537 2538 *An implementation may evaluate the call frame information immediately, or2539 may defer evaluation until L is accessed by an operation. If evaluation is2540 deferred, R and the current context can be recorded in L. When accessed, the2541 recorded context is used to evaluate the call frame information, not the2542 current context of the access operation.*2543 2544*These operations obtain a register location. To fetch the contents of a2545register, it is necessary to use* ``DW_OP_regval_type``\ *, use one of the*2546``DW_OP_breg*`` *register-based addressing operations, or use* ``DW_OP_deref*``2547*on a register location description.*2548 2549.. _amdgpu-dwarf-implicit-location-description-operations:2550 2551A.2.5.4.4.5 Implicit Location Description Operations2552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2553 2554.. note::2555 2556 This section replaces DWARF Version 5 section 2.6.1.1.4.2557 2558Implicit location storage represents a piece or all of an object which has no2559actual location in the program but whose contents are nonetheless known, either2560as a constant or can be computed from other locations and values in the program.2561 2562An implicit location description specifies an implicit location storage. The bit2563offset corresponds to a bit position within the implicit location storage. Bits2564accessed using an implicit location description, access the corresponding2565implicit storage value starting at the bit offset.2566 25671. ``DW_OP_implicit_value``2568 2569 ``DW_OP_implicit_value`` has two operands. The first is an unsigned LEB1282570 integer that represents a byte size S. The second is a block of bytes with a2571 length equal to S treated as a literal value V.2572 2573 An implicit location storage LS is created with the literal value V and a2574 size of S.2575 2576 It pushes location description L with one implicit location description SL2577 on the stack. SL specifies LS with a bit offset of 0.2578 25792. ``DW_OP_stack_value``2580 2581 ``DW_OP_stack_value`` pops one stack entry that must be a value V.2582 2583 An implicit location storage LS is created with the literal value V using2584 the size, encoding, and endianity specified by V's base type.2585 2586 It pushes a location description L with one implicit location description SL2587 on the stack. SL specifies LS with a bit offset of 0.2588 2589 *The* ``DW_OP_stack_value`` *operation specifies that the object does not2590 exist in memory, but its value is nonetheless known. In this form, the2591 location description specifies the actual value of the object, rather than2592 specifying the memory or register storage that holds the value.*2593 2594 See ``DW_OP_implicit_pointer`` (following) for special rules concerning2595 implicit pointer values produced by dereferencing implicit location2596 descriptions created by the ``DW_OP_implicit_pointer`` and2597 ``DW_OP_LLVM_aspace_implicit_pointer`` operations.2598 2599 Note: Since location descriptions are allowed on the stack, the2600 ``DW_OP_stack_value`` operation no longer terminates the DWARF operation2601 expression execution as in DWARF Version 5.2602 26033. ``DW_OP_implicit_pointer``2604 2605 *An optimizing compiler may eliminate a pointer, while still retaining the2606 value that the pointer addressed.* ``DW_OP_implicit_pointer`` *allows a2607 producer to describe this value.*2608 2609 ``DW_OP_implicit_pointer`` *specifies an object is a pointer to the target2610 architecture default address space that cannot be represented as a real2611 pointer, even though the value it would point to can be described. In this2612 form, the location description specifies a debugging information entry that2613 represents the actual location description of the object to which the2614 pointer would point. Thus, a consumer of the debug information would be able2615 to access the dereferenced pointer, even when it cannot access the pointer2616 itself.*2617 2618 ``DW_OP_implicit_pointer`` has two operands. The first operand is a 4-byte2619 unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in2620 the 64-bit DWARF format, that represents the byte offset DR of a debugging2621 information entry D relative to the beginning of the ``.debug_info`` section2622 that contains the current compilation unit. The second operand is a signed2623 LEB128 integer that represents a byte displacement B.2624 2625 *Note that D might not be in the current compilation unit.*2626 2627 *The first operand interpretation is exactly like that for*2628 ``DW_FORM_ref_addr``\ *.*2629 2630 The address space identifier AS is defined as the one corresponding to the2631 target architecture specific default address space.2632 2633 The address size S is defined as the address bit size of the target2634 architecture specific address space corresponding to AS.2635 2636 An implicit location storage LS is created with the debugging information2637 entry D, address space AS, and size of S.2638 2639 It pushes a location description L that comprises one implicit location2640 description SL on the stack. SL specifies LS with a bit offset of 0.2641 2642 It is an evaluation error if a ``DW_OP_deref*`` operation pops a location2643 description L', and retrieves S bits, such that any retrieved bits come from2644 an implicit location storage that is the same as LS, unless both the2645 following conditions are met:2646 2647 1. All retrieved bits come from an implicit location description that2648 refers to an implicit location storage that is the same as LS.2649 2650 *Note that all bits do not have to come from the same implicit location2651 description, as L' may involve composite location descriptions.*2652 2653 2. The bits come from consecutive ascending offsets within their respective2654 implicit location storage.2655 2656 *These rules are equivalent to retrieving the complete contents of LS.*2657 2658 If both the above conditions are met, then the value V pushed by the2659 ``DW_OP_deref*`` operation is an implicit pointer value IPV with a target2660 architecture specific address space of AS, a debugging information entry of2661 D, and a base type of T. If AS is the target architecture default address2662 space, then T is the generic type. Otherwise, T is a target architecture2663 specific integral type with a bit size equal to S.2664 2665 If IPV is either implicitly converted to a location description (only done2666 if AS is the target architecture default address space) or used by2667 ``DW_OP_LLVM_form_aspace_address`` (only done if the address space popped by2668 ``DW_OP_LLVM_form_aspace_address`` is AS), then the resulting location2669 description RL is:2670 2671 * If D has a ``DW_AT_location`` attribute, the DWARF expression E from the2672 ``DW_AT_location`` attribute is evaluated with the current context, except2673 that the result kind is a location description, the compilation unit is2674 the one that contains D, the object is unspecified, and the initial stack2675 is empty. RL is the expression result.2676 2677 *Note that E is evaluated with the context of the expression accessing2678 IPV, and not the context of the expression that contained the*2679 ``DW_OP_implicit_pointer`` *or* ``DW_OP_LLVM_aspace_implicit_pointer``2680 *operation that created L.*2681 2682 * If D has a ``DW_AT_const_value`` attribute, then an implicit location2683 storage RLS is created from the ``DW_AT_const_value`` attribute's value2684 with a size matching the size of the ``DW_AT_const_value`` attribute's2685 value. RL comprises one implicit location description SRL. SRL specifies2686 RLS with a bit offset of 0.2687 2688 .. note::2689 2690 If using ``DW_AT_const_value`` for variables and formal parameters is2691 deprecated and instead ``DW_AT_location`` is used with an implicit2692 location description, then this rule would not be required.2693 2694 * Otherwise, it is an evaluation error.2695 2696 The bit offset of RL is updated as if the ``DW_OP_LLVM_offset_uconst B``2697 operation was applied.2698 2699 If a ``DW_OP_stack_value`` operation pops a value that is the same as IPV,2700 then it pushes a location description that is the same as L.2701 2702 It is an evaluation error if LS or IPV is accessed in any other manner.2703 2704 *The restrictions on how an implicit pointer location description created2705 by* ``DW_OP_implicit_pointer`` *and* ``DW_OP_LLVM_aspace_implicit_pointer``2706 *can be used are to simplify the DWARF consumer. Similarly, for an implicit2707 pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ *.*2708 27094. ``DW_OP_LLVM_aspace_implicit_pointer`` *New*2710 2711 ``DW_OP_LLVM_aspace_implicit_pointer`` has two operands that are the same as2712 for ``DW_OP_implicit_pointer``.2713 2714 It pops one stack entry that must be an integral type value that represents2715 a target architecture specific address space identifier AS.2716 2717 The location description L that is pushed on the stack is the same as for2718 ``DW_OP_implicit_pointer``, except that the address space identifier used is2719 AS.2720 2721 The DWARF expression is ill-formed if AS is not one of the values defined by2722 the target architecture specific ``DW_ASPACE_LLVM_*`` values.2723 2724 .. note::2725 2726 This definition of ``DW_OP_LLVM_aspace_implicit_pointer`` may change when2727 full support for address classes is added as required for languages such2728 as OpenCL/SyCL.2729 2730*Typically a* ``DW_OP_implicit_pointer`` *or*2731``DW_OP_LLVM_aspace_implicit_pointer`` *operation is used in a DWARF expression2732E*\ :sub:`1` *of a* ``DW_TAG_variable`` *or* ``DW_TAG_formal_parameter``2733*debugging information entry D*\ :sub:`1`\ *'s* ``DW_AT_location`` *attribute.2734The debugging information entry referenced by the* ``DW_OP_implicit_pointer``2735*or* ``DW_OP_LLVM_aspace_implicit_pointer`` *operations is typically itself a*2736``DW_TAG_variable`` *or* ``DW_TAG_formal_parameter`` *debugging information2737entry D*\ :sub:`2` *whose* ``DW_AT_location`` *attribute gives a second DWARF2738expression E*\ :sub:`2`\ *.*2739 2740*D*\ :sub:`1` *and E*\ :sub:`1` *are describing the location of a pointer type2741object. D*\ :sub:`2` *and E*\ :sub:`2` *are describing the location of the2742object pointed to by that pointer object.*2743 2744*However, D*\ :sub:`2` *may be any debugging information entry that contains a*2745``DW_AT_location`` *or* ``DW_AT_const_value`` *attribute (for example,*2746``DW_TAG_dwarf_procedure``\ *). By using E*\ :sub:`2`\ *, a consumer can2747reconstruct the value of the object when asked to dereference the pointer2748described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` *or*2749``DW_OP_LLVM_aspace_implicit_pointer`` *operation.*2750 2751.. _amdgpu-dwarf-composite-location-description-operations:2752 2753A.2.5.4.4.6 Composite Location Description Operations2754^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^2755 2756.. note::2757 2758 This section replaces DWARF Version 5 section 2.6.1.2.2759 2760A composite location storage represents an object or value which may be2761contained in part of another location storage or contained in parts of more2762than one location storage.2763 2764Each part has a part location description L and a part bit size S. L can have2765one or more single location descriptions SL. If there are more than one SL then2766that indicates that part is located in more than one place. The bits of each2767place of the part comprise S contiguous bits from the location storage LS2768specified by SL starting at the bit offset specified by SL. All the bits must2769be within the size of LS or the DWARF expression is ill-formed.2770 2771A composite location storage can have zero or more parts. The parts are2772contiguous such that the zero-based location storage bit index will range over2773each part with no gaps between them. Therefore, the size of a composite location2774storage is the sum of the size of its parts. The DWARF expression is ill-formed2775if the size of the contiguous location storage is larger than the size of the2776memory location storage corresponding to the largest target architecture2777specific address space.2778 2779A composite location description specifies a composite location storage. The bit2780offset corresponds to a bit position within the composite location storage.2781 2782There are operations that create a composite location storage.2783 2784There are other operations that allow a composite location storage to be2785incrementally created. Each part is created by a separate operation. There may2786be one or more operations to create the final composite location storage. A2787series of such operations describes the parts of the composite location storage2788that are in the order that the associated part operations are executed.2789 2790To support incremental creation, a composite location storage can be in an2791incomplete state. When an incremental operation operates on an incomplete2792composite location storage, it adds a new part, otherwise it creates a new2793composite location storage. The ``DW_OP_LLVM_piece_end`` operation explicitly2794makes an incomplete composite location storage complete.2795 2796A composite location description that specifies a composite location storage2797that is incomplete is termed an incomplete composite location description. A2798composite location description that specifies a composite location storage that2799is complete is termed a complete composite location description.2800 2801If the top stack entry is a location description that has one incomplete2802composite location description SL after the execution of an operation expression2803has completed, SL is converted to a complete composite location description.2804 2805*Note that this conversion does not happen after the completion of an operation2806expression that is evaluated on the same stack by the* ``DW_OP_call*``2807*operations. Such executions are not a separate evaluation of an operation2808expression, but rather the continued evaluation of the same operation expression2809that contains the* ``DW_OP_call*`` *operation.*2810 2811If a stack entry is required to be a location description L, but L has an2812incomplete composite location description, then the DWARF expression is2813ill-formed. The exception is for the operations involved in incrementally2814creating a composite location description as described below.2815 2816*Note that a DWARF operation expression may arbitrarily compose composite2817location descriptions from any other location description, including those that2818have multiple single location descriptions, and those that have composite2819location descriptions.*2820 2821*The incremental composite location description operations are defined to be2822compatible with the definitions in DWARF Version 5.*2823 28241. ``DW_OP_piece``2825 2826 ``DW_OP_piece`` has a single unsigned LEB128 integer that represents a byte2827 size S.2828 2829 The action is based on the context:2830 2831 * If the stack is empty, then a location description L comprised of one2832 incomplete composite location description SL is pushed on the stack.2833 2834 An incomplete composite location storage LS is created with a single part2835 P. P specifies a location description PL and has a bit size of S scaled by2836 8 (the byte size). PL is comprised of one undefined location description2837 PSL.2838 2839 SL specifies LS with a bit offset of 0.2840 2841 * Otherwise, if the top stack entry is a location description L comprised of2842 one incomplete composite location description SL, then the incomplete2843 composite location storage LS that SL specifies is updated to append a new2844 part P. P specifies a location description PL and has a bit size of S2845 scaled by 8 (the byte size). PL is comprised of one undefined location2846 description PSL. L is left on the stack.2847 2848 * Otherwise, if the top stack entry is a location description or can be2849 converted to one, then it is popped and treated as a part location2850 description PL. Then:2851 2852 * If the top stack entry (after popping PL) is a location description L2853 comprised of one incomplete composite location description SL, then the2854 incomplete composite location storage LS that SL specifies is updated to2855 append a new part P. P specifies the location description PL and has a2856 bit size of S scaled by 8 (the byte size). L is left on the stack.2857 2858 * Otherwise, a location description L comprised of one incomplete2859 composite location description SL is pushed on the stack.2860 2861 An incomplete composite location storage LS is created with a single2862 part P. P specifies the location description PL and has a bit size of S2863 scaled by 8 (the byte size).2864 2865 SL specifies LS with a bit offset of 0.2866 2867 * Otherwise, the DWARF expression is ill-formed2868 2869 *Many compilers store a single variable in sets of registers or store a2870 variable partially in memory and partially in registers.* ``DW_OP_piece``2871 *provides a way of describing where a part of a variable is located.*2872 2873 *If a non-0 byte displacement is required, the* ``DW_OP_LLVM_offset``2874 *operation can be used to update the location description before using it as2875 the part location description of a* ``DW_OP_piece`` *operation.*2876 2877 *The evaluation rules for the* ``DW_OP_piece`` *operation allow it to be2878 compatible with the DWARF Version 5 definition.*2879 2880 .. note::2881 2882 Since these extensions allow location descriptions to be entries on the2883 stack, a simpler operation to create composite location descriptions could2884 be defined. For example, just one operation that specifies how many parts,2885 and pops pairs of stack entries for the part size and location2886 description. Not only would this be a simpler operation and avoid the2887 complexities of incomplete composite location descriptions, but it may2888 also have a smaller encoding in practice. However, the desire for2889 compatibility with DWARF Version 5 is likely a stronger consideration.2890 28912. ``DW_OP_bit_piece``2892 2893 ``DW_OP_bit_piece`` has two operands. The first is an unsigned LEB1282894 integer that represents the part bit size S. The second is an unsigned2895 LEB128 integer that represents a bit displacement B.2896 2897 The action is the same as for ``DW_OP_piece``, except that any part created2898 has the bit size S, and the location description PL of any created part is2899 updated as if the ``DW_OP_constu B; DW_OP_LLVM_bit_offset`` operations were2900 applied.2901 2902 ``DW_OP_bit_piece`` *is used instead of* ``DW_OP_piece`` *when the piece to2903 be assembled is not byte-sized or is not at the start of the part location2904 description.*2905 2906 *If a computed bit displacement is required, the* ``DW_OP_LLVM_bit_offset``2907 *operation can be used to update the location description before using it as2908 the part location description of a* ``DW_OP_bit_piece`` *operation.*2909 2910 .. note::2911 2912 The bit offset operand is not needed as ``DW_OP_LLVM_bit_offset`` can be2913 used on the part's location description.2914 29153. ``DW_OP_LLVM_piece_end`` *New*2916 2917 If the top stack entry is not a location description L comprised of one2918 incomplete composite location description SL, then the DWARF expression is2919 ill-formed.2920 2921 Otherwise, the incomplete composite location storage LS specified by SL is2922 updated to be a complete composite location description with the same parts.2923 29244. ``DW_OP_LLVM_extend`` *New*2925 2926 ``DW_OP_LLVM_extend`` has two operands. The first is an unsigned LEB1282927 integer that represents the element bit size S. The second is an unsigned2928 LEB128 integer that represents a count C.2929 2930 It pops one stack entry that must be a location description and is treated2931 as the part location description PL.2932 2933 A location description L comprised of one complete composite location2934 description SL is pushed on the stack.2935 2936 A complete composite location storage LS is created with C identical parts2937 P. Each P specifies PL and has a bit size of S.2938 2939 SL specifies LS with a bit offset of 0.2940 2941 The DWARF expression is ill-formed if the element bit size or count are 0.2942 29435. ``DW_OP_LLVM_select_bit_piece`` *New*2944 2945 ``DW_OP_LLVM_select_bit_piece`` has two operands. The first is an unsigned2946 LEB128 integer that represents the element bit size S. The second is an2947 unsigned LEB128 integer that represents a count C.2948 2949 It pops three stack entries. The first must be an integral type value that2950 represents a bit mask value M. The second must be a location description2951 that represents the one-location description L1. The third must be a2952 location description that represents the zero-location description L0.2953 2954 A complete composite location storage LS is created with C parts P\ :sub:`N`2955 ordered in ascending N from 0 to C-1 inclusive. Each P\ :sub:`N` specifies2956 location description PL\ :sub:`N` and has a bit size of S.2957 2958 PL\ :sub:`N` is as if the ``DW_OP_LLVM_bit_offset N*S`` operation was2959 applied to PLX\ :sub:`N`\ .2960 2961 PLX\ :sub:`N` is the same as L0 if the N\ :sup:`th` least significant bit of2962 M is a zero, otherwise it is the same as L1.2963 2964 A location description L comprised of one complete composite location2965 description SL is pushed on the stack. SL specifies LS with a bit offset of2966 0.2967 2968 The DWARF expression is ill-formed if S or C are 0, or if the bit size of M2969 is less than C.2970 2971 .. note::2972 2973 Should the count operand for DW_OP_extend and DW_OP_select_bit_piece be2974 changed to get the count value off the stack? This would allow support for2975 architectures that have variable length vector instructions such as ARM2976 and RISC-V.2977 29786. ``DW_OP_LLVM_overlay`` *New*2979 2980 ``DW_OP_LLVM_overlay`` pops four stack entries. The first must be an2981 integral type value that represents the overlay byte size value S. The2982 second must be an integral type value that represents the overlay byte2983 offset value O. The third must be a location description that represents the2984 overlay location description OL. The fourth must be a location description2985 that represents the base location description BL.2986 2987 The action is the same as for ``DW_OP_LLVM_bit_overlay``, except that the2988 overlay bit size BS and overlay bit offset BO used are S and O respectively2989 scaled by 8 (the byte size).2990 29917. ``DW_OP_LLVM_bit_overlay`` *New*2992 2993 ``DW_OP_LLVM_bit_overlay`` pops four stack entries. The first must be an2994 integral type value that represents the overlay bit size value BS. The2995 second must be an integral type value that represents the overlay bit offset2996 value BO. The third must be a location description that represents the2997 overlay location description OL. The fourth must be a location description2998 that represents the base location description BL.2999 3000 The DWARF expression is ill-formed if BS or BO are negative values.3001 3002 *rbss(L)* is the minimum remaining bit storage size of L which is defined as3003 follows. LS is the location storage and LO is the location bit offset3004 specified by a single location description SL of L. The remaining bit3005 storage size RBSS of SL is the bit size of LS minus LO. *rbss(L)* is the3006 minimum RBSS of each single location description SL of L.3007 3008 The DWARF expression is ill-formed if *rbss(BL)* is less than BO plus BS.3009 3010 If BS is 0, then the operation pushes BL.3011 3012 If BO is 0 and BS equals *rbss(BL)*, then the operation pushes OL.3013 3014 Otherwise, the operation is equivalent to performing the following steps to3015 push a composite location description.3016 3017 *The composite location description is conceptually the base location3018 description BL with the overlay location description OL positioned as an3019 overlay starting at the overlay offset BO and covering overlay bit size BS.*3020 3021 1. If BO is not 0 then push BL followed by performing the ``DW_OP_bit_piece3022 BO, 0`` operation.3023 2. Push OL followed by performing the ``DW_OP_bit_piece BS, 0`` operation.3024 3. If *rbss(BL)* is greater than BO plus BS, push BL followed by performing3025 the ``DW_OP_bit_piece (rbss(BL) - BO - BS), (BO + BS)`` operation.3026 4. Perform the ``DW_OP_LLVM_piece_end`` operation.3027 3028.. _amdgpu-dwarf-location-list-expressions:3029 3030A.2.5.5 DWARF Location List Expressions3031+++++++++++++++++++++++++++++++++++++++3032 3033.. note::3034 3035 This section replaces DWARF Version 5 section 2.6.2.3036 3037*To meet the needs of recent computer architectures and optimization techniques,3038debugging information must be able to describe the location of an object whose3039location changes over the object’s lifetime, and may reside at multiple3040locations during parts of an object's lifetime. Location list expressions are3041used in place of operation expressions whenever the object whose location is3042being described has these requirements.*3043 3044A location list expression consists of a series of location list entries. Each3045location list entry is one of the following kinds:3046 3047*Bounded location description*3048 3049 This kind of location list entry provides an operation expression that3050 evaluates to the location description of an object that is valid over a3051 lifetime bounded by a starting and ending address. The starting address is the3052 lowest address of the address range over which the location is valid. The3053 ending address is the address of the first location past the highest address3054 of the address range.3055 3056 The location list entry matches when the current program location is within3057 the given range.3058 3059 There are several kinds of bounded location description entries which differ3060 in the way that they specify the starting and ending addresses.3061 3062*Default location description*3063 3064 This kind of location list entry provides an operation expression that3065 evaluates to the location description of an object that is valid when no3066 bounded location description entry applies.3067 3068 The location list entry matches when the current program location is not3069 within the range of any bounded location description entry.3070 3071*Base address*3072 3073 This kind of location list entry provides an address to be used as the base3074 address for beginning and ending address offsets given in certain kinds of3075 bounded location description entries. The applicable base address of a bounded3076 location description entry is the address specified by the closest preceding3077 base address entry in the same location list. If there is no preceding base3078 address entry, then the applicable base address defaults to the base address3079 of the compilation unit (see DWARF Version 5 section 3.1.1).3080 3081 In the case of a compilation unit where all of the machine code is contained3082 in a single contiguous section, no base address entry is needed.3083 3084*End-of-list*3085 3086 This kind of location list entry marks the end of the location list3087 expression.3088 3089The address ranges defined by the bounded location description entries of a3090location list expression may overlap. When they do, they describe a situation in3091which an object exists simultaneously in more than one place.3092 3093If all of the address ranges in a given location list expression do not3094collectively cover the entire range over which the object in question is3095defined, and there is no following default location description entry, it is3096assumed that the object is not available for the portion of the range that is3097not covered.3098 3099The result of the evaluation of a DWARF location list expression is:3100 3101* If the current program location is not specified, then it is an evaluation3102 error.3103 3104 .. note::3105 3106 If the location list only has a single default entry, should that be3107 considered a match if there is no program location? If there are non-default3108 entries then it seems it has to be an evaluation error when there is no3109 program location as that indicates the location depends on the program3110 location which is not known.3111 3112* If there are no matching location list entries, then the result is a location3113 description that comprises one undefined location description.3114 3115* Otherwise, the operation expression E of each matching location list entry is3116 evaluated with the current context, except that the result kind is a location3117 description, the object is unspecified, and the initial stack is empty. The3118 location list entry result is the location description returned by the3119 evaluation of E.3120 3121 The result is a location description that is comprised of the union of the3122 single location descriptions of the location description result of each3123 matching location list entry.3124 3125A location list expression can only be used as the value of a debugger3126information entry attribute that is encoded using class ``loclist`` or3127``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the3128attribute provides an index into a separate object file section called3129``.debug_loclists`` or ``.debug_loclists.dwo`` (for split DWARF object files)3130that contains the location list entries.3131 3132A ``DW_OP_call*`` and ``DW_OP_implicit_pointer`` operation can be used to3133specify a debugger information entry attribute that has a location list3134expression. Several debugger information entry attributes allow DWARF3135expressions that are evaluated with an initial stack that includes a location3136description that may originate from the evaluation of a location list3137expression.3138 3139*This location list representation, the* ``loclist`` *and* ``loclistsptr``3140*class, and the related* ``DW_AT_loclists_base`` *attribute are new in DWARF3141Version 5. Together they eliminate most, or all of the code object relocations3142previously needed for location list expressions.*3143 3144.. note::3145 3146 The rest of this section is the same as DWARF Version 5 section 2.6.2.3147 3148.. _amdgpu-dwarf-address-spaces:3149 3150A.2.13 Address Spaces3151~~~~~~~~~~~~~~~~~~~~~3152 3153.. note::3154 3155 This is a new section after DWARF Version 5 section 2.12 Segmented Addresses.3156 3157DWARF address spaces correspond to target architecture specific linear3158addressable memory areas. They are used in DWARF expression location3159descriptions to describe in which target architecture specific memory area data3160resides.3161 3162*Target architecture specific DWARF address spaces may correspond to hardware3163supported facilities such as memory utilizing base address registers, scratchpad3164memory, and memory with special interleaving. The size of addresses in these3165address spaces may vary. Their access and allocation may be hardware managed3166with each thread or group of threads having access to independent storage. For3167these reasons they may have properties that do not allow them to be viewed as3168part of the unified global virtual address space accessible by all threads.*3169 3170*It is target architecture specific whether multiple DWARF address spaces are3171supported and how source language memory spaces map to target architecture3172specific DWARF address spaces. A target architecture may map multiple source3173language memory spaces to the same target architecture specific DWARF address3174class. Optimization may determine that variable lifetime and access pattern3175allows them to be allocated in faster scratchpad memory represented by a3176different DWARF address space than the default for the source language memory3177space.*3178 3179Although DWARF address space identifiers are target architecture specific,3180``DW_ASPACE_LLVM_none`` is a common address space supported by all target3181architectures, and defined as the target architecture default address space.3182 3183DWARF address space identifiers are used by:3184 3185* The ``DW_AT_LLVM_address_space`` attribute.3186 3187* The DWARF expression operations: ``DW_OP_aspace_bregx``,3188 ``DW_OP_form_aspace_address``, ``DW_OP_aspace_implicit_pointer``, and3189 ``DW_OP_xderef*``.3190 3191* The CFI instructions: ``DW_CFA_def_aspace_cfa`` and3192 ``DW_CFA_def_aspace_cfa_sf``.3193 3194.. note::3195 3196 Currently, DWARF defines address class values as being target architecture3197 specific, and defines a DW_AT_address_class attribute. With the removal of3198 DW_AT_segment in DWARF 6, it is unclear how the address class is intended to3199 be used as the term is not used elsewhere. Should these be replaced by this3200 proposal's more complete address space? Or are they intended to represent3201 source language memory spaces such as in OpenCL?3202 3203.. _amdgpu-dwarf-memory-spaces:3204 3205A.2.14 Memory Spaces3206~~~~~~~~~~~~~~~~~~~~3207 3208.. note::3209 3210 This is a new section after DWARF Version 5 section 2.12 Segmented Addresses.3211 3212DWARF memory spaces are used for source languages that have the concept of3213memory spaces. They are used in the ``DW_AT_LLVM_memory_space`` attribute for3214pointer type, reference type, variable, formal parameter, and constant debugger3215information entries.3216 3217Each DWARF memory space is conceptually a separate source language memory space3218with its own lifetime and aliasing rules. DWARF memory spaces are used to3219specify the source language memory spaces that pointer type and reference type3220values refer, and to specify the source language memory space in which variables3221are allocated.3222 3223Although DWARF memory space identifiers are source language specific,3224``DW_MSPACE_LLVM_none`` is a common memory space supported by all source3225languages, and defined as the source language default memory space.3226 3227The set of currently defined DWARF memory spaces, together with source language3228mappings, is given in :ref:`amdgpu-dwarf-source-language-memory-spaces-table`.3229 3230Vendor defined source language memory spaces may be defined using codes in the3231range ``DW_MSPACE_LLVM_lo_user`` to ``DW_MSPACE_LLVM_hi_user``.3232 3233.. table:: Source language memory spaces3234 :name: amdgpu-dwarf-source-language-memory-spaces-table3235 3236 =========================== ============ ============== ============== ==============3237 Memory Space Name Meaning C/C++ OpenCL CUDA/HIP3238 =========================== ============ ============== ============== ==============3239 ``DW_MSPACE_LLVM_none`` generic *default* generic *default*3240 ``DW_MSPACE_LLVM_global`` global global3241 ``DW_MSPACE_LLVM_constant`` constant constant constant3242 ``DW_MSPACE_LLVM_group`` thread-group local shared3243 ``DW_MSPACE_LLVM_private`` thread private3244 ``DW_MSPACE_LLVM_lo_user``3245 ``DW_MSPACE_LLVM_hi_user``3246 =========================== ============ ============== ============== ==============3247 3248.. note::3249 3250 The approach presented in3251 :ref:`amdgpu-dwarf-source-language-memory-spaces-table` is to define the3252 default ``DW_MSPACE_LLVM_none`` to be the generic address class and not the3253 global address class. This matches how CLANG and LLVM have added support for3254 CUDA-like languages on top of existing C++ language support. This allows all3255 addresses to be generic by default which matches CUDA-like languages.3256 3257 An alternative approach is to define ``DW_MSPACE_LLVM_none`` as being the3258 global memory space and then change ``DW_MSPACE_LLVM_global`` to3259 ``DW_MSPACE_LLVM_generic``. This would match the reality that languages that3260 do not support multiple memory spaces only have one default global memory3261 space. Generally, in these languages if they expose that the target3262 architecture supports multiple memory spaces, the default one is still the3263 global memory space. Then a language that does support multiple memory spaces3264 has to explicitly indicate which pointers have the added ability to reference3265 more than the global memory space. However, compilers generating DWARF for3266 CUDA-like languages would then have to define every CUDA-like language pointer3267 type or reference type with a ``DW_AT_LLVM_memory_space`` attribute of3268 ``DW_MSPACE_LLVM_generic`` to match the language semantics.3269 3270A.3 Program Scope Entries3271-------------------------3272 3273.. note::3274 3275 This section provides changes to existing debugger information entry3276 attributes. These would be incorporated into the corresponding DWARF Version 53277 chapter 3 sections.3278 3279A.3.1 Unit Entries3280~~~~~~~~~~~~~~~~~~3281 3282.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries:3283 3284A.3.1.1 Full and Partial Compilation Unit Entries3285+++++++++++++++++++++++++++++++++++++++++++++++++3286 3287.. note::3288 3289 This augments DWARF Version 5 section 3.1.1 and Table 3.1.3290 3291Additional language codes defined for use with the ``DW_AT_language`` attribute3292are defined in :ref:`amdgpu-dwarf-language-names-table`.3293 3294.. table:: Language Names3295 :name: amdgpu-dwarf-language-names-table3296 3297 ==================== =============================3298 Language Name Meaning3299 ==================== =============================3300 ``DW_LANG_LLVM_HIP`` HIP Language.3301 ==================== =============================3302 3303The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending3304the C++ language.3305 3306.. note::3307 3308 The following new attribute is added.3309 33101. A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit3311 may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an3312 augmentation string.3313 3314 *The augmentation string allows producers to indicate that there is3315 additional vendor or target specific information in the debugging3316 information entries. For example, this might be information about the3317 version of vendor specific extensions that are being used.*3318 3319 If not present, or if the string is empty, then the compilation unit has no3320 augmentation string.3321 3322 The format for the augmentation string is:3323 3324 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *3325 3326 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y3327 version number of the extensions used, and *options* is an optional string3328 providing additional information about the extensions. The version number3329 must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`].3330 The *options* string must not contain the "\ ``]``\ " character.3331 3332 For example:3333 3334 ::3335 3336 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3]3337 3338A.3.3 Subroutine and Entry Point Entries3339~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3340 3341.. _amdgpu-dwarf-low-level-information:3342 3343A.3.3.5 Low-Level Information3344+++++++++++++++++++++++++++++3345 33461. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or3347 ``DW_TAG_entry_point`` debugger information entry may have a3348 ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E.3349 3350 The result of the attribute is obtained by evaluating E with a context that3351 has a result kind of a location description, an unspecified object, the3352 compilation unit that contains E, an empty initial stack, and other context3353 elements corresponding to the source language thread of execution upon which3354 the user is focused, if any. The result of the evaluation is the location3355 description L of the place where the return address for the current call3356 frame's subprogram or entry point is stored.3357 3358 The DWARF is ill-formed if L is not comprised of one memory location3359 description for one of the target architecture specific address spaces.3360 3361 .. note::3362 3363 It is unclear why ``DW_TAG_inlined_subroutine`` has a3364 ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or3365 ``DW_AT_static_link`` attribute. Seems it would either have all of them or3366 none. Since inlined subprograms do not have a call frame it seems they3367 would have none of these attributes.3368 33692. A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry3370 may have a ``DW_AT_frame_base`` attribute, whose value is a DWARF expression3371 E.3372 3373 The result of the attribute is obtained by evaluating E with a context that3374 has a result kind of a location description, an unspecified object, the3375 compilation unit that contains E, an empty initial stack, and other context3376 elements corresponding to the source language thread of execution upon which3377 the user is focused, if any.3378 3379 The DWARF is ill-formed if E contains a ``DW_OP_fbreg`` operation, or the3380 resulting location description L is not comprised of one single location3381 description SL.3382 3383 If SL is a register location description for register R, then L is replaced3384 with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This3385 computes the frame base memory location description in the target3386 architecture default address space.3387 3388 *This allows the more compact* ``DW_OP_reg*`` *to be used instead of*3389 ``DW_OP_breg* 0``\ *.*3390 3391 .. note::3392 3393 This rule could be removed and require the producer to create the required3394 location description directly using ``DW_OP_call_frame_cfa``,3395 ``DW_OP_breg*``, or ``DW_OP_LLVM_aspace_bregx``. This would also then3396 allow a target to implement the call frames within a large register.3397 3398 Otherwise, the DWARF is ill-formed if SL is not a memory location3399 description in any of the target architecture specific address spaces.3400 3401 The resulting L is the *frame base* for the subprogram or entry point.3402 3403 *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a3404 stack pointer register plus or minus some offset.*3405 3406 *The frame base for a subprogram is typically an address relative to the3407 first unit of storage allocated for the subprogram's stack frame. The*3408 ``DW_AT_frame_base`` *attribute can be used in several ways:*3409 3410 1. *In subprograms that need location lists to locate local variables, the*3411 ``DW_AT_frame_base`` *can hold the needed location list, while all3412 variables' location descriptions can be simpler ones involving the frame3413 base.*3414 3415 2. *It can be used in resolving "up-level" addressing within3416 nested routines. (See also* ``DW_AT_static_link``\ *, below)*3417 3418 *Some languages support nested subroutines. In such languages, it is3419 possible to reference the local variables of an outer subroutine from within3420 an inner subroutine. The* ``DW_AT_static_link`` *and* ``DW_AT_frame_base``3421 *attributes allow debuggers to support this same kind of referencing.*3422 34233. If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information3424 entry is lexically nested, it may have a ``DW_AT_static_link`` attribute,3425 whose value is a DWARF expression E.3426 3427 The result of the attribute is obtained by evaluating E with a context that3428 has a result kind of a location description, an unspecified object, the3429 compilation unit that contains E, an empty initial stack, and other context3430 elements corresponding to the source language thread of execution upon which3431 the user is focused, if any. The result of the evaluation is the location3432 description L of the *canonical frame address* (see3433 :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of3434 the subprogram instance that immediately lexically encloses the current call3435 frame's subprogram or entry point.3436 3437 The DWARF is ill-formed if L is not comprised of one memory location3438 description for one of the target architecture specific address spaces.3439 3440 In the context of supporting nested subroutines, the DW_AT_frame_base3441 attribute value obeys the following constraints:3442 3443 1. It computes a value that does not change during the life of the3444 subprogram, and3445 3446 2. The computed value is unique among instances of the same subroutine.3447 3448 *For typical DW_AT_frame_base use, this means that a recursive subroutine's3449 stack frame must have non-zero size.*3450 3451 *If a debugger is attempting to resolve an up-level reference to a variable,3452 it uses the nesting structure of DWARF to determine which subroutine is the3453 lexical parent and the* ``DW_AT_static_link`` *value to identify the3454 appropriate active frame of the parent. It can then attempt to find the3455 reference within the context of the parent.*3456 3457 .. note::3458 3459 The following new attributes are added.3460 34614. For languages that are implemented using a SIMT execution model, a3462 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or3463 ``DW_TAG_entry_point`` debugger information entry may have a3464 ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is3465 the number of source language threads of execution per target architecture3466 thread.3467 3468 *For example, a compiler may map source language threads of execution onto3469 lanes of a target architecture thread using a SIMT execution model.*3470 3471 It is the static number of source language threads of execution per target3472 architecture thread. It is not the dynamic number of source language threads3473 of execution with which the target architecture thread was initiated, for3474 example, due to smaller or partial work-groups.3475 3476 If not present, the default value of 1 is used.3477 3478 The DWARF is ill-formed if the value is less than or equal to 0.3479 34805. For source languages that are implemented using a SIMT execution model, a3481 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or3482 ``DW_TAG_entry_point`` debugging information entry may have a3483 ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E.3484 3485 The result of the attribute is obtained by evaluating E with a context that3486 has a result kind of a location description, an unspecified object, the3487 compilation unit that contains E, an empty initial stack, and other context3488 elements corresponding to the source language thread of execution upon which3489 the user is focused, if any.3490 3491 The resulting location description L is for a lane count sized vector of3492 generic type elements. The lane count is the value of the3493 ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program3494 location of the corresponding lane. If the lane was not active when the3495 current subprogram was called, its element is an undefined location3496 description.3497 3498 The DWARF is ill-formed if L does not have exactly one single location3499 description.3500 3501 ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where3502 each SIMT lane of a target architecture thread is positioned even when it is3503 in divergent control flow that is not active.*3504 3505 *Typically, the result is a location description with one composite location3506 description with each part being a location description with either one3507 undefined location description or one memory location description.*3508 3509 If not present, the target architecture thread is not being used in a SIMT3510 manner, and the thread's current program location is used.3511 35126. For languages that are implemented using a SIMT execution model, a3513 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or3514 ``DW_TAG_entry_point`` debugger information entry may have a3515 ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E.3516 3517 E is evaluated with a context that has a result kind of a location3518 description, an unspecified object, the compilation unit that contains E, an3519 empty initial stack, and other context elements corresponding to the source3520 language thread of execution upon which the user is focused, if any.3521 3522 The DWARF is ill-formed if L does not have exactly one single location3523 description SL.3524 3525 The active lane bit mask V for the current program location is obtained by3526 reading from SL using a target architecture specific integral base type T3527 that has a bit size equal to the value of the ``DW_AT_LLVM_lanes`` attribute3528 of the subprogram corresponding to context's frame and program location. The3529 N\ :sup:`th` least significant bit of the mask corresponds to the N\3530 :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is3531 inactive. The result of the attribute is the value V.3532 3533 *Some targets may update the target architecture execution mask for regions3534 of code that must execute with different sets of lanes than the current3535 active lanes. For example, some code must execute with all lanes made3536 temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to3537 provide the means to determine the source language active lanes at any3538 program location. Typically, this attribute will use a loclist to express3539 different locations of the active lane mask at different program locations.*3540 3541 If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target3542 architecture execution mask is used.3543 35447. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or3545 ``DW_TAG_entry_point`` debugger information entry may have a3546 ``DW_AT_LLVM_iterations`` attribute whose value is an integer constant or a3547 DWARF expression E. Its value is the number of source language loop3548 iterations executing concurrently by the target architecture for a single3549 source language thread of execution.3550 3551 *A compiler may generate code that executes more than one iteration of a3552 source language loop concurrently using optimization techniques such as3553 software pipelining or SIMD vectorization. The number of concurrent3554 iterations may vary for different loop nests in the same subprogram.3555 Typically, this attribute will use a loclist to express different values at3556 different program locations.*3557 3558 If the attribute is an integer constant, then the value is the constant. The3559 DWARF is ill-formed if the constant is less than or equal to 0.3560 3561 Otherwise, E is evaluated with a context that has a result kind of a3562 location description, an unspecified object, the compilation unit that3563 contains E, an empty initial stack, and other context elements corresponding3564 to the source language thread of execution upon which the user is focused,3565 if any. The DWARF is ill-formed if the result is not a location description3566 comprised of one implicit location description, that when read as the3567 generic type, results in a value V that is less than or equal to 0. The3568 result of the attribute is the value V.3569 3570 If not present, the default value of 1 is used.3571 3572A.3.4 Call Site Entries and Parameters3573~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3574 3575A.3.4.2 Call Site Parameters3576++++++++++++++++++++++++++++3577 35781. The call site entry may own ``DW_TAG_call_site_parameter`` debugging3579 information entries representing the parameters passed to the call. Call3580 site parameter entries occur in the same order as the corresponding3581 parameters in the source. Each such entry has a ``DW_AT_location`` attribute3582 which is a location description. This location description describes where3583 the parameter is passed (usually either some register, or a memory location3584 expressible as the contents of the stack register plus some offset).3585 35862. A ``DW_TAG_call_site_parameter`` debugger information entry may have a3587 ``DW_AT_call_value`` attribute, whose value is a DWARF operation expression3588 E\ :sub:`1`\ .3589 3590 The result of the ``DW_AT_call_value`` attribute is obtained by evaluating3591 E\ :sub:`1` with a context that has a result kind of a value, an unspecified3592 object, the compilation unit that contains E, an empty initial stack, and3593 other context elements corresponding to the source language thread of3594 execution upon which the user is focused, if any. The resulting value V\3595 :sub:`1` is the value of the parameter at the time of the call made by the3596 call site.3597 3598 For parameters passed by reference, where the code passes a pointer to a3599 location which contains the parameter, or for reference type parameters, the3600 ``DW_TAG_call_site_parameter`` debugger information entry may also have a3601 ``DW_AT_call_data_location`` attribute whose value is a DWARF operation3602 expression E\ :sub:`2`\ , and a ``DW_AT_call_data_value`` attribute whose3603 value is a DWARF operation expression E\ :sub:`3`\ .3604 3605 The value of the ``DW_AT_call_data_location`` attribute is obtained by3606 evaluating E\ :sub:`2` with a context that has a result kind of a location3607 description, an unspecified object, the compilation unit that contains E, an3608 empty initial stack, and other context elements corresponding to the source3609 language thread of execution upon which the user is focused, if any. The3610 resulting location description L\ :sub:`2` is the location where the3611 referenced parameter lives during the call made by the call site. If E\3612 :sub:`2` would just be a ``DW_OP_push_object_address``, then the3613 ``DW_AT_call_data_location`` attribute may be omitted.3614 3615 .. note::3616 3617 The DWARF Version 5 implies that ``DW_OP_push_object_address`` may be used3618 but does not state what object must be specified in the context. Either3619 ``DW_OP_push_object_address`` cannot be used, or the object to be passed3620 in the context must be defined.3621 3622 The value of the ``DW_AT_call_data_value`` attribute is obtained by3623 evaluating E\ :sub:`3` with a context that has a result kind of a value, an3624 unspecified object, the compilation unit that contains E, an empty initial3625 stack, and other context elements corresponding to the source language3626 thread of execution upon which the user is focused, if any. The resulting3627 value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made3628 by the call site.3629 3630 The result of these attributes is undefined if the current call frame is not3631 for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger3632 information entry or the current program location is not for the call site3633 containing the ``DW_TAG_call_site_parameter`` debugger information entry in3634 the current call frame.3635 3636 *The consumer may have to virtually unwind to the call site (see*3637 :ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these3638 attributes. This will ensure the source language thread of execution upon3639 which the user is focused corresponds to the call site needed to evaluate3640 the expression.*3641 3642 If it is not possible to avoid the expressions of these attributes from3643 accessing registers or memory locations that might be clobbered by the3644 subprogram being called by the call site, then the associated attribute3645 should not be provided.3646 3647 *The reason for the restriction is that the parameter may need to be3648 accessed during the execution of the callee. The consumer may virtually3649 unwind from the called subprogram back to the caller and then evaluate the3650 attribute expressions. The call frame information (see*3651 :ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore3652 registers that have been clobbered, and clobbered memory will no longer have3653 the value at the time of the call.*3654 36553. Each call site parameter entry may also have a ``DW_AT_call_parameter``3656 attribute which contains a reference to a ``DW_TAG_formal_parameter`` entry,3657 ``DW_AT_type attribute`` referencing the type of the parameter or3658 ``DW_AT_name`` attribute describing the parameter's name.3659 3660*Examples using call site entries and related attributes are found in Appendix3661D.15.*3662 3663.. _amdgpu-dwarf-lexical-block-entries:3664 3665A.3.5 Lexical Block Entries3666~~~~~~~~~~~~~~~~~~~~~~~~~~~3667 3668.. note::3669 3670 This section is the same as DWARF Version 5 section 3.5.3671 3672A.4 Data Object and Object List Entries3673---------------------------------------3674 3675.. note::3676 3677 This section provides changes to existing debugger information entry3678 attributes. These would be incorporated into the corresponding DWARF Version 53679 chapter 4 sections.3680 3681.. _amdgpu-dwarf-data-object-entries:3682 3683A.4.1 Data Object Entries3684~~~~~~~~~~~~~~~~~~~~~~~~~3685 3686Program variables, formal parameters and constants are represented by debugging3687information entries with the tags ``DW_TAG_variable``,3688``DW_TAG_formal_parameter`` and ``DW_TAG_constant``, respectively.3689 3690*The tag DW_TAG_constant is used for languages that have true named constants.*3691 3692The debugging information entry for a program variable, formal parameter or3693constant may have the following attributes:3694 36951. A ``DW_AT_location`` attribute, whose value is a DWARF expression E that3696 describes the location of a variable or parameter at run-time.3697 3698 The result of the attribute is obtained by evaluating E with a context that3699 has a result kind of a location description, an unspecified object, the3700 compilation unit that contains E, an empty initial stack, and other context3701 elements corresponding to the source language thread of execution upon which3702 the user is focused, if any. The result of the evaluation is the location3703 description of the base of the data object.3704 3705 See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules3706 used by the ``DW_OP_call*`` operations.3707 3708 .. note::3709 3710 Delete the description of how the ``DW_OP_call*`` operations evaluate a3711 ``DW_AT_location`` attribute as that is now described in the operations.3712 3713 .. note::3714 3715 See the discussion about the ``DW_AT_location`` attribute in the3716 ``DW_OP_call*`` operation. Having each attribute only have a single3717 purpose and single execution semantics seems desirable. It makes it easier3718 for the consumer that no longer have to track the context. It makes it3719 easier for the producer as it can rely on a single semantics for each3720 attribute.3721 3722 For that reason, limiting the ``DW_AT_location`` attribute to only3723 supporting evaluating the location description of an object, and using a3724 different attribute and encoding class for the evaluation of DWARF3725 expression *procedures* on the same operation expression stack seems3726 desirable.3727 37282. ``DW_AT_const_value``3729 3730 .. note::3731 3732 Could deprecate using the ``DW_AT_const_value`` attribute for3733 ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information3734 entries that have been optimized to a constant. Instead,3735 ``DW_AT_location`` could be used with a DWARF expression that produces an3736 implicit location description now that any location description can be3737 used within a DWARF expression. This allows the ``DW_OP_call*`` operations3738 to be used to push the location description of any variable regardless of3739 how it is optimized.3740 37413. ``DW_AT_LLVM_memory_space``3742 3743 A ``DW_AT_memory_space`` attribute with a constant value representing a source3744 language specific DWARF memory space (see 2.14 "Memory Spaces"). If omitted,3745 defaults to ``DW_MSPACE_none``.3746 3747 3748A.4.2 Common Block Entries3749~~~~~~~~~~~~~~~~~~~~~~~~~~3750 3751A common block entry also has a ``DW_AT_location`` attribute whose value is a3752DWARF expression E that describes the location of the common block at run-time.3753The result of the attribute is obtained by evaluating E with a context that has3754a result kind of a location description, an unspecified object, the compilation3755unit that contains E, an empty initial stack, and other context elements3756corresponding to the source language thread of execution upon which the user is3757focused, if any. The result of the evaluation is the location description of the3758base of the common block. See :ref:`amdgpu-dwarf-control-flow-operations` for3759special evaluation rules used by the ``DW_OP_call*`` operations.3760 3761A.5 Type Entries3762----------------3763 3764.. note::3765 3766 This section provides changes to existing debugger information entry3767 attributes. These would be incorporated into the corresponding DWARF Version 53768 chapter 5 sections.3769 3770.. _amdgpu-dwarf-base-type-entries:3771 3772A.5.1 Base Type Entries3773~~~~~~~~~~~~~~~~~~~~~~~3774 3775.. note::3776 3777 The following new attribute is added.3778 37791. A ``DW_TAG_base_type`` debugger information entry for a base type T may have3780 a ``DW_AT_LLVM_vector_size`` attribute whose value is an integer constant3781 that is the vector type size N.3782 3783 The representation of a vector base type is as N contiguous elements, each3784 one having the representation of a base type T' that is the same as T3785 without the ``DW_AT_LLVM_vector_size`` attribute.3786 3787 If a ``DW_TAG_base_type`` debugger information entry does not have a3788 ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector3789 type.3790 3791 The DWARF is ill-formed if N is not greater than 0.3792 3793 .. note::3794 3795 LLVM has mention of a non-upstreamed debugger information entry that is3796 intended to support vector types. However, that was not for a base type so3797 would not be suitable as the type of a stack value entry. But perhaps that3798 could be replaced by using this attribute.3799 3800 .. note::3801 3802 Compare this with the ``DW_AT_GNU_vector`` extension supported by GNU. Is3803 it better to add an attribute to the existing ``DW_TAG_base_type`` debug3804 entry, or allow some forms of ``DW_TAG_array_type`` (those that have the3805 ``DW_AT_GNU_vector`` attribute) to be used as stack entry value types?3806 38072. A ``DW_TAG_base_type`` debugger information entry with the encoding3808 ``DW_ATE_address`` may have a ``DW_AT_LLVM_address_space`` attribute whose3809 value is an architecture specific address space (see3810 :ref:`amdgpu-dwarf-address-spaces`). If omitted it defaults to3811 ``DW_ASPACE_LLVM_none``.3812 3813.. _amdgpu-dwarf-type-modifier-entries:3814 3815A.5.3 Type Modifier Entries3816~~~~~~~~~~~~~~~~~~~~~~~~~~~3817 3818.. note::3819 3820 This section augments DWARF Version 5 section 5.3.3821 3822A modified type entry describing a pointer or reference type (using3823``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or3824``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_memory_space``3825attribute with a constant value representing a source language specific DWARF3826memory space (see :ref:`amdgpu-dwarf-memory-spaces`). If omitted, defaults to3827DW_MSPACE_LLVM_none.3828 3829A modified type entry describing a pointer or reference type (using3830``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or3831``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_address_space``3832attribute with a constant value AS representing an architecture specific DWARF3833address space (see :ref:`amdgpu-dwarf-address-spaces`). If omitted, defaults to3834``DW_ASPACE_LLVM_none``. DR is the offset of a hypothetical debug information3835entry D in the current compilation unit for an integral base type matching the3836address size of AS. An object P having the given pointer or reference type are3837dereferenced as if the ``DW_OP_push_object_address; DW_OP_deref_type DR;3838DW_OP_constu AS; DW_OP_form_aspace_address`` operation expression was evaluated3839with the current context except: the result kind is location description; the3840initial stack is empty; and the object is the location description of P.3841 3842.. note::3843 3844 What if the current context does not have a current target architecture3845 defined?3846 3847.. note::3848 3849 With the expanded support for DWARF address spaces, it may be worth examining3850 if they can be used for what was formerly supported by DWARF 5 segments. That3851 would include specifying the address space of all code addresses (compilation3852 units, subprograms, subprogram entries, labels, subprogram types, etc.).3853 Either the code address attributes could be extended to allow a exprloc form3854 (so that ``DW_OP_form_aspace_address`` can be used) or the3855 ``DW_AT_LLVM_address_space`` attribute be allowed on all DIEs that allow3856 ``DW_AT_segment``.3857 3858A.5.7 Structure, Union, Class and Interface Type Entries3859~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3860 3861A.5.7.3 Derived or Extended Structures, Classes and Interfaces3862++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++3863 38641. For a ``DW_AT_data_member_location`` attribute there are two cases:3865 3866 1. If the attribute is an integer constant B, it provides the offset in3867 bytes from the beginning of the containing entity.3868 3869 The result of the attribute is obtained by evaluating a3870 ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the3871 location description of the beginning of the containing entity. The3872 result of the evaluation is the location description of the base of the3873 member entry.3874 3875 *If the beginning of the containing entity is not byte aligned, then the3876 beginning of the member entry has the same bit displacement within a3877 byte.*3878 3879 2. Otherwise, the attribute must be a DWARF expression E which is evaluated3880 with a context that has a result kind of a location description, an3881 unspecified object, the compilation unit that contains E, an initial3882 stack comprising the location description of the beginning of the3883 containing entity, and other context elements corresponding to the3884 source language thread of execution upon which the user is focused, if3885 any. The result of the evaluation is the location description of the3886 base of the member entry.3887 3888 .. note::3889 3890 The beginning of the containing entity can now be any location3891 description, including those with more than one single location3892 description, and those with single location descriptions that are of any3893 kind and have any bit offset.3894 3895A.5.7.8 Member Function Entries3896+++++++++++++++++++++++++++++++3897 38981. An entry for a virtual function also has a ``DW_AT_vtable_elem_location``3899 attribute whose value is a DWARF expression E.3900 3901 The result of the attribute is obtained by evaluating E with a context that3902 has a result kind of a location description, an unspecified object, the3903 compilation unit that contains E, an initial stack comprising the location3904 description of the object of the enclosing type, and other context elements3905 corresponding to the source language thread of execution upon which the user3906 is focused, if any. The result of the evaluation is the location description3907 of the slot for the function within the virtual function table for the3908 enclosing class.3909 3910A.5.14 Pointer to Member Type Entries3911~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3912 39131. The ``DW_TAG_ptr_to_member_type`` debugging information entry has a3914 ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is3915 used to compute the location description of the member of the class to which3916 the pointer to member entry points.3917 3918 *The method used to find the location description of a given member of a3919 class, structure, or union is common to any instance of that class,3920 structure, or union and to any instance of the pointer to member type. The3921 method is thus associated with the pointer to member type, rather than with3922 each object that has a pointer to member type.*3923 3924 The ``DW_AT_use_location`` DWARF expression is used in conjunction with the3925 location description for a particular object of the given pointer to member3926 type and for a particular structure or class instance.3927 3928 The result of the attribute is obtained by evaluating E with a context that3929 has a result kind of a location description, an unspecified object, the3930 compilation unit that contains E, an initial stack comprising two entries,3931 and other context elements corresponding to the source language thread of3932 execution upon which the user is focused, if any. The first stack entry is3933 the value of the pointer to member object itself. The second stack entry is3934 the location description of the base of the entire class, structure, or3935 union instance containing the member whose location is being calculated. The3936 result of the evaluation is the location description of the member of the3937 class to which the pointer to member entry points.3938 3939A.5.18 Dynamic Properties of Types3940~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3941 3942A.5.18.1 Data Location3943++++++++++++++++++++++3944 3945*Some languages may represent objects using descriptors to hold information,3946including a location and/or run-time parameters, about the data that represents3947the value for that object.*3948 39491. The ``DW_AT_data_location`` attribute may be used with any type that3950 provides one or more levels of hidden indirection and/or run-time parameters3951 in its representation. Its value is a DWARF operation expression E which3952 computes the location description of the data for an object. When this3953 attribute is omitted, the location description of the data is the same as3954 the location description of the object.3955 3956 The result of the attribute is obtained by evaluating E with a context that3957 has a result kind of a location description, an object that is the location3958 description of the data descriptor, the compilation unit that contains E, an3959 empty initial stack, and other context elements corresponding to the source3960 language thread of execution upon which the user is focused, if any. The3961 result of the evaluation is the location description of the base of the3962 member entry.3963 3964 *E will typically involve an operation expression that begins with a*3965 ``DW_OP_push_object_address`` *operation which loads the location3966 description of the object which can then serve as a descriptor in subsequent3967 calculation.*3968 3969 .. note::3970 3971 Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and3972 ``DW_AT_vtable_elem_location`` allow both operation expressions and3973 location list expressions, why does ``DW_AT_data_location`` not allow3974 both? In all cases they apply to data objects so less likely that3975 optimization would cause different operation expressions for different3976 program location ranges. But if supporting for some then should be for3977 all.3978 3979 It seems odd this attribute is not the same as3980 ``DW_AT_data_member_location`` in having an initial stack with the3981 location description of the object since the expression has to need it.3982 3983A.6 Other Debugging Information3984-------------------------------3985 3986.. note::3987 3988 This section provides changes to existing debugger information entry3989 attributes. These would be incorporated into the corresponding DWARF Version 53990 chapter 6 sections.3991 3992A.6.1 Accelerated Access3993~~~~~~~~~~~~~~~~~~~~~~~~3994 3995.. _amdgpu-dwarf-lookup-by-name:3996 3997A.6.1.1 Lookup By Name3998++++++++++++++++++++++3999 4000A.6.1.1.1 Contents of the Name Index4001####################################4002 4003.. note::4004 4005 The following provides changes to DWARF Version 5 section 6.1.1.1.4006 4007 The rule for debugger information entries included in the name index in the4008 optional ``.debug_names`` section is extended to also include named4009 ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location``4010 attribute that includes a ``DW_OP_LLVM_form_aspace_address`` operation.4011 4012The name index must contain an entry for each debugging information entry that4013defines a named subprogram, label, variable, type, or namespace, subject to the4014following rules:4015 4016* ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location``4017 attribute that includes a ``DW_OP_addr``, ``DW_OP_LLVM_form_aspace_address``,4018 or ``DW_OP_form_tls_address`` operation are included; otherwise, they are4019 excluded.4020 4021A.6.1.1.4 Data Representation of the Name Index4022###############################################4023 4024.. _amdgpu-dwarf-name-index-section-header:4025 4026 4027A.6.1.1.4.1 Section Header4028^^^^^^^^^^^^^^^^^^^^^^^^^^4029 4030.. note::4031 4032 The following provides an addition to DWARF Version 5 section 6.1.1.4.1 item4033 14 ``augmentation_string``.4034 4035A null-terminated UTF-8 vendor specific augmentation string, which provides4036additional information about the contents of this index. If provided, the4037recommended format for augmentation string is:4038 4039 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *4040 4041Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y4042version number of the extensions used in the DWARF of the compilation unit, and4043*options* is an optional string providing additional information about the4044extensions. The version number must conform to semantic versioning [:ref:`SEMVER4045<amdgpu-dwarf-SEMVER>`]. The *options* string must not contain the "\ ``]``\ "4046character.4047 4048For example:4049 4050 ::4051 4052 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3]4053 4054.. note::4055 4056 This is different to the definition in DWARF Version 5 but is consistent with4057 the other augmentation strings and allows multiple vendor extensions to be4058 supported.4059 4060.. _amdgpu-dwarf-line-number-information:4061 4062A.6.2 Line Number Information4063~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4064 4065A.6.2.4 The Line Number Program Header4066++++++++++++++++++++++++++++++++++++++4067 4068A.6.2.4.1 Standard Content Descriptions4069#######################################4070 4071.. note::4072 4073 This augments DWARF Version 5 section 6.2.4.1.4074 4075.. _amdgpu-dwarf-line-number-information-dw-lnct-llvm-source:4076 40771. ``DW_LNCT_LLVM_source``4078 4079 The component is a null-terminated UTF-8 source text string with "\ ``\n``\4080 " line endings. This content code is paired with the same forms as4081 ``DW_LNCT_path``. It can be used for file name entries.4082 4083 The value is an empty null-terminated string if no source is available. If4084 the source is available but is an empty file then the value is a4085 null-terminated single "\ ``\n``\ ".4086 4087 *When the source field is present, consumers can use the embedded source4088 instead of attempting to discover the source on disk using the file path4089 provided by the* ``DW_LNCT_path`` *field. When the source field is absent,4090 consumers can access the file to get the source text.*4091 4092 *This is particularly useful for programming languages that support runtime4093 compilation and runtime generation of source text. In these cases, the4094 source text does not reside in any permanent file. For example, the OpenCL4095 language [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`] supports online compilation.*4096 40972. ``DW_LNCT_LLVM_is_MD5``4098 4099 ``DW_LNCT_LLVM_is_MD5`` indicates if the ``DW_LNCT_MD5`` content kind, if4100 present, is valid: when 0 it is not valid and when 1 it is valid. If4101 ``DW_LNCT_LLVM_is_MD5`` content kind is not present, and ``DW_LNCT_MD5``4102 content kind is present, then the MD5 checksum is valid.4103 4104 ``DW_LNCT_LLVM_is_MD5`` is always paired with the ``DW_FORM_udata`` form.4105 4106 *This allows a compilation unit to have a mixture of files with and without4107 MD5 checksums. This can happen when multiple relocatable files are linked4108 together.*4109 4110.. _amdgpu-dwarf-call-frame-information:4111 4112A.6.4 Call Frame Information4113~~~~~~~~~~~~~~~~~~~~~~~~~~~~4114 4115.. note::4116 4117 This section provides changes to existing call frame information and defines4118 instructions added by these extensions. Additional support is added for4119 address spaces. Register unwind DWARF expressions are generalized to allow any4120 location description, including those with composite and implicit location4121 descriptions.4122 4123 These changes would be incorporated into the DWARF Version 5 section 6.4.4124 4125.. _amdgpu-dwarf-structure_of-call-frame-information:4126 4127A.6.4.1 Structure of Call Frame Information4128+++++++++++++++++++++++++++++++++++++++++++4129 4130The register rules are:4131 4132*undefined*4133 A register that has this rule has no recoverable value in the previous frame.4134 The previous value of this register is the undefined location description (see4135 :ref:`amdgpu-dwarf-undefined-location-description-operations`).4136 4137 *By convention, the register is not preserved by a callee.*4138 4139*same value*4140 This register has not been modified from the previous caller frame.4141 4142 If the current frame is the top frame, then the previous value of this4143 register is the location description L that specifies one register location4144 description SL. SL specifies the register location storage that corresponds to4145 the register with a bit offset of 0 for the current thread.4146 4147 If the current frame is not the top frame, then the previous value of this4148 register is the location description obtained using the call frame information4149 for the callee frame and callee program location invoked by the current caller4150 frame for the same register.4151 4152 *By convention, the register is preserved by the callee, but the callee has4153 not modified it.*4154 4155*offset(N)*4156 N is a signed byte offset. The previous value of this register is saved at the4157 location description computed as if the DWARF operation expression4158 ``DW_OP_LLVM_offset N`` is evaluated with the current context, except the4159 result kind is a location description, the compilation unit is unspecified,4160 the object is unspecified, and an initial stack comprising the location4161 description of the current CFA (see4162 :ref:`amdgpu-dwarf-operation-expressions`).4163 4164*val_offset(N)*4165 N is a signed byte offset. The previous value of this register is the memory4166 byte address of the location description computed as if the DWARF operation4167 expression ``DW_OP_LLVM_offset N`` is evaluated with the current context,4168 except the result kind is a location description, the compilation unit is4169 unspecified, the object is unspecified, and an initial stack comprising the4170 location description of the current CFA (see4171 :ref:`amdgpu-dwarf-operation-expressions`).4172 4173 The DWARF is ill-formed if the CFA location description is not a memory byte4174 address location description, or if the register size does not match the size4175 of an address in the address space of the current CFA location description.4176 4177 *Since the CFA location description is required to be a memory byte address4178 location description, the value of val_offset(N) will also be a memory byte4179 address location description since it is offsetting the CFA location4180 description by N bytes. Furthermore, the value of val_offset(N) will be a4181 memory byte address in the same address space as the CFA location4182 description.*4183 4184 .. note::4185 4186 Should DWARF allow the address size to be a different size to the size of4187 the register? Requiring them to be the same bit size avoids any issue of4188 conversion as the bit contents of the register is simply interpreted as a4189 value of the address.4190 4191 GDB has a per register hook that allows a target-specific conversion on a4192 register by register basis. It defaults to truncation of bigger registers,4193 and to actually reading bytes from the next register (or reads out of bounds4194 for the last register) for smaller registers. There are no GDB tests that4195 read a register out of bounds (except an illegal hand written assembly4196 test).4197 4198*register(R)*4199 This register has been stored in another register numbered R.4200 4201 The previous value of this register is the location description obtained using4202 the call frame information for the current frame and current program location4203 for register R.4204 4205 The DWARF is ill-formed if the size of this register does not match the size4206 of register R or if there is a cyclic dependency in the call frame4207 information.4208 4209 .. note::4210 4211 Should this also allow R to be larger than this register? If so is the value4212 stored in the low order bits and it is undefined what is stored in the4213 extra upper bits?4214 4215*expression(E)*4216 The previous value of this register is located at the location description4217 produced by evaluating the DWARF operation expression E (see4218 :ref:`amdgpu-dwarf-operation-expressions`).4219 4220 E is evaluated with the current context, except the result kind is a location4221 description, the compilation unit is unspecified, the object is unspecified,4222 and an initial stack comprising the location description of the current CFA4223 (see :ref:`amdgpu-dwarf-operation-expressions`).4224 4225*val_expression(E)*4226 The previous value of this register is located at the implicit location4227 description created from the value produced by evaluating the DWARF operation4228 expression E (see :ref:`amdgpu-dwarf-operation-expressions`).4229 4230 E is evaluated with the current context, except the result kind is a value,4231 the compilation unit is unspecified, the object is unspecified, and an initial4232 stack comprising the location description of the current CFA (see4233 :ref:`amdgpu-dwarf-operation-expressions`).4234 4235 The DWARF is ill-formed if the resulting value type size does not match the4236 register size.4237 4238 .. note::4239 4240 This has limited usefulness as the DWARF expression E can only produce4241 values up to the size of the generic type. This is due to not allowing any4242 operations that specify a type in a CFI operation expression. This makes it4243 unusable for registers that are larger than the generic type. However,4244 *expression(E)* can be used to create an implicit location description of4245 any size.4246 4247*architectural*4248 The rule is defined externally to this specification by the augmenter.4249 4250*This table would be extremely large if actually constructed as described. Most4251of the entries at any point in the table are identical to the ones above them.4252The whole table can be represented quite compactly by recording just the4253differences starting at the beginning address of each subroutine in the4254program.*4255 4256The virtual unwind information is encoded in a self-contained section called4257``.debug_frame``. Entries in a ``.debug_frame`` section are aligned on a4258multiple of the address size relative to the start of the section and come in4259two forms: a Common Information Entry (CIE) and a Frame Description Entry (FDE).4260 4261*If the range of code addresses for a function is not contiguous, there may be4262multiple CIEs and FDEs corresponding to the parts of that function.*4263 4264A Common Information Entry (CIE) holds information that is shared among many4265Frame Description Entries (FDE). There is at least one CIE in every non-empty4266``.debug_frame`` section. A CIE contains the following fields, in order:4267 42681. ``length`` (initial length)4269 4270 A constant that gives the number of bytes of the CIE structure, not4271 including the length field itself (see Section 7.2.2 Initial Length Values).4272 The size of the length field plus the value of length must be an integral4273 multiple of the address size specified in the ``address_size`` field.4274 42752. ``CIE_id`` (4 or 8 bytes, see4276 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`)4277 4278 A constant that is used to distinguish CIEs from FDEs.4279 4280 In the 32-bit DWARF format, the value of the CIE id in the CIE header is4281 0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.4282 42833. ``version`` (ubyte)4284 4285 A version number (see Section 7.24 Call Frame Information). This number is4286 specific to the call frame information and is independent of the DWARF4287 version number.4288 4289 The value of the CIE version number is 4.4290 4291 .. note::4292 4293 Would this be increased to 5 to reflect the changes in these extensions?4294 42954. ``augmentation`` (sequence of UTF-8 characters)4296 4297 A null-terminated UTF-8 string that identifies the augmentation to this CIE4298 or to the FDEs that use it. If a reader encounters an augmentation string4299 that is unexpected, then only the following fields can be read:4300 4301 * CIE: length, CIE_id, version, augmentation4302 * FDE: length, CIE_pointer, initial_location, address_range4303 4304 If there is no augmentation, this value is a zero byte.4305 4306 *The augmentation string allows users to indicate that there is additional4307 vendor and target architecture specific information in the CIE or FDE which4308 is needed to virtually unwind a stack frame. For example, this might be4309 information about dynamically allocated data which needs to be freed on exit4310 from the routine.*4311 4312 *Because the* ``.debug_frame`` *section is useful independently of any*4313 ``.debug_info`` *section, the augmentation string always uses UTF-84314 encoding.*4315 4316 The recommended format for the augmentation string is:4317 4318 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ *4319 4320 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y4321 version number of the extensions used, and *options* is an optional string4322 providing additional information about the extensions. The version number4323 must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`].4324 The *options* string must not contain the "\ ``]``\ " character.4325 4326 For example:4327 4328 ::4329 4330 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3]4331 43325. ``address_size`` (ubyte)4333 4334 The size of a target address in this CIE and any FDEs that use it, in bytes.4335 If a compilation unit exists for this frame, its address size must match the4336 address size here.4337 43386. ``segment_selector_size`` (ubyte)4339 4340 The size of a segment selector in this CIE and any FDEs that use it, in4341 bytes.4342 43437. ``code_alignment_factor`` (unsigned LEB128)4344 4345 A constant that is factored out of all advance location instructions (see4346 :ref:`amdgpu-dwarf-row-creation-instructions`). The resulting value is4347 ``(operand * code_alignment_factor)``.4348 43498. ``data_alignment_factor`` (signed LEB128)4350 4351 A constant that is factored out of certain offset instructions (see4352 :ref:`amdgpu-dwarf-cfa-definition-instructions` and4353 :ref:`amdgpu-dwarf-register-rule-instructions`). The resulting value is4354 ``(operand * data_alignment_factor)``.4355 43569. ``return_address_register`` (unsigned LEB128)4357 4358 An unsigned LEB128 constant that indicates which column in the rule table4359 represents the return address of the subprogram. Note that this column might4360 not correspond to an actual machine register.4361 4362 The value of the return address register is used to determine the program4363 location of the caller frame. The program location of the top frame is the4364 target architecture program counter value of the current thread.4365 436610. ``initial_instructions`` (array of ubyte)4367 4368 A sequence of rules that are interpreted to create the initial setting of4369 each column in the table.4370 4371 The default rule for all columns before interpretation of the initial4372 instructions is the undefined rule. However, an ABI authoring body or a4373 compilation system authoring body may specify an alternate default value for4374 any or all columns.4375 437611. ``padding`` (array of ubyte)4377 4378 Enough ``DW_CFA_nop`` instructions to make the size of this entry match the4379 length value above.4380 4381An FDE contains the following fields, in order:4382 43831. ``length`` (initial length)4384 4385 A constant that gives the number of bytes of the header and instruction4386 stream for this subprogram, not including the length field itself (see4387 Section 7.2.2 Initial Length Values). The size of the length field plus the4388 value of length must be an integral multiple of the address size.4389 43902. ``CIE_pointer`` (4 or 8 bytes, see4391 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`)4392 4393 A constant offset into the ``.debug_frame`` section that denotes the CIE4394 that is associated with this FDE.4395 43963. ``initial_location`` (segment selector and target address)4397 4398 The address of the first location associated with this table entry. If the4399 segment_selector_size field of this FDE’s CIE is non-zero, the initial4400 location is preceded by a segment selector of the given length.4401 44024. ``address_range`` (target address)4403 4404 The number of bytes of program instructions described by this entry.4405 44065. ``instructions`` (array of ubyte)4407 4408 A sequence of table defining instructions that are described in4409 :ref:`amdgpu-dwarf-call-frame-instructions`.4410 44116. ``padding`` (array of ubyte)4412 4413 Enough ``DW_CFA_nop`` instructions to make the size of this entry match the4414 length value above.4415 4416.. _amdgpu-dwarf-call-frame-instructions:4417 4418A.6.4.2 Call Frame Instructions4419+++++++++++++++++++++++++++++++4420 4421Each call frame instruction is defined to take 0 or more operands. Some of the4422operands may be encoded as part of the opcode (see4423:ref:`amdgpu-dwarf-call-frame-information-encoding`). The instructions are4424defined in the following sections.4425 4426Some call frame instructions have operands that are encoded as DWARF operation4427expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF4428operations that can be used in E have the following restrictions:4429 4430* ``DW_OP_addrx``, ``DW_OP_call2``, ``DW_OP_call4``, ``DW_OP_call_ref``,4431 ``DW_OP_const_type``, ``DW_OP_constx``, ``DW_OP_convert``,4432 ``DW_OP_deref_type``, ``DW_OP_fbreg``, ``DW_OP_implicit_pointer``,4433 ``DW_OP_regval_type``, ``DW_OP_reinterpret``, and ``DW_OP_xderef_type``4434 operations are not allowed because the call frame information must not depend4435 on other debug sections.4436 4437* ``DW_OP_push_object_address`` is not allowed because there is no object4438 context to provide a value to push.4439 4440* ``DW_OP_LLVM_push_lane`` and ``DW_OP_LLVM_push_iteration`` are not allowed4441 because the call frame instructions describe the actions for the whole target4442 architecture thread, not the lanes or iterations independently.4443 4444* ``DW_OP_call_frame_cfa`` and ``DW_OP_entry_value`` are not allowed because4445 their use would be circular.4446 4447* ``DW_OP_LLVM_call_frame_entry_reg`` is not allowed if evaluating E causes a4448 circular dependency between ``DW_OP_LLVM_call_frame_entry_reg`` operations.4449 4450 *For example, if a register R1 has a* ``DW_CFA_def_cfa_expression``4451 *instruction that evaluates a* ``DW_OP_LLVM_call_frame_entry_reg`` *operation4452 that specifies register R2, and register R2 has a*4453 ``DW_CFA_def_cfa_expression`` *instruction that that evaluates a*4454 ``DW_OP_LLVM_call_frame_entry_reg`` *operation that specifies register R1.*4455 4456*Call frame instructions to which these restrictions apply include*4457``DW_CFA_def_cfa_expression``\ *,* ``DW_CFA_expression``\ *, and*4458``DW_CFA_val_expression``\ *.*4459 4460.. _amdgpu-dwarf-row-creation-instructions:4461 4462A.6.4.2.1 Row Creation Instructions4463###################################4464 4465.. note::4466 4467 These instructions are the same as in DWARF Version 5 section 6.4.2.1.4468 4469.. _amdgpu-dwarf-cfa-definition-instructions:4470 4471A.6.4.2.2 CFA Definition Instructions4472#####################################4473 44741. ``DW_CFA_def_cfa``4475 4476 The ``DW_CFA_def_cfa`` instruction takes two unsigned LEB128 operands4477 representing a register number R and a (non-factored) byte displacement B.4478 AS is set to the target architecture default address space identifier. The4479 required action is to define the current CFA rule to be equivalent to the4480 result of evaluating the DWARF operation expression ``DW_OP_constu AS;4481 DW_OP_LLVM_aspace_bregx R, B`` as a location description.4482 44832. ``DW_CFA_def_cfa_sf``4484 4485 The ``DW_CFA_def_cfa_sf`` instruction takes two operands: an unsigned LEB1284486 value representing a register number R and a signed LEB128 factored byte4487 displacement B. AS is set to the target architecture default address space4488 identifier. The required action is to define the current CFA rule to be4489 equivalent to the result of evaluating the DWARF operation expression4490 ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B * data_alignment_factor`` as4491 a location description.4492 4493 *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second4494 operand is signed and factored.*4495 44963. ``DW_CFA_LLVM_def_aspace_cfa`` *New*4497 4498 The ``DW_CFA_LLVM_def_aspace_cfa`` instruction takes three unsigned LEB1284499 operands representing a register number R, a (non-factored) byte4500 displacement B, and a target architecture specific address space identifier4501 AS. The required action is to define the current CFA rule to be equivalent4502 to the result of evaluating the DWARF operation expression ``DW_OP_constu4503 AS; DW_OP_LLVM_aspace_bregx R, B`` as a location description.4504 4505 If AS is not one of the values defined by the target architecture specific4506 ``DW_ASPACE_LLVM_*`` values then the DWARF expression is ill-formed.4507 45084. ``DW_CFA_LLVM_def_aspace_cfa_sf`` *New*4509 4510 The ``DW_CFA_LLVM_def_aspace_cfa_sf`` instruction takes three operands: an4511 unsigned LEB128 value representing a register number R, a signed LEB1284512 factored byte displacement B, and an unsigned LEB128 value representing a4513 target architecture specific address space identifier AS. The required4514 action is to define the current CFA rule to be equivalent to the result of4515 evaluating the DWARF operation expression ``DW_OP_constu AS;4516 DW_OP_LLVM_aspace_bregx R, B * data_alignment_factor`` as a location4517 description.4518 4519 If AS is not one of the values defined by the target architecture specific4520 ``DW_ASPACE_LLVM_*`` values, then the DWARF expression is ill-formed.4521 4522 *The action is the same as* ``DW_CFA_aspace_def_cfa``\ *, except that the4523 second operand is signed and factored.*4524 45255. ``DW_CFA_def_cfa_register``4526 4527 The ``DW_CFA_def_cfa_register`` instruction takes a single unsigned LEB1284528 operand representing a register number R. The required action is to define4529 the current CFA rule to be equivalent to the result of evaluating the DWARF4530 operation expression ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B`` as a4531 location description. B and AS are the old CFA byte displacement and address4532 space respectively.4533 4534 If the subprogram has no current CFA rule, or the rule was defined by a4535 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.4536 45376. ``DW_CFA_def_cfa_offset``4538 4539 The ``DW_CFA_def_cfa_offset`` instruction takes a single unsigned LEB1284540 operand representing a (non-factored) byte displacement B. The required4541 action is to define the current CFA rule to be equivalent to the result of4542 evaluating the DWARF operation expression ``DW_OP_constu AS;4543 DW_OP_LLVM_aspace_bregx R, B`` as a location description. R and AS are the4544 old CFA register number and address space respectively.4545 4546 If the subprogram has no current CFA rule, or the rule was defined by a4547 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.4548 45497. ``DW_CFA_def_cfa_offset_sf``4550 4551 The ``DW_CFA_def_cfa_offset_sf`` instruction takes a signed LEB128 operand4552 representing a factored byte displacement B. The required action is to4553 define the current CFA rule to be equivalent to the result of evaluating the4554 DWARF operation expression ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B *4555 data_alignment_factor`` as a location description. R and AS are the old CFA4556 register number and address space respectively.4557 4558 If the subprogram has no current CFA rule, or the rule was defined by a4559 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.4560 4561 *The action is the same as* ``DW_CFA_def_cfa_offset``\ *, except that the4562 operand is signed and factored.*4563 45648. ``DW_CFA_def_cfa_expression``4565 4566 The ``DW_CFA_def_cfa_expression`` instruction takes a single operand encoded4567 as a ``DW_FORM_exprloc`` value representing a DWARF operation expression E.4568 The required action is to define the current CFA rule to be equivalent to4569 the result of evaluating E with the current context, except the result kind4570 is a location description, the compilation unit is unspecified, the object4571 is unspecified, and an empty initial stack.4572 4573 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on4574 the DWARF expression operations that can be used in E.*4575 4576 The DWARF is ill-formed if the result of evaluating E is not a memory byte4577 address location description.4578 4579.. _amdgpu-dwarf-register-rule-instructions:4580 4581A.6.4.2.3 Register Rule Instructions4582####################################4583 45841. ``DW_CFA_undefined``4585 4586 The ``DW_CFA_undefined`` instruction takes a single unsigned LEB128 operand4587 that represents a register number R. The required action is to set the rule4588 for the register specified by R to ``undefined``.4589 45902. ``DW_CFA_same_value``4591 4592 The ``DW_CFA_same_value`` instruction takes a single unsigned LEB128 operand4593 that represents a register number R. The required action is to set the rule4594 for the register specified by R to ``same value``.4595 45963. ``DW_CFA_offset``4597 4598 The ``DW_CFA_offset`` instruction takes two operands: a register number R4599 (encoded with the opcode) and an unsigned LEB128 constant representing a4600 factored displacement B. The required action is to change the rule for the4601 register specified by R to be an *offset(B \* data_alignment_factor)* rule.4602 4603 .. note::4604 4605 Seems this should be named ``DW_CFA_offset_uf`` since the offset is4606 unsigned factored.4607 46084. ``DW_CFA_offset_extended``4609 4610 The ``DW_CFA_offset_extended`` instruction takes two unsigned LEB1284611 operands representing a register number R and a factored displacement B.4612 This instruction is identical to ``DW_CFA_offset``, except for the encoding4613 and size of the register operand.4614 4615 .. note::4616 4617 Seems this should be named ``DW_CFA_offset_extended_uf`` since the4618 displacement is unsigned factored.4619 46205. ``DW_CFA_offset_extended_sf``4621 4622 The ``DW_CFA_offset_extended_sf`` instruction takes two operands: an4623 unsigned LEB128 value representing a register number R and a signed LEB1284624 factored displacement B. This instruction is identical to4625 ``DW_CFA_offset_extended``, except that B is signed.4626 46276. ``DW_CFA_val_offset``4628 4629 The ``DW_CFA_val_offset`` instruction takes two unsigned LEB128 operands4630 representing a register number R and a factored displacement B. The required4631 action is to change the rule for the register indicated by R to be a4632 *val_offset(B \* data_alignment_factor)* rule.4633 4634 .. note::4635 4636 Seems this should be named ``DW_CFA_val_offset_uf`` since the displacement4637 is unsigned factored.4638 4639 .. note::4640 4641 An alternative is to define ``DW_CFA_val_offset`` to implicitly use the4642 target architecture default address space, and add another operation that4643 specifies the address space.4644 46457. ``DW_CFA_val_offset_sf``4646 4647 The ``DW_CFA_val_offset_sf`` instruction takes two operands: an unsigned4648 LEB128 value representing a register number R and a signed LEB128 factored4649 displacement B. This instruction is identical to ``DW_CFA_val_offset``,4650 except that B is signed.4651 46528. ``DW_CFA_register``4653 4654 The ``DW_CFA_register`` instruction takes two unsigned LEB128 operands4655 representing register numbers R1 and R2 respectively. The required action is4656 to set the rule for the register specified by R1 to be a *register(R2)* rule.4657 46589. ``DW_CFA_expression``4659 4660 The ``DW_CFA_expression`` instruction takes two operands: an unsigned LEB1284661 value representing a register number R, and a ``DW_FORM_block`` value4662 representing a DWARF operation expression E. The required action is to4663 change the rule for the register specified by R to be an *expression(E)*4664 rule.4665 4666 *That is, E computes the location description where the register value can4667 be retrieved.*4668 4669 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on4670 the DWARF expression operations that can be used in E.*4671 467210. ``DW_CFA_val_expression``4673 4674 The ``DW_CFA_val_expression`` instruction takes two operands: an unsigned4675 LEB128 value representing a register number R, and a ``DW_FORM_block`` value4676 representing a DWARF operation expression E. The required action is to4677 change the rule for the register specified by R to be a *val_expression(E)*4678 rule.4679 4680 *That is, E computes the value of register R.*4681 4682 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on4683 the DWARF expression operations that can be used in E.*4684 4685 If the result of evaluating E is not a value with a base type size that4686 matches the register size, then the DWARF is ill-formed.4687 468811. ``DW_CFA_restore``4689 4690 The ``DW_CFA_restore`` instruction takes a single operand (encoded with the4691 opcode) that represents a register number R. The required action is to4692 change the rule for the register specified by R to the rule assigned it by4693 the ``initial_instructions`` in the CIE.4694 469512. ``DW_CFA_restore_extended``4696 4697 The ``DW_CFA_restore_extended`` instruction takes a single unsigned LEB1284698 operand that represents a register number R. This instruction is identical4699 to ``DW_CFA_restore``, except for the encoding and size of the register4700 operand.4701 4702A.6.4.2.4 Row State Instructions4703################################4704 4705.. note::4706 4707 These instructions are the same as in DWARF Version 5 section 6.4.2.4.4708 4709A.6.4.2.5 Padding Instruction4710#############################4711 4712.. note::4713 4714 These instructions are the same as in DWARF Version 5 section 6.4.2.5.4715 4716A.6.4.3 Call Frame Instruction Usage4717++++++++++++++++++++++++++++++++++++4718 4719.. note::4720 4721 The same as in DWARF Version 5 section 6.4.3.4722 4723.. _amdgpu-dwarf-call-frame-calling-address:4724 4725A.6.4.4 Call Frame Calling Address4726++++++++++++++++++++++++++++++++++4727 4728.. note::4729 4730 The same as in DWARF Version 5 section 6.4.4.4731 4732A.7 Data Representation4733-----------------------4734 4735.. note::4736 4737 This section provides changes to existing debugger information entry4738 attributes. These would be incorporated into the corresponding DWARF Version 54739 chapter 7 sections.4740 4741.. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats:4742 4743A.7.4 32-Bit and 64-Bit DWARF Formats4744~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4745 4746.. note::4747 4748 This augments DWARF Version 5 section 7.4 list item 3's table.4749 4750.. table:: ``.debug_info`` section attribute form roles4751 :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table4752 4753 ================================== ===================================4754 Form Role4755 ================================== ===================================4756 DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info``4757 ================================== ===================================4758 4759A.7.5 Format of Debugging Information4760~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4761 4762A.7.5.4 Attribute Encodings4763+++++++++++++++++++++++++++4764 4765.. note::4766 4767 This augments DWARF Version 5 section 7.5.4 and Table 7.5.4768 4769The following table gives the encoding of the additional debugging information4770entry attributes.4771 4772.. table:: Attribute encodings4773 :name: amdgpu-dwarf-attribute-encodings-table4774 4775 ================================== ====== ===================================4776 Attribute Name Value Classes4777 ================================== ====== ===================================4778 ``DW_AT_LLVM_active_lane`` 0x3e08 exprloc, loclist4779 ``DW_AT_LLVM_augmentation`` 0x3e09 string4780 ``DW_AT_LLVM_lanes`` 0x3e0a constant4781 ``DW_AT_LLVM_lane_pc`` 0x3e0b exprloc, loclist4782 ``DW_AT_LLVM_vector_size`` 0x3e0c constant4783 ``DW_AT_LLVM_iterations`` 0x3e0a constant, exprloc, loclist4784 ``DW_AT_LLVM_address_space`` TBA constant4785 ``DW_AT_LLVM_memory_space`` TBA constant4786 ================================== ====== ===================================4787 4788.. _amdgpu-dwarf-classes-and-forms:4789 4790A.7.5.5 Classes and Forms4791+++++++++++++++++++++++++4792 4793.. note::4794 4795 The following modifies the matching text in DWARF Version 5 section 7.5.5.4796 4797* reference4798 There are four types of reference.4799 4800 - The first type of reference...4801 4802 - The second type of reference can identify any debugging information4803 entry within a .debug_info section; in particular, it may refer to an4804 entry in a different compilation unit from the unit containing the4805 reference, and may refer to an entry in a different shared object file.4806 This type of reference (DW_FORM_ref_addr) is an offset from the4807 beginning of the .debug_info section of the target executable or shared4808 object file, or, for references within a supplementary object file, an4809 offset from the beginning of the local .debug_info section; it is4810 relocatable in a relocatable object file and frequently relocated in an4811 executable or shared object file. In the 32-bit DWARF format, this4812 offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an4813 8-byte unsigned value (see4814 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`).4815 4816 *A debugging information entry that may be referenced by another4817 compilation unit using DW_FORM_ref_addr must have a global symbolic4818 name.*4819 4820 *For a reference from one executable or shared object file to another,4821 the reference is resolved by the debugger to identify the executable or4822 shared object file and the offset into that file's* ``.debug_info``4823 *section in the same fashion as the run time loader, either when the4824 debug information is first read, or when the reference is used.*4825 4826A.7.7 DWARF Expressions4827~~~~~~~~~~~~~~~~~~~~~~~4828 4829.. note::4830 4831 Rename DWARF Version 5 section 7.7 to reflect the unification of location4832 descriptions into DWARF expressions.4833 4834A.7.7.1 Operation Expressions4835+++++++++++++++++++++++++++++4836 4837.. note::4838 4839 Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect the4840 unification of location descriptions into DWARF expressions.4841 4842 This augments DWARF Version 5 section 7.7.1 and Table 7.9, and adds a new4843 table describing vendor extension operations for ``DW_OP_LLVM_user``.4844 4845A DWARF operation expression is stored in a block of contiguous bytes. The bytes4846form a sequence of operations. Each operation is a 1-byte code that identifies4847that operation, followed by zero or more bytes of additional data. The encoding4848for the operation ``DW_OP_LLVM_user`` is described in4849:ref:`amdgpu-dwarf-operation-encodings-table`, and the encoding of all4850``DW_OP_LLVM_user`` vendor extensions operations are described in4851:ref:`amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table`.4852 4853.. table:: DWARF Operation Encodings4854 :name: amdgpu-dwarf-operation-encodings-table4855 4856 ====================================== ===== ======== =========================================================================================4857 Operation Code Number Notes4858 of4859 Operands4860 ====================================== ===== ======== =========================================================================================4861 ``DW_OP_LLVM_user`` 0xe9 1+ ULEB128 vendor extension opcode, followed by vendor extension operands4862 defined in :ref:`amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table`4863 ====================================== ===== ======== =========================================================================================4864 4865.. table:: DWARF DW_OP_LLVM_user Vendor Extension Operation Encodings4866 :name: amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table4867 4868 ====================================== ========= ========== ===============================4869 Operation Vendor Number Notes4870 Extension of4871 Opcode Additional4872 Operands4873 ====================================== ========= ========== ===============================4874 ``DW_OP_LLVM_form_aspace_address`` 0x02 04875 ``DW_OP_LLVM_push_lane`` 0x03 04876 ``DW_OP_LLVM_offset`` 0x04 04877 ``DW_OP_LLVM_offset_uconst`` 0x05 1 ULEB128 byte displacement4878 ``DW_OP_LLVM_bit_offset`` 0x06 04879 ``DW_OP_LLVM_call_frame_entry_reg`` 0x07 1 ULEB128 register number4880 ``DW_OP_LLVM_undefined`` 0x08 04881 ``DW_OP_LLVM_aspace_bregx`` 0x09 2 ULEB128 register number,4882 SLEB128 byte displacement4883 ``DW_OP_LLVM_piece_end`` 0x0a 04884 ``DW_OP_LLVM_extend`` 0x0b 2 ULEB128 bit size,4885 ULEB128 count4886 ``DW_OP_LLVM_select_bit_piece`` 0x0c 2 ULEB128 bit size,4887 ULEB128 count4888 ``DW_OP_LLVM_aspace_implicit_pointer`` TBA 2 4-byte or 8-byte offset of DIE,4889 SLEB128 byte displacement4890 ``DW_OP_LLVM_push_iteration`` TBA 04891 ``DW_OP_LLVM_overlay`` TBA 04892 ``DW_OP_LLVM_bit_overlay`` TBA 04893 ====================================== ========= ========== ===============================4894 4895A.7.7.3 Location List Expressions4896+++++++++++++++++++++++++++++++++4897 4898.. note::4899 4900 Rename DWARF Version 5 section 7.7.3 to reflect that location lists are a kind4901 of DWARF expression.4902 4903A.7.12 Source Languages4904~~~~~~~~~~~~~~~~~~~~~~~4905 4906.. note::4907 4908 This augments DWARF Version 5 section 7.12 and Table 7.17.4909 4910The following table gives the encoding of the additional DWARF languages.4911 4912.. table:: Language encodings4913 :name: amdgpu-dwarf-language-encodings-table4914 4915 ==================== ====== ===================4916 Language Name Value Default Lower Bound4917 ==================== ====== ===================4918 ``DW_LANG_LLVM_HIP`` 0x8100 04919 ==================== ====== ===================4920 4921A.7.14 Address Space Encodings4922~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4923 4924.. note::4925 4926 This is a new section after DWARF Version 5 section 7.13 "Address Class and4927 Address Space Encodings".4928 4929The value of the common address space encoding ``DW_ASPACE_LLVM_none`` is 0.4930 4931A.7.15 Memory Space Encodings4932~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4933 4934.. note::4935 4936 This is a new section after DWARF Version 5 section 7.13 "Address Class and4937 Address Space Encodings".4938 4939The encodings of the constants used for the currently defined memory spaces4940are given in :ref:`amdgpu-dwarf-memory-space-encodings-table`.4941 4942.. table:: Memory space encodings4943 :name: amdgpu-dwarf-memory-space-encodings-table4944 4945 =========================== ======4946 Memory Space Name Value4947 =========================== ======4948 ``DW_MSPACE_LLVM_none`` 0x00004949 ``DW_MSPACE_LLVM_global`` 0x00014950 ``DW_MSPACE_LLVM_constant`` 0x00024951 ``DW_MSPACE_LLVM_group`` 0x00034952 ``DW_MSPACE_LLVM_private`` 0x00044953 ``DW_MSPACE_LLVM_lo_user`` 0x80004954 ``DW_MSPACE_LLVM_hi_user`` 0xffff4955 =========================== ======4956 4957A.7.22 Line Number Information4958~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4959 4960.. note::4961 4962 This augments DWARF Version 5 section 7.22 and Table 7.27.4963 4964The following table gives the encoding of the additional line number header4965entry formats.4966 4967.. table:: Line number header entry format encodings4968 :name: amdgpu-dwarf-line-number-header-entry-format-encodings-table4969 4970 ==================================== ====================4971 Line number header entry format name Value4972 ==================================== ====================4973 ``DW_LNCT_LLVM_source`` 0x20014974 ``DW_LNCT_LLVM_is_MD5`` 0x20024975 ==================================== ====================4976 4977.. _amdgpu-dwarf-call-frame-information-encoding:4978 4979A.7.24 Call Frame Information4980~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4981 4982.. note::4983 4984 This augments DWARF Version 5 section 7.24 and Table 7.29.4985 4986The following table gives the encoding of the additional call frame information4987instructions.4988 4989.. table:: Call frame instruction encodings4990 :name: amdgpu-dwarf-call-frame-instruction-encodings-table4991 4992 ================================= ====== ====== ================ ================ =====================4993 Instruction High 2 Low 6 Operand 1 Operand 2 Operand 34994 Bits Bits4995 ================================= ====== ====== ================ ================ =====================4996 ``DW_CFA_LLVM_def_aspace_cfa`` 0 0x30 ULEB128 register ULEB128 offset ULEB128 address space4997 ``DW_CFA_LLVM_def_aspace_cfa_sf`` 0 0x31 ULEB128 register SLEB128 offset ULEB128 address space4998 ================================= ====== ====== ================ ================ =====================4999 5000A.7.32 Type Signature Computation5001~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~5002 5003.. note::5004 5005 This augments (in alphabetical order) DWARF Version 5 section 7.32, Table5006 7.32.5007 5008.. table:: Attributes used in type signature computation5009 :name: amdgpu-dwarf-attributes-used-in-type-signature-computation-table5010 5011 ================================== =======5012 ``DW_AT_LLVM_address_space``5013 ``DW_AT_LLVM_memory_space``5014 ``DW_AT_LLVM_vector_size``5015 ================================== =======5016 5017A. Attributes by Tag Value (Informative)5018----------------------------------------5019 5020.. note::5021 5022 This augments DWARF Version 5 Appendix A and Table A.1.5023 5024The following table provides the additional attributes that are applicable to5025debugger information entries.5026 5027.. table:: Attributes by tag value5028 :name: amdgpu-dwarf-attributes-by-tag-value-table5029 5030 ================================== =============================5031 Tag Name Applicable Attributes5032 ================================== =============================5033 ``DW_TAG_base_type`` * ``DW_AT_LLVM_vector_size``5034 ``DW_TAG_pointer_type`` * ``DW_AT_LLVM_address_space``5035 * ``DW_AT_LLVM_memory_space``5036 ``DW_TAG_reference_type`` * ``DW_AT_LLVM_address_space``5037 * ``DW_AT_LLVM_memory_space``5038 ``DW_TAG_rvalue_reference_type`` * ``DW_AT_LLVM_address_space``5039 * ``DW_AT_LLVM_memory_space``5040 ``DW_TAG_variable`` * ``DW_AT_LLVM_memory_space``5041 ``DW_TAG_formal_parameter`` * ``DW_AT_LLVM_memory_space``5042 ``DW_TAG_constant`` * ``DW_AT_LLVM_memory_space``5043 ``DW_TAG_compile_unit`` * ``DW_AT_LLVM_augmentation``5044 ``DW_TAG_entry_point`` * ``DW_AT_LLVM_active_lane``5045 * ``DW_AT_LLVM_lane_pc``5046 * ``DW_AT_LLVM_lanes``5047 * ``DW_AT_LLVM_iterations``5048 ``DW_TAG_inlined_subroutine`` * ``DW_AT_LLVM_active_lane``5049 * ``DW_AT_LLVM_lane_pc``5050 * ``DW_AT_LLVM_lanes``5051 * ``DW_AT_LLVM_iterations``5052 ``DW_TAG_subprogram`` * ``DW_AT_LLVM_active_lane``5053 * ``DW_AT_LLVM_lane_pc``5054 * ``DW_AT_LLVM_lanes``5055 * ``DW_AT_LLVM_iterations``5056 ================================== =============================5057 5058D. Examples (Informative)5059-------------------------5060 5061.. note::5062 5063 This modifies the corresponding DWARF Version 5 Appendix D examples.5064 5065D.1 General Description Examples5066~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~5067 5068D.1.3 DWARF Location Description Examples5069+++++++++++++++++++++++++++++++++++++++++5070 5071``DW_OP_offset_uconst 4``5072 A structure member is four bytes from the start of the structure instance. The5073 location description of the base of the structure instance is assumed to be5074 already on the stack.5075 5076``DW_OP_entry_value 1 DW_OP_reg5 DW_OP_offset_uconst 16``5077 The address of the memory location is calculated by adding 16 to the value5078 contained in register 5 upon entering the current subprogram.5079 5080D.2 Aggregate Examples5081~~~~~~~~~~~~~~~~~~~~~~5082 5083D.2.1 Fortran Simple Array Example5084++++++++++++++++++++++++++++++++++5085 5086Figure D.4: Fortran array example: DWARF description5087 5088.. code::5089 :number-lines:5090 5091 -------------------------------------------------------------------------------5092 ! Description for type of 'ap'5093 !5094 1$: DW_TAG_array_type5095 ! No name, default (Fortran) ordering, default stride5096 DW_AT_type(reference to REAL)5097 DW_AT_associated(expression= ! Test 'ptr_assoc' flag5098 DW_OP_push_object_address5099 DW_OP_lit<n> ! where n == offset(ptr_assoc)5100 DW_OP_offset5101 DW_OP_deref5102 DW_OP_lit1 ! mask for 'ptr_assoc' flag5103 DW_OP_and)5104 DW_AT_data_location(expression= ! Get raw data address5105 DW_OP_push_object_address5106 DW_OP_lit<n> ! where n == offset(base)5107 DW_OP_offset5108 DW_OP_deref) ! Type of index of array 'ap'5109 2$: DW_TAG_subrange_type5110 ! No name, default stride5111 DW_AT_type(reference to INTEGER)5112 DW_AT_lower_bound(expression=5113 DW_OP_push_object_address5114 DW_OP_lit<n> ! where n ==5115 ! offset(desc, dims) +5116 ! offset(dims_str, lower_bound)5117 DW_OP_offset5118 DW_OP_deref)5119 DW_AT_upper_bound(expression=5120 DW_OP_push_object_address5121 DW_OP_lit<n> ! where n ==5122 ! offset(desc, dims) +5123 ! offset(dims_str, upper_bound)5124 DW_OP_offset5125 DW_OP_deref)5126 ! Note: for the m'th dimension, the second operator becomes5127 ! DW_OP_lit<n> where5128 ! n == offset(desc, dims) +5129 ! (m-1)*sizeof(dims_str) +5130 ! offset(dims_str, [lower|upper]_bound)5131 ! That is, the expression does not get longer for each successive5132 ! dimension (other than to express the larger offsets involved).5133 3$: DW_TAG_structure_type5134 DW_AT_name("array_ptr")5135 DW_AT_byte_size(constant sizeof(REAL) + sizeof(desc<1>))5136 4$: DW_TAG_member5137 DW_AT_name("myvar")5138 DW_AT_type(reference to REAL)5139 DW_AT_data_member_location(constant 0)5140 5$: DW_TAG_member5141 DW_AT_name("ap");5142 DW_AT_type(reference to 1$)5143 DW_AT_data_member_location(constant sizeof(REAL))5144 6$: DW_TAG_array_type5145 ! No name, default (Fortran) ordering, default stride5146 DW_AT_type(reference to 3$)5147 DW_AT_allocated(expression= ! Test 'ptr_alloc' flag5148 DW_OP_push_object_address5149 DW_OP_lit<n> ! where n == offset(ptr_alloc)5150 DW_OP_offset5151 DW_OP_deref5152 DW_OP_lit2 ! Mask for 'ptr_alloc' flag5153 DW_OP_and)5154 DW_AT_data_location(expression= ! Get raw data address5155 DW_OP_push_object_address5156 DW_OP_lit<n> ! where n == offset(base)5157 DW_OP_offset5158 DW_OP_deref)5159 7$: DW_TAG_subrange_type5160 ! No name, default stride5161 DW_AT_type(reference to INTEGER)5162 DW_AT_lower_bound(expression=5163 DW_OP_push_object_address5164 DW_OP_lit<n> ! where n == ...5165 DW_OP_offset5166 DW_OP_deref)5167 DW_AT_upper_bound(expression=5168 DW_OP_push_object_address5169 DW_OP_lit<n> ! where n == ...5170 DW_OP_offset5171 DW_OP_deref)5172 8$: DW_TAG_variable5173 DW_AT_name("arrayvar")5174 DW_AT_type(reference to 6$)5175 DW_AT_location(expression=5176 ...as appropriate...) ! Assume static allocation5177 -------------------------------------------------------------------------------5178 5179D.2.3 Fortran 2008 Assumed-rank Array Example5180+++++++++++++++++++++++++++++++++++++++++++++5181 5182Figure D.13: Sample DWARF for the array descriptor in Figure D.125183 5184.. code::5185 :number-lines:5186 5187 ----------------------------------------------------------------------------5188 10$: DW_TAG_array_type5189 DW_AT_type(reference to real)5190 DW_AT_rank(expression=5191 DW_OP_push_object_address5192 DW_OP_lit<n>5193 DW_OP_offset5194 DW_OP_deref)5195 DW_AT_data_location(expression=5196 DW_OP_push_object_address5197 DW_OP_lit<n>5198 DW_OP_offset5199 DW_OP_deref)5200 11$: DW_TAG_generic_subrange5201 DW_AT_type(reference to integer)5202 ! offset of rank in descriptor5203 ! offset of data in descriptor5204 DW_AT_lower_bound(expression=5205 ! Looks up the lower bound of dimension i.5206 ! Operation ! Stack effect5207 ! (implicit) ! i5208 DW_OP_lit<n> ! i sizeof(dim)5209 DW_OP_mul ! dim[i]5210 DW_OP_lit<n> ! dim[i] offsetof(dim)5211 DW_OP_plus ! dim[i]+offset5212 DW_OP_push_object_address ! dim[i]+offsetof(dim) objptr5213 DW_OP_swap ! objptr dim[i]+offsetof(dim)5214 DW_OP_offset ! objptr.dim[i]5215 DW_OP_lit<n> ! objptr.dim[i] offsetof(lb)5216 DW_OP_offset ! objptr.dim[i].lowerbound5217 DW_OP_deref) ! *objptr.dim[i].lowerbound5218 DW_AT_upper_bound(expression=5219 ! Looks up the upper bound of dimension i.5220 DW_OP_lit<n> ! sizeof(dim)5221 DW_OP_mul5222 DW_OP_lit<n> ! offsetof(dim)5223 DW_OP_plus5224 DW_OP_push_object_address5225 DW_OP_swap5226 DW_OP_offset5227 DW_OP_lit<n> ! offset of upperbound in dim5228 DW_OP_offset5229 DW_OP_deref)5230 DW_AT_byte_stride(expression=5231 ! Looks up the byte stride of dimension i.5232 ...5233 ! (analogous to DW_AT_upper_bound)5234 )5235 ----------------------------------------------------------------------------5236 5237.. note::5238 5239 This example suggests that ``DW_AT_lower_bound`` and ``DW_AT_upper_bound``5240 evaluate an exprloc with an initial stack containing the rank value. The5241 attribute definition should be updated to state this.5242 5243D.2.6 Ada Example5244+++++++++++++++++5245 5246Figure D.20: Ada example: DWARF description5247 5248.. code::5249 :number-lines:5250 5251 ----------------------------------------------------------------------------5252 11$: DW_TAG_variable5253 DW_AT_name("M")5254 DW_AT_type(reference to INTEGER)5255 12$: DW_TAG_array_type5256 ! No name, default (Ada) order, default stride5257 DW_AT_type(reference to INTEGER)5258 13$: DW_TAG_subrange_type5259 DW_AT_type(reference to INTEGER)5260 DW_AT_lower_bound(constant 1)5261 DW_AT_upper_bound(reference to variable M at 11$)5262 14$: DW_TAG_variable5263 DW_AT_name("VEC1")5264 DW_AT_type(reference to array type at 12$)5265 ...5266 21$: DW_TAG_subrange_type5267 DW_AT_name("TEENY")5268 DW_AT_type(reference to INTEGER)5269 DW_AT_lower_bound(constant 1)5270 DW_AT_upper_bound(constant 100)5271 ...5272 26$: DW_TAG_structure_type5273 DW_AT_name("REC2")5274 27$: DW_TAG_member5275 DW_AT_name("N")5276 DW_AT_type(reference to subtype TEENY at 21$)5277 DW_AT_data_member_location(constant 0)5278 28$: DW_TAG_array_type5279 ! No name, default (Ada) order, default stride5280 ! Default data location5281 DW_AT_type(reference to INTEGER)5282 29$: DW_TAG_subrange_type5283 DW_AT_type(reference to subrange TEENY at 21$)5284 DW_AT_lower_bound(constant 1)5285 DW_AT_upper_bound(reference to member N at 27$)5286 30$: DW_TAG_member5287 DW_AT_name("VEC2")5288 DW_AT_type(reference to array "subtype" at 28$)5289 DW_AT_data_member_location(machine=5290 DW_OP_lit<n> ! where n == offset(REC2, VEC2)5291 DW_OP_offset)5292 ...5293 41$: DW_TAG_variable5294 DW_AT_name("OBJ2B")5295 DW_AT_type(reference to REC2 at 26$)5296 DW_AT_location(...as appropriate...)5297 ----------------------------------------------------------------------------5298 5299.. _amdgpu-dwarf-further-examples:5300 5301C. Further Examples5302===================5303 5304The AMD GPU specific usage of the features in these extensions, including5305examples, is available at *User Guide for AMDGPU Backend* section5306:ref:`amdgpu-dwarf-debug-information`.5307 5308.. note::5309 5310 Change examples to use ``DW_OP_LLVM_offset`` instead of ``DW_OP_add`` when5311 acting on a location description.5312 5313 Need to provide examples of new features.5314 5315.. _amdgpu-dwarf-references:5316 5317D. References5318=============5319 5320 .. _amdgpu-dwarf-AMD:5321 53221. [AMD] `Advanced Micro Devices <https://www.amd.com/>`__5323 5324 .. _amdgpu-dwarf-AMD-ROCgdb:5325 53262. [AMD-ROCgdb] `AMD ROCm Debugger (ROCgdb) <https://github.com/ROCm/ROCgdb>`__5327 5328 .. _amdgpu-dwarf-AMD-ROCm:5329 53303. [AMD-ROCm] `AMD ROCm Platform <https://rocm-documentation.readthedocs.io>`__5331 5332 .. _amdgpu-dwarf-AMDGPU-DWARF-LOC:5333 53344. [AMDGPU-DWARF-LOC] `Allow Location Descriptions on the DWARF Expression Stack <https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html>`__5335 5336 .. _amdgpu-dwarf-AMDGPU-LLVM:5337 53385. [AMDGPU-LLVM] `User Guide for AMDGPU LLVM Backend <https://llvm.org/docs/AMDGPUUsage.html>`__5339 5340 .. _amdgpu-dwarf-CUDA:5341 53426. [CUDA] `Nvidia CUDA Language <https://docs.nvidia.com/cuda/cuda-c-programming-guide/>`__5343 5344 .. _amdgpu-dwarf-DWARF:5345 53467. [DWARF] `DWARF Debugging Information Format <http://dwarfstd.org/>`__5347 5348 .. _amdgpu-dwarf-ELF:5349 53508. [ELF] `Executable and Linkable Format (ELF) <http://www.sco.com/developers/gabi/>`__5351 5352 .. _amdgpu-dwarf-GCC:5353 53549. [GCC] `GCC: The GNU Compiler Collection <https://www.gnu.org/software/gcc/>`__5355 5356 .. _amdgpu-dwarf-GDB:5357 535810. [GDB] `GDB: The GNU Project Debugger <https://www.gnu.org/software/gdb/>`__5359 5360 .. _amdgpu-dwarf-HIP:5361 536211. [HIP] `HIP Programming Guide <https://rocm-documentation.readthedocs.io/en/latest/Programming_Guides/Programming-Guides.html#hip-programing-guide>`__5363 5364 .. _amdgpu-dwarf-HSA:5365 536612. [HSA] `Heterogeneous System Architecture (HSA) Foundation <http://www.hsafoundation.com/>`__5367 5368 .. _amdgpu-dwarf-LLVM:5369 537013. [LLVM] `The LLVM Compiler Infrastructure <https://llvm.org/>`__5371 5372 .. _amdgpu-dwarf-OpenCL:5373 537414. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__5375 5376 .. _amdgpu-dwarf-Perforce-TotalView:5377 537815. [Perforce-TotalView] `Perforce TotalView HPC Debugging Software <https://totalview.io/products/totalview>`__5379 5380 .. _amdgpu-dwarf-SEMVER:5381 538216. [SEMVER] `Semantic Versioning <https://semver.org/>`__5383