1.. _amdgpu-dwarf-extensions-for-heterogeneous-debugging: 2 3******************************************** 4DWARF Extensions For Heterogeneous Debugging 5******************************************** 6 7.. contents:: 8 :local: 9 10.. warning:: 11 12 This document describes **provisional extensions** to DWARF Version 5 13 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] to support heterogeneous debugging. It is 14 not currently fully implemented and is subject to change. 15 16.. _amdgpu-dwarf-introduction: 17 181. Introduction 19=============== 20 21AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] has been working on supporting heterogeneous 22computing. A heterogeneous computing program can be written in a high level 23language such as C++ or Fortran with OpenMP pragmas, OpenCL, or HIP (a portable 24C++ programming environment for heterogeneous computing [:ref:`HIP 25<amdgpu-dwarf-HIP>`]). A heterogeneous compiler and runtime allows a program to 26execute on multiple devices within the same native process. Devices could 27include 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-ROCm 31<amdgpu-dwarf-AMD-ROCm>`] is an implementation of the industry standard for 32heterogeneous computing devices defined by the Heterogeneous System Architecture 33(HSA) Foundation [:ref:`HSA <amdgpu-dwarf-HSA>`]. It is open sourced and 34includes contributions to open source projects such as LLVM [:ref:`LLVM 35<amdgpu-dwarf-LLVM>`] for compilation and GDB for debugging [:ref:`GDB 36<amdgpu-dwarf-GDB>`]. 37 38The LLVM compiler has upstream support for commercially available AMD GPU 39hardware (AMDGPU) [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The open 40source ROCgdb [:ref:`AMD-ROCgdb <amdgpu-dwarf-AMD-ROCgdb>`] GDB based debugger 41also has support for AMDGPU which is being upstreamed. Support for AMDGPU is 42also being added by third parties to the GCC [:ref:`GCC <amdgpu-dwarf-GCC>`] 43compiler and the Perforce TotalView HPC Debugger [:ref:`Perforce-TotalView 44<amdgpu-dwarf-Perforce-TotalView>`]. 45 46To support debugging heterogeneous programs several features that are not 47provided by current DWARF Version 5 [:ref:`DWARF <amdgpu-dwarf-DWARF>`] have 48been identified. The :ref:`amdgpu-dwarf-extensions` section gives an overview of 49the extensions devised to address the missing features. The extensions seek to 50be general in nature and backwards compatible with DWARF Version 5. Their goal 51is to be applicable to meeting the needs of any heterogeneous system and not be 52vendor or architecture specific. That is followed by appendix 53:ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` which contains the 54textual changes for the extensions relative to the DWARF Version 5 standard. 55There are a number of notes included that raise open questions, or provide 56alternative approaches that may be worth considering. Then appendix 57:ref:`amdgpu-dwarf-further-examples` links to the AMD GPU specific usage of the 58extensions that includes an example. Finally, appendix 59:ref:`amdgpu-dwarf-references` provides references to further information. 60 61.. _amdgpu-dwarf-extensions: 62 632. Extensions 64============= 65 66The extensions continue to evolve through collaboration with many individuals and 67active prototyping within the GDB debugger and LLVM compiler. Input has also 68been very much appreciated from the developers working on the Perforce TotalView 69HPC Debugger and GCC compiler. 70 71The inputs provided and insights gained so far have been incorporated into this 72current version. The plan is to participate in upstreaming the work and 73addressing any feedback. If there is general interest then some or all of these 74extensions 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:`DWARF 79 <amdgpu-dwarf-DWARF>`] standard. 80 812. Be vendor and architecture neutral. They are intended to apply to other 82 heterogeneous hardware devices including GPUs, DSPs, FPGAs, and other 83 specialized hardware. These collectively include similar characteristics and 84 requirements as AMDGPU devices. 85 863. Provide improved optimization support for non-GPU code. For example, some 87 extensions apply to traditional CPU hardware that supports large vector 88 registers. Compilers can map source languages, and source language 89 extensions, that describe large scale parallel execution, onto the lanes of 90 the vector registers. This is common in programming languages used in ML and 91 HPC. 92 934. Fully define well-formed DWARF in a consistent style based on the DWARF 94 Version 5 specification. 95 96It is possible that some of the generalizations may also benefit other DWARF 97issues that have been raised. 98 99The remainder of this section enumerates the extensions and provides motivation 100for 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 Stack 105------------------------------------------------------------ 106 107DWARF Version 5 does not allow location descriptions to be entries on the DWARF 108expression stack. They can only be the final result of the evaluation of a DWARF 109expression. However, by allowing a location description to be a first-class 110entry on the DWARF expression stack it becomes possible to compose expressions 111containing both values and location descriptions naturally. It allows objects to 112be located in any kind of memory address space, in registers, be implicit 113values, be undefined, or a composite of any of these. 114 115By extending DWARF carefully, all existing DWARF expressions can retain their 116current semantic meaning. DWARF has implicit conversions that convert from a 117value that represents an address in the default address space to a memory 118location description. This can be extended to allow a default address space 119memory location description to be implicitly converted back to its address 120value. This allows all DWARF Version 5 expressions to retain their same meaning, 121while enabling the ability to explicitly create memory location descriptions in 122non-default address spaces and generalizing the power of composite location 123descriptions to any kind of location description. 124 125For those familiar with the definition of location descriptions in DWARF Version 1265, the definitions in these extensions are presented differently, but does in 127fact define the same concept with the same fundamental semantics. However, it 128does so in a way that allows the concept to extend to support address spaces, 129bit addressing, the ability for composite location descriptions to be composed 130of any kind of location description, and the ability to support objects located 131at multiple places. Collectively these changes expand the set of architectures 132that can be supported and improves support for optimized code. 133 134Several approaches were considered, and the one presented, together with the 135extensions it enables, appears to be the simplest and cleanest one that offers 136the greatest improvement of DWARF's ability to support debugging optimized GPU 137and non-GPU code. Examining the GDB debugger and LLVM compiler, it appears only 138to require modest changes as they both already have to support general use of 139location descriptions. It is anticipated that will also be the case for other 140debuggers and compilers. 141 142GDB has been modified to evaluate DWARF Version 5 expressions with location 143descriptions as stack entries and with implicit conversions. All GDB tests have 144passed, except one that turned out to be an invalid test case by DWARF Version 5 145rules. The code in GDB actually became simpler as all evaluation is done on a 146single stack and there was no longer a need to maintain a separate structure for 147the location description results. This gives confidence in backwards 148compatibility. 149 150See :ref:`amdgpu-dwarf-expressions` and nested sections. 151 152This extension is separately described at *Allow Location Descriptions on the 153DWARF Expression Stack* [:ref:`AMDGPU-DWARF-LOC 154<amdgpu-dwarf-AMDGPU-DWARF-LOC>`]. 155 1562.2 Generalize CFI to Allow Any Location Description Kind 157--------------------------------------------------------- 158 159CFI describes restoring callee saved registers that are spilled. Currently CFI 160only allows a location description that is a register, memory address, or 161implicit location description. AMDGPU optimized code may spill scalar registers 162into portions of vector registers. This requires extending CFI to allow any 163location description kind to be supported. 164 165See :ref:`amdgpu-dwarf-call-frame-information`. 166 1672.3 Generalize DWARF Operation Expressions to Support Multiple Places 168--------------------------------------------------------------------- 169 170In DWARF Version 5 a location description is defined as a single location 171description or a location list. A location list is defined as either 172effectively an undefined location description or as one or more single 173location descriptions to describe an object with multiple places. 174 175With 176:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`, 177the ``DW_OP_push_object_address`` and ``DW_OP_call*`` operations can put a 178location description on the stack. Furthermore, debugger information entry 179attributes such as ``DW_AT_data_member_location``, ``DW_AT_use_location``, and 180``DW_AT_vtable_elem_location`` are defined as pushing a location description on 181the expression stack before evaluating the expression. 182 183DWARF Version 5 only allows the stack to contain values and so only a single 184memory address can be on the stack. This makes these operations and attributes 185incapable of handling location descriptions with multiple places, or places 186other than memory. 187 188Since 189:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` 190allows the stack to contain location descriptions, the operations are 191generalized to support location descriptions that can have multiple places. This 192is backwards compatible with DWARF Version 5 and allows objects with multiple 193places to be supported. For example, the expression that describes how to access 194the field of an object can be evaluated with a location description that has 195multiple places and will result in a location description with multiple places. 196 197With this change, the separate DWARF Version 5 sections that described DWARF 198expressions and location lists are unified into a single section that describes 199DWARF expressions in general. This unification is a natural consequence of, and 200a necessity of, allowing location descriptions to be part of the evaluation 201stack. 202 203See :ref:`amdgpu-dwarf-location-description`. 204 2052.4 Generalize Offsetting of Location Descriptions 206-------------------------------------------------- 207 208The ``DW_OP_plus`` and ``DW_OP_minus`` operations can be defined to operate on a 209memory location description in the default target architecture specific address 210space and a generic type value to produce an updated memory location 211description. This allows them to continue to be used to offset an address. 212 213To generalize offsetting to any location description, including location 214descriptions that describe when bytes are in registers, are implicit, or a 215composite of these, the ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and 216``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 to 220define offsets that exceed the size of the location storage as being an 221evaluation error, than having to force an implementation to support potentially 222infinite precision offsets to allow it to correctly track a series of positive 223and negative offsets that may transiently overflow or underflow, but end up in 224range. This is simple for the arithmetic operations as they are defined in terms 225of two's complement arithmetic on a base type of a fixed size. Therefore, the 226offset operation define that integer overflow is ill-formed. This is in contrast 227to the ``DW_OP_plus``, ``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic 228operations which define that it causes wrap-around. 229 230Having the offset operations allows ``DW_OP_push_object_address`` to push a 231location description that may be in a register, or be an implicit value. The 232DWARF expression of ``DW_TAG_ptr_to_member_type`` can use the offset operations 233without regard to what kind of location description was pushed. 234 235Since 236:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` has 237generalized location storage to be bit indexable, ``DW_OP_LLVM_bit_offset`` 238generalizes DWARF to work with bit fields. This is generally not possible in 239DWARF Version 5. 240 241The ``DW_OP_*piece`` operations only allow literal indices. A way to use a 242computed offset of an arbitrary location description (such as a vector register) 243is required. The offset operations provide this ability since they can be used 244to compute a location description on the stack. 245 246It could be possible to define ``DW_OP_plus``, ``DW_OP_plus_uconst``, and 247``DW_OP_minus`` to operate on location descriptions to avoid needing 248``DW_OP_LLVM_offset`` and ``DW_OP_LLVM_offset_uconst``. However, this is not 249proposed since currently the arithmetic operations are defined to require values 250of the same base type and produces a result with the same base type. Allowing 251these operations to act on location descriptions would permit the first operand 252to be a location description and the second operand to be an integral value 253type, or vice versa, and return a location description. This complicates the 254rules for implicit conversions between default address space memory location 255descriptions and generic base type values. Currently the rules would convert 256such a location description to the memory address value and then perform two's 257compliment wrap around arithmetic. If the result was used as a location 258description, it would be implicitly converted back to a default address space 259memory location description. This is different to the overflow rules on location 260descriptions. To allow control, an operation that converts a memory location 261description to an address integral type value would be required. Keeping a 262separation of location description operations and arithmetic operations avoids 263this semantic complexity. 264 265See ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and 266``DW_OP_LLVM_bit_offset`` in 267:ref:`amdgpu-dwarf-general-location-description-operations`. 268 2692.5 Generalize Creation of Undefined Location Descriptions 270---------------------------------------------------------- 271 272Current DWARF uses an empty expression to indicate an undefined location 273description. Since 274:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` 275allows location descriptions to be created on the stack, it is necessary to have 276an explicit way to specify an undefined location description. 277 278For example, the ``DW_OP_LLVM_select_bit_piece`` (see 279:ref:`amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware`) 280operation takes more than one location description on the stack. Without this 281ability, it is not possible to specify that a particular one of the input 282location descriptions is undefined. 283 284See the ``DW_OP_LLVM_undefined`` operation in 285:ref:`amdgpu-dwarf-undefined-location-description-operations`. 286 2872.6 Generalize Creation of Composite Location Descriptions 288---------------------------------------------------------- 289 290To allow composition of composite location descriptions, an explicit operation 291that indicates the end of the definition of a composite location description is 292required. 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`` in 296:ref:`amdgpu-dwarf-composite-location-description-operations`. 297 2982.7 Generalize DWARF Base Objects to Allow Any Location Description Kind 299------------------------------------------------------------------------ 300 301The number of registers and the cost of memory operations is much higher for 302AMDGPU than a typical CPU. The compiler attempts to optimize whole variables and 303arrays into registers. 304 305Currently DWARF only allows ``DW_OP_push_object_address`` and related operations 306to work with a global memory location. To support AMDGPU optimized code it is 307required to generalize DWARF to allow any location description to be used. This 308allows registers, or composite location descriptions that may be a mixture of 309memory, registers, or even implicit values. 310 311See ``DW_OP_push_object_address`` in 312:ref:`amdgpu-dwarf-general-location-description-operations`. 313 3142.8 General Support for Address Spaces 315-------------------------------------- 316 317AMDGPU needs to be able to describe addresses that are in different kinds of 318memory. Optimized code may need to describe a variable that resides in pieces 319that 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 be 323specified within a DWARF expression, which is only able to specify the offset 324portion of a segment address. The segment index is only provided by the entity 325that specifies the DWARF expression. Therefore, the segment index is a property 326that can only be put on complete objects, such as a variable. That makes it only 327suitable for describing an entity (such as variable or subprogram code) that is 328in a single kind of memory. 329 330AMDGPU uses multiple address spaces. For example, a variable may be allocated in 331a register that is partially spilled to the call stack which is in the private 332address space, and partially spilled to the local address space. DWARF mentions 333address spaces, for example as an argument to the ``DW_OP_xderef*`` operations. 334A new section that defines address spaces is added (see 335:ref:`amdgpu-dwarf-address-spaces`). 336 337A new attribute ``DW_AT_LLVM_address_space`` is added to pointer and reference 338types (see :ref:`amdgpu-dwarf-type-modifier-entries`). This allows the compiler 339to specify which address space is being used to represent the pointer or 340reference type. 341 342DWARF uses the concept of an address in many expression operations but does not 343define how it relates to address spaces. For example, 344``DW_OP_push_object_address`` pushes the address of an object. Other contexts 345implicitly push an address on the stack before evaluating an expression. For 346example, the ``DW_AT_use_location`` attribute of the 347``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type 348which may apply to objects allocated in different kinds of storage. Therefore, 349it is desirable that the expression that uses the address can do so without 350regard to what kind of storage it specifies, including the address space of a 351memory location description. For example, a pointer to member value may want to 352be 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 an 355address of a specified address space which is then read. But it provides no 356way to create a memory location description for an address in the non-default 357address space. For example, AMDGPU variables can be allocated in the local 358address space at a fixed address. 359 360The ``DW_OP_LLVM_form_aspace_address`` (see 361:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is defined 362to create a memory location description from an address and address space. If 363can be used to specify the location of a variable that is allocated in a 364specific address space. This allows the size of addresses in an address space to 365be larger than the generic type. It also allows a consumer great implementation 366freedom. It allows the implicit conversion back to a value to be limited only to 367the default address space to maintain compatibility with DWARF Version 5. For 368other address spaces the producer can use the new operations that explicitly 369specify the address space. 370 371In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been 372defined to produce a value, and an implicit conversion to a memory location 373description was defined, then it would be limited to the size of the generic 374type (which matches the size of the default address space). An implementation 375would likely have to use *reserved ranges* of value to represent different 376address spaces. Such a value would likely not match any address value in the 377actual hardware. That would require the consumer to have special treatment for 378such values. 379 380``DW_OP_breg*`` treats the register as containing an address in the default 381address space. A ``DW_OP_LLVM_aspace_bregx`` (see 382:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is added 383to 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 being 386in the default address space. A ``DW_OP_LLVM_aspace_implicit_pointer`` 387(:ref:`amdgpu-dwarf-implicit-location-description-operations`) operation is 388added to allow the address space to be specified. 389 390Almost all uses of addresses in DWARF are limited to defining location 391descriptions, or to be dereferenced to read memory. The exception is 392``DW_CFA_val_offset`` which uses the address to set the value of a register. In 393order to support address spaces, the CFA DWARF expression is defined to be a 394memory location description. This allows it to specify an address space which is 395used to convert the offset address back to an address in that address space. See 396:ref:`amdgpu-dwarf-call-frame-information`. 397 398This approach of extending memory location descriptions to support address 399spaces, allows all existing DWARF Version 5 expressions to have the identical 400semantics. It allows the compiler to explicitly specify the address space it is 401using. For example, a compiler could choose to access private memory in a 402swizzled manner when mapping a source language thread to the lane of a wavefront 403in a SIMT manner. Or a compiler could choose to access it in an unswizzled 404manner 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 private 407memory. For example, for SIMT it can still spill entire vector registers in an 408unswizzled manner, while using a swizzled private memory for SIMT variable 409access. 410 411This approach also allows memory location descriptions for different address 412spaces to be combined using the regular ``DW_OP_*piece`` operations. 413 414Location descriptions are an abstraction of storage. They give freedom to the 415consumer on how to implement them. They allow the address space to encode lane 416information so they can be used to read memory with only the memory location 417description and no extra information. The same set of operations can operate on 418locations independent of their kind of storage. The ``DW_OP_deref*`` therefore 419can be used on any storage kind, including memory location descriptions of 420different address spaces. Therefore, the ``DW_OP_xderef*`` operations are 421unnecessary, except to become a more compact way to encode a non-default address 422space address followed by dereferencing it. See 423:ref:`amdgpu-dwarf-general-operations`. 424 4252.9 Support for Vector Base Types 426--------------------------------- 427 428The vector registers of the AMDGPU are represented as their full wavefront 429size, meaning the wavefront size times the dword size. This reflects the 430actual hardware and allows the compiler to generate DWARF for languages that 431map a thread to the complete wavefront. It also allows more efficient DWARF to 432be generated to describe the CFI as only a single expression is required for 433the whole vector register, rather than a separate expression for each lane's 434dword of the vector register. It also allows the compiler to produce DWARF 435that indexes the vector register if it spills scalar registers into portions 436of a vector register. 437 438Since DWARF stack value entries have a base type and AMDGPU registers are a 439vector of dwords, the ability to specify that a base type is a vector is 440required. 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 Descriptions 447---------------------------------------------------------------------- 448 449AMDGPU optimized code may spill vector registers to non-global address space 450memory, and this spilling may be done only for SIMT lanes that are active on 451entry to the subprogram. To support this the CFI rule for the partially spilled 452register needs to use an expression that uses the EXEC register as a bit mask to 453select between the register (for inactive lanes) and the stack spill location 454(for active lanes that are spilled). This needs to evaluate to a location 455description, and not a value, as a debugger needs to change the value if the 456user assigns to the variable. 457 458Another usage is to create an expression that evaluates to provide a vector of 459logical PCs for active and inactive lanes in a SIMT execution model. Again the 460EXEC register is used to select between active and inactive PC values. In order 461to represent a vector of PC values, a way to create a composite location 462description that is a vector of a single location is used. 463 464It may be possible to use existing DWARF to incrementally build the composite 465location description, possibly using the DWARF operations for control flow to 466create 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 be 468reasonably common as it is needed for every vector register that is spilled in a 469function. AMDGPU can have up to 512 vector registers. Another concern is the 470time taken to evaluate such non-trivial expressions repeatedly. 471 472To avoid these issues, a composite location description that can be created as a 473masked select is proposed. In addition, an operation that creates a composite 474location description that is a vector on another location description is needed. 475These operations generate the composite location description using a single 476DWARF operation that combines all lanes of the vector in one step. The DWARF 477expression is more compact, and can be evaluated by a consumer far more 478efficiently. 479 480An example that uses these operations is referenced in the 481:ref:`amdgpu-dwarf-further-examples` appendix. 482 483See ``DW_OP_LLVM_select_bit_piece`` and ``DW_OP_LLVM_extend`` in 484:ref:`amdgpu-dwarf-composite-location-description-operations`. 485 4862.11 DWARF Operation to Access Call Frame Entry Registers 487--------------------------------------------------------- 488 489As described in 490:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`, 491a DWARF expression involving the set of SIMT lanes active on entry to a 492subprogram is required. The SIMT active lane mask may be held in a register that 493is modified as the subprogram executes. However, its value may be saved on entry 494to the subprogram. 495 496The Call Frame Information (CFI) already encodes such register saving, so it is 497more efficient to provide an operation to return the location of a saved 498register than have to generate a loclist to describe the same information. This 499is now possible since 500: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`` in 504:ref:`amdgpu-dwarf-general-location-description-operations` and 505:ref:`amdgpu-dwarf-call-frame-information`. 506 5072.12 Support for Source Languages Mapped to SIMT Hardware 508--------------------------------------------------------- 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 a 512single lane of the wavefront. Therefore, a DWARF operation is required to denote 513the current lane, much like ``DW_OP_push_object_address`` denotes the current 514object. 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 source 517language threads of execution are mapped to a target architecture thread's SIMT 518lanes. 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 Hardware 523-------------------------------------------------------- 524 525If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner the 526compiler can use the AMDGPU execution mask register to control which lanes are 527active. To describe the conceptual location of non-active lanes requires an 528attribute that has an expression that computes the source location PC for each 529lane. 530 531For efficiency, the expression calculates the source location the wavefront as a 532whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see 533: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 active 538lane mask. This can have an expression that may evaluate to the SIMT active lane 539mask register or to a saved mask when in whole wavefront execution mode. 540 541An example that uses these attributes is referenced in the 542:ref:`amdgpu-dwarf-further-examples` appendix. 543 544See ``DW_AT_LLVM_lane_pc`` and ``DW_AT_LLVM_active_lane`` in 545:ref:`amdgpu-dwarf-composite-location-description-operations`. 546 5472.14 Define Source Language Memory Classes 548------------------------------------------- 549 550AMDGPU supports languages, such as OpenCL [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`], 551that define source language memory classes. Support is added to define language 552specific 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 data 555object allocation is also added. 556 557See :ref:`amdgpu-dwarf-memory-spaces`. 558 5592.15 Define Augmentation Strings to Support Multiple Extensions 560--------------------------------------------------------------- 561 562A ``DW_AT_LLVM_augmentation`` attribute is added to a compilation unit debugger 563information entry to indicate that there is additional target architecture 564specific information in the debugging information entries of that compilation 565unit. This allows a consumer to know what extensions are present in the debugger 566information entries as is possible with the augmentation string of other 567sections. See . 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 from 571multiple vendors. Augmentation strings occur in the ``DW_AT_LLVM_augmentation`` 572attribute, in the lookup by name table, and in the CFI Common Information Entry 573(CIE). 574 575See :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`, 576:ref:`amdgpu-dwarf-name-index-section-header`, and 577:ref:`amdgpu-dwarf-structure_of-call-frame-information`. 578 5792.16 Support Embedding Source Text for Online Compilation 580--------------------------------------------------------- 581 582AMDGPU supports programming languages that include online compilation where the 583source text may be created at runtime. For example, the OpenCL and HIP language 584runtimes support online compilation. To support is, a way to embed the source 585text in the debug information is provided. 586 587See :ref:`amdgpu-dwarf-line-number-information`. 588 5892.17 Allow MD5 Checksums to be Optionally Present 590------------------------------------------------- 591 592In DWARF Version 5 the file timestamp and file size can be optional, but if the 593MD5 checksum is present it must be valid for all files. This is a problem if 594using link time optimization to combine compilation units where some have MD5 595checksums and some do not. Therefore, sSupport to allow MD5 checksums to be 596optionally present in the line table is added. 597 598See :ref:`amdgpu-dwarf-line-number-information`. 599 6002.18 Add the HIP Programing Language 601------------------------------------ 602 603The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported 604by 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 Execution 609-------------------------------------------------------------------------------------------- 610 611A compiler can perform loop optimizations that result in the generated code 612executing multiple iterations concurrently. For example, software pipelining 613schedules multiple iterations in an interleaved fashion to allow the 614instructions of one iteration to hide the latencies of the instructions of 615another iteration. Another example is vectorization that can exploit SIMD 616hardware to allow a single instruction to execute multiple iterations using 617vector registers. 618 619Note that although this is similar to SIMT execution, the way a client debugger 620uses the information is fundamentally different. In SIMT execution the debugger 621needs to present the concurrent execution as distinct source language threads 622that the user can list and switch focus between. With iteration concurrency 623optimizations, such as software pipelining and vectorized SIMD, the debugger 624must not present the concurrency as distinct source language threads. Instead, 625it must inform the user that multiple loop iterations are executing in parallel 626and allow the user to select between them. 627 628In general, SIMT execution fixes the number of concurrent executions per target 629architecture thread. However, both software pipelining and SIMD vectorization 630may vary the number of concurrent iterations for different loops executed by a 631single source language thread. 632 633It is possible for the compiler to use both SIMT concurrency and iteration 634concurrency techniques in the code of a single source language thread. 635 636Therefore, a DWARF operation is required to denote the current concurrent 637iteration instance, much like ``DW_OP_push_object_address`` denotes the current 638object. See ``DW_OP_LLVM_push_iteration`` in 639:ref:`amdgpu-dwarf-literal-operations`. 640 641In addition, a way is needed for the compiler to communicate how many source 642language loop iterations are executing concurrently. See 643``DW_AT_LLVM_iterations`` in :ref:`amdgpu-dwarf-low-level-information`. 644 6452.20 DWARF Operation to Create Runtime Overlay Composite Location Description 646----------------------------------------------------------------------------- 647 648It is common in SIMD vectorization for the compiler to generate code that 649promotes portions of an array into vector registers. For example, if the 650hardware has vector registers with 8 elements, and 8 wide SIMD instructions, the 651compiler may vectorize a loop so that is executes 8 iterations concurrently for 652each vectorized loop iteration. 653 654On the first iteration of the generated vectorized loop, iterations 0 to 7 of 655the source language loop will be executed using SIMD instructions. Then on the 656next iteration of the generated vectorized loop, iteration 8 to 15 will be 657executed, and so on. 658 659If the source language loop accesses an array element based on the loop 660iteration index, the compiler may read the element into a register for the 661duration of that iteration. Next iteration it will read the next element into 662the register, and so on. With SIMD, this generalizes to the compiler reading 663array elements 0 to 7 into a vector register on the first vectorized loop 664iteration, 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 elements 667are 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 iteration 669index 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, an 673offset and a size, and creates a composite that effectively uses the second 674location description as an overlay of the first, positioned according to the 675offset and size. See ``DW_OP_LLVM_overlay`` and ``DW_OP_LLVM_bit_overlay`` in 676:ref:`amdgpu-dwarf-composite-location-description-operations`. 677 678Consider an array that has been partially registerized such that the currently 679processed elements are held in registers, whereas the remainder of the array 680remains 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]`` into 691registers, adds them, and stores the result back into ``dst[i]``. 692 693Considering the location of ``dst`` and ``src`` in the loop body, the elements 694``dst[i]`` and ``src[i]`` would be located in registers, all other elements are 695located in memory. Let register ``R0`` contain the base address of ``dst``, 696register ``R1`` contain ``i``, and register ``R2`` contain the registerized 697``dst[i]`` element. We can describe the location of ``dst`` as a memory location 698with 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 0 705 706 // 2. Register location description of element dst[i] is located in R2: 707 DW_OP_reg2 708 709 // 3. Offset of the register within the memory of dst: 710 DW_OP_breg1 0 711 DW_OP_lit4 712 DW_OP_mul 713 714 // 4. The size of the register element: 715 DW_OP_lit4 716 717 // 5. Make a composite location description for dst that is the memory #1 with 718 // the register #2 positioned as an overlay at offset #3 of size #4: 719 DW_OP_LLVM_overlay 720 7212.21 Support for Source Language Memory Spaces 722---------------------------------------------- 723 724AMDGPU supports languages, such as OpenCL, that define source language memory 725spaces. Support is added to define language specific memory spaces so they can 726be 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 memory 729spaces in defining source language pointer and reference types (see 730:ref:`amdgpu-dwarf-type-modifier-entries`) and data object allocation (see 731:ref:`amdgpu-dwarf-data-object-entries`). 732 7332.22 Expression Operation Vendor Extensibility Opcode 734----------------------------------------------------- 735 736The vendor extension encoding space for DWARF expression operations 737accommodates only 32 unique operations. In practice, the lack of a central 738registry and a desire for backwards compatibility means vendor extensions are 739never retired, even when standard versions are accepted into DWARF proper. This 740has produced a situation where the effective encoding space available for new 741vendor extensions is miniscule today. 742 743To expand this encoding space a new DWARF operation ``DW_OP_LLVM_user`` is 744added which acts as a "prefix" for vendor extensions. It is followed by a 745ULEB128 encoded vendor extension opcode, which is then followed by the operands 746of the corresponding vendor extension operation. 747 748This approach allows all remaining operations defined in these extensions to be 749encoded 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 5 756====================================== 757 758.. note:: 759 760 This appendix provides changes relative to DWARF Version 5. It has been 761 defined such that it is backwards compatible with DWARF Version 5. 762 Non-normative text is shown in *italics*. The section numbers generally 763 correspond to those in the DWARF Version 5 standard unless specified 764 otherwise. Definitions are given for the additional operations, as well as 765 clarifying how existing expression operations, CFI operations, and attributes 766 behave with respect to generalized location descriptions that support address 767 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 extensions 771 can be implemented as an LLVM vendor extension to DWARF Version 5. New 772 operations other than ``DW_OP_LLVM_user`` are "prefixed" by 773 ``DW_OP_LLVM_user`` to make enough encoding space available for their 774 implementation. 775 776 .. note:: 777 778 Notes are included to describe how the changes are to be applied to the 779 DWARF Version 5 standard. They also describe rational and issues that may 780 need further consideration. 781 782A.2 General Description 783----------------------- 784 785A.2.2 Attribute Types 786~~~~~~~~~~~~~~~~~~~~~ 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 names 795 :name: amdgpu-dwarf-attribute-names-table 796 797 ============================ ==================================== 798 Attribute Usage 799 ============================ ==================================== 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 Expressions 814~~~~~~~~~~~~~~~~~~~~~~~ 815 816.. note:: 817 818 This section, and its nested sections, replaces DWARF Version 5 section 2.5 819 and section 2.6. The new DWARF expression operation extensions are defined as 820 well as clarifying the extensions to already existing DWARF Version 5 821 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, the 826value of an array bound, the length of a dynamic string, the desired value 827itself, and so on.* 828 829If the evaluation of a DWARF expression does not encounter an error, then it can 830either result in a value (see :ref:`amdgpu-dwarf-expression-value`) or a 831location description (see :ref:`amdgpu-dwarf-location-description`). When a 832DWARF expression is evaluated, it may be specified whether a value or location 833description is required as the result kind. 834 835If a result kind is specified, and the result of the evaluation does not match 836the specified result kind, then the implicit conversions described in 837:ref:`amdgpu-dwarf-memory-location-description-operations` are performed if 838valid. Otherwise, the DWARF expression is ill-formed. 839 840If the evaluation of a DWARF expression encounters an evaluation error, then the 841result is an evaluation error. 842 843.. note:: 844 845 Decided to define the concept of an evaluation error. An alternative is to 846 introduce an undefined value base type in a similar way to location 847 descriptions having an undefined location description. Then operations that 848 encounter an evaluation error can return the undefined location description or 849 value with an undefined base type. 850 851 All operations that act on values would return an undefined entity if given an 852 undefined value. The expression would then always evaluate to completion, and 853 can be tested to determine if it is an undefined entity. 854 855 However, this would add considerable additional complexity and does not match 856 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 is 861ill-formed or results in an evaluation error. 862 863A DWARF expression can either be encoded as an operation expression (see 864:ref:`amdgpu-dwarf-operation-expressions`), or as a location list expression 865(see :ref:`amdgpu-dwarf-location-list-expressions`). 866 867.. _amdgpu-dwarf-expression-evaluation-context: 868 869A.2.5.1 DWARF Expression Evaluation Context 870+++++++++++++++++++++++++++++++++++++++++++ 871 872A DWARF expression is evaluated in a context that can include a number of 873context elements. If multiple context elements are specified then they must be 874self consistent or the result of the evaluation is undefined. The context 875elements that can be specified are: 876 877*A current result kind* 878 879 The kind of result required by the DWARF expression evaluation. If specified 880 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 not 885 implemented using a SIMT execution model, this corresponds to the source 886 program thread of execution for which a user presented expression is currently 887 being evaluated. For source languages that are implemented using a SIMT 888 execution model, this together with the current lane corresponds to the source 889 program thread of execution for which a user presented expression is currently 890 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 thread 897 specific.* 898 899*A current lane* 900 901 The 0 based SIMT lane identifier to be used in evaluating a user presented 902 expression. This applies to source languages that are implemented for a target 903 architecture using a SIMT execution model. These implementations map source 904 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 that 910 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 program 914 location. It is consistent if the value is greater than or equal to 0 and less 915 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 user 921 presented expression. This applies to target architectures that support 922 optimizations that result in executing multiple source language loop iterations 923 concurrently. 924 925 *For example, software pipelining and SIMD vectorization.* 926 927 It is required for operations that are related to source language loop 928 iterations. 929 930 *For example, the* ``DW_OP_LLVM_push_iteration`` *operation.* 931 932 If specified, it must be consistent with the value of the 933 ``DW_AT_LLVM_iterations`` attribute of the subprogram corresponding to 934 context's frame and program location. It is consistent if the value is greater 935 than or equal to 0 and less than the, possibly default, value of the 936 ``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 that 941 corresponds to an active invocation of a subprogram in the current thread. It 942 is identified by its address on the call stack. The address is referred to as 943 the Canonical Frame Address (CFA). The call frame information is used to 944 determine the CFA for the call frames of the current thread's call stack (see 945 :ref:`amdgpu-dwarf-call-frame-information`). 946 947 It is required for operations that specify target architecture registers to 948 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 the 953 current lane is specified, then that lane must have been active on entry to 954 the call frame (see the ``DW_AT_LLVM_lane_pc`` attribute). Otherwise the 955 result is undefined. 956 957 If it is the currently executing call frame, then it is termed the top call 958 frame. 959 960*A current program location* 961 962 The target architecture program location corresponding to the current call 963 frame of the current thread. 964 965 The program location of the top call frame is the target architecture program 966 counter for the current thread. The call frame information is used to obtain 967 the value of the return address register to determine the program location of 968 the other call frames (see :ref:`amdgpu-dwarf-call-frame-information`). 969 970 It is required for the evaluation of location list expressions to select 971 amongst multiple program location ranges. It is required for operations that 972 specify target architecture registers to support virtual unwinding of the call 973 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 current 980 target architecture program location. 981 982 * If the current call frame F is not the top call frame, it must be the 983 program location associated with the call site in the current caller frame 984 F that invoked the callee frame. 985 986 * If the current lane is specified and the architecture program location LPC 987 computed by the ``DW_AT_LLVM_lane_pc`` attribute for the current lane is not 988 the undefined location description (indicating the lane was not active on 989 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 expression 996 being evaluated. 997 998 It is required for operations that reference debug information associated with 999 the same compilation unit, including indicating if such references use the 1000 32-bit or 64-bit DWARF format. It can also provide the default address space 1001 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 unit 1006 determined from the loaded code object corresponding to the current program 1007 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 that 1010 contains E and not the one that contains the* ``DW_OP_call*`` *operation 1011 expression.* 1012 1013*A current target architecture* 1014 1015 The target architecture. 1016 1017 It is required for operations that specify target architecture specific 1018 entities. 1019 1020 *For example, target architecture specific entities include DWARF register 1021 identifiers, DWARF lane identifiers, DWARF address space identifiers, the 1022 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 must 1027 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 current 1030 thread is specified, then the current target architecture must be the same 1031 as the target architecture of the current thread. 1032 1033 * If the current compilation unit is specified, then the current target 1034 architecture default address space address size must be the same as the 1035 ``address_size`` field in the header of the current compilation unit and any 1036 associated entry in the ``.debug_aranges`` section. 1037 1038 * If the current program location is specified, then the current target 1039 architecture must be the same as the target architecture of any line number 1040 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 target 1044 architecture default address space address size must be the same as the 1045 ``address_size`` field in the header of any entry corresponding to the 1046 current program location in the ``.debug_addr``, ``.debug_line``, 1047 ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and 1048 ``.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 debug 1059 information entries specifies the program object corresponding to a runtime 1060 descriptor as the current object when it evaluates its associated expression.* 1061 1062 The result is undefined if the location description is invalid (see 1063 :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 the 1068 operation expression evaluation stack in the order provided before evaluation 1069 of an operation expression starts. 1070 1071 Some debugger information entries have attributes that evaluate their DWARF 1072 expression value with initial stack entries. In all other cases the initial 1073 stack is empty. 1074 1075 The result is undefined if any location descriptions are invalid (see 1076 :ref:`amdgpu-dwarf-location-description`). 1077 1078If the evaluation requires a context element that is not specified, then the 1079result of the evaluation is an error. 1080 1081*A DWARF expression for a location description may be able to be evaluated 1082without a thread, lane, call frame, program location, or architecture context. 1083For example, the location of a global variable may be able to be evaluated 1084without such context. If the expression evaluates with an error then it may 1085indicate 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 to 1089those 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 all 1092the entries in the ``.debug_info``, ``.debug_addr``, ``.debug_line``, 1093``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and 1094``.debug_loclists.dwo`` sections corresponding to any given program location do 1095not match. 1096 1097.. _amdgpu-dwarf-expression-value: 1098 1099A.2.5.2 DWARF Expression Value 1100++++++++++++++++++++++++++++++ 1101 1102A value has a type and a literal value. It can represent a literal value of any 1103supported base type of the target architecture. The base type specifies the 1104size, 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 be 1109 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 storage 1111 created by the ``DW_OP_implicit_pointer`` or 1112 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. The literal value would 1113 record the debugging information entry and byte displacement specified by the 1114 associated ``DW_OP_implicit_pointer`` or 1115 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. 1116 1117There is a distinguished base type termed the generic type, which is an integral 1118type that has the size of an address in the target architecture default address 1119space, a target architecture defined endianity, and unspecified signedness. 1120 1121*The generic type is the same as the unspecified type used for stack operations 1122defined 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 the 1127inclusive 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 to 1132 consider it as integral. 1133 1134.. _amdgpu-dwarf-location-description: 1135 1136A.2.5.3 DWARF Location Description 1137++++++++++++++++++++++++++++++++++ 1138 1139*Debugging information must provide consumers a way to find the location of 1140program variables, determine the bounds of dynamic arrays and strings, and 1141possibly to find the base address of a subprogram’s call frame or the return 1142address of a subprogram. Furthermore, to meet the needs of recent computer 1143architectures and optimization techniques, debugging information must be able to 1144describe the location of an object whose location changes over the object’s 1145lifetime, and may reside at multiple locations simultaneously during parts of an 1146object's lifetime.* 1147 1148Information about the location of program objects is provided by location 1149descriptions. 1150 1151Location descriptions can consist of one or more single location descriptions. 1152 1153A single location description specifies the location storage that holds a 1154program object and a position within the location storage where the program 1155object starts. The position within the location storage is expressed as a bit 1156offset relative to the start of the location storage. 1157 1158A location storage is a linear stream of bits that can hold values. Each 1159location storage has a size in bits and can be accessed using a zero-based bit 1160offset. The ordering of bits within a location storage uses the bit numbering 1161and direction conventions that are appropriate to the current language on the 1162target 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 and 1180 some from another location storage, or from disjoint parts of the same 1181 location storage. 1182 1183.. note:: 1184 1185 It may be better to add an implicit pointer location storage kind used by the 1186 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer`` 1187 operations. It would specify the debugger information entry and byte offset 1188 provided by the operations. 1189 1190*Location descriptions are a language independent representation of addressing 1191rules.* 1192 1193* *They can be the result of evaluating a debugger information entry attribute 1194 that specifies an operation expression of arbitrary complexity. In this usage 1195 they can describe the location of an object as long as its lifetime is either 1196 static or the same as the lexical block (see 1197 :ref:`amdgpu-dwarf-lexical-block-entries`) that owns it, and it does not move 1198 during its lifetime.* 1199 1200* *They can be the result of evaluating a debugger information entry attribute 1201 that specifies a location list expression. In this usage they can describe the 1202 location of an object that has a limited lifetime, changes its location during 1203 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, the 1206DWARF expression is ill-formed if the object value held in each single location 1207description's position within the associated location storage is not the same 1208value, except for the parts of the value that are uninitialized. 1209 1210*A location description that has more than one single location description can 1211only be created by a location list expression that has overlapping program 1212location ranges, or certain expression operations that act on a location 1213description that has more than one single location description. There are no 1214operation expression operations that can directly create a location description 1215with more than one single location description.* 1216 1217*A location description with more than one single location description can be 1218used to describe objects that reside in more than one piece of storage at the 1219same time. An object may have more than one location as a result of 1220optimization. For example, a value that is only read may be promoted from memory 1221to a register for some region of code, but later code may revert to reading the 1222value from memory as the register may be used for other purposes. For the code 1223region where the value is in a register, any change to the object value must be 1224made in both the register and the memory so both regions of code will read the 1225updated value.* 1226 1227*A consumer of a location description with more than one single location 1228description can read the object's value from any of the single location 1229descriptions (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 a 1233location description. If such a location description is accessed, the storage it 1234denotes is that associated with the context element values specified when the 1235location description was created, which may differ from the context at the time 1236it is accessed. 1237 1238*For example, creating a register location description requires the thread 1239context: the location storage is for the specified register of that thread. 1240Creating a memory location description for an address space may required a 1241thread and a lane context: the location storage is the memory associated with 1242that 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 call 1251 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 that 1254 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 call 1259 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 location 1263description as the object context or initial stack context to compute a 1264component of the object. The final result is undefined if the object location 1265description becomes invalid between the two expression evaluations.* 1266 1267A change of a thread's program location may not make a location description 1268invalid, yet may still render it as no longer meaningful. Accessing such a 1269location description, or using it as the object context or initial stack context 1270of an expression evaluation, may produce an undefined result. 1271 1272*For example, a location description may specify a register that no longer holds 1273the intended program object after a program location change. One way to avoid 1274such problems is to recompute location descriptions associated with threads when 1275their program locations change.* 1276 1277.. _amdgpu-dwarf-operation-expressions: 1278 1279A.2.5.4 DWARF Operation Expressions 1280+++++++++++++++++++++++++++++++++++ 1281 1282An operation expression is comprised of a stream of operations, each consisting 1283of an opcode followed by zero or more operands. The number of operands is 1284implied by the opcode. 1285 1286Operations represent a postfix operation on a simple stack machine. Each stack 1287entry can hold either a value or a location description. Operations can act on 1288entries on the stack, including adding entries and removing entries. If the kind 1289of a stack entry does not match the kind required by the operation and is not 1290implicitly convertible to the required kind (see 1291:ref:`amdgpu-dwarf-memory-location-description-operations`), then the DWARF 1292operation expression is ill-formed. 1293 1294Evaluation of an operation expression starts with an empty stack on which the 1295entries from the initial stack provided by the context are pushed in the order 1296provided. Then the operations are evaluated, starting with the first operation 1297of the stream. Evaluation continues until either an operation has an evaluation 1298error, 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 an 1303 expression that has an evaluation error, then the result is an evaluation 1304 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 one 1309 undefined location description. 1310 1311 *This rule is for backwards compatibility with DWARF Version 5 which has no 1312 explicit operation to create an undefined location description, and uses an 1313 empty operation expression for this purpose.* 1314 1315 * If the top stack entry is a location description, or can be converted 1316 to one (see :ref:`amdgpu-dwarf-memory-location-description-operations`), 1317 then the result is that, possibly converted, location description. Any other 1318 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 as 1325 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 (see 1330 :ref:`amdgpu-dwarf-memory-location-description-operations`), then the result 1331 is that, possibly converted, value. Any other entries on the stack are 1332 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 one 1339 undefined location description. 1340 1341 *This rule is for backwards compatibility with DWARF Version 5 which has no 1342 explicit operation to create an undefined location description, and uses an 1343 empty operation expression for this purpose.* 1344 1345 .. note:: 1346 1347 This rule is consistent with the rule above for when a location 1348 description is requested. However, GDB appears to report this as an error 1349 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 stack 1352 are discarded. 1353 1354An operation expression is encoded as a byte block with some form of prefix that 1355specifies the byte count. It can be used: 1356 1357* as the value of a debugging information entry attribute that is encoded using 1358 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 (see 1363 :ref:`amdgpu-dwarf-call-frame-information`), 1364 1365* and in location list entries (see 1366 :ref:`amdgpu-dwarf-location-list-expressions`). 1367 1368.. _amdgpu-dwarf-vendor-extensions-operations: 1369 1370A.2.5.4.0 Vendor Extension Operations 1371##################################### 1372 13731. ``DW_OP_LLVM_user`` 1374 1375 ``DW_OP_LLVM_user`` encodes a vendor extension operation. It has at least one 1376 operand: a ULEB128 constant identifying a vendor extension operation. The 1377 remaining operands are defined by the vendor extension. The vendor extension 1378 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 space 1381 defined by DW_OP_lo_user and DW_OP_hi_user that is allocated by the standard 1382 for the same purpose.* 1383 1384.. _amdgpu-dwarf-stack-operations: 1385 1386A.2.5.4.1 Stack Operations 1387########################## 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 the 1394stack 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 composite 1398location description (see 1399:ref:`amdgpu-dwarf-composite-location-description-operations`), then the DWARF 1400expression is ill-formed. 1401 1402.. note:: 1403 1404 These operations now support stack entries that are values and location 1405 descriptions. 1406 1407.. note:: 1408 1409 If it is desired to also make them work with incomplete composite location 1410 descriptions, then would need to define that the composite location storage 1411 specified by the incomplete composite location description is also replicated 1412 when a copy is pushed. This ensures that each copy of the incomplete composite 1413 location description can update the composite location storage they specify 1414 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 index 1427 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 the 1438 stack becomes the second stack entry, and the second stack entry becomes the 1439 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 of 1444 the stack becomes the third stack entry, the second entry becomes the top of 1445 the stack, and the third entry becomes the second entry. 1446 1447*Examples illustrating many of these stack operations are found in Appendix 1448D.1.2 on page 289.* 1449 1450.. _amdgpu-dwarf-control-flow-operations: 1451 1452A.2.5.4.2 Control Flow Operations 1453################################# 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 operation 1460expression. 1461 14621. ``DW_OP_nop`` 1463 1464 ``DW_OP_nop`` is a place holder. It has no effect on the DWARF stack 1465 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-byte 1477 signed integer constant. The 2-byte constant is the number of bytes of the 1478 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, then 1482 the operation expression evaluation is complete. 1483 1484 Otherwise, the DWARF expression is ill-formed if the updated operation 1485 position is not in the range of the first to last operation inclusive, or 1486 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 signed 1491 integer constant. This operation pops the top of stack. If the value popped 1492 is not the constant 0, the 2-byte constant operand is the number of bytes of 1493 the DWARF operation expression to skip forward or backward from the current 1494 operation, beginning after the 2-byte constant. 1495 1496 If the updated position is at one past the end of the last operation, then 1497 the operation expression evaluation is complete. 1498 1499 Otherwise, the DWARF expression is ill-formed if the updated operation 1500 position is not in the range of the first to last operation inclusive, or 1501 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 DWARF 1506 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 a 1510 debugging information entry D relative to the beginning of the current 1511 compilation unit. 1512 1513 ``DW_OP_call_ref`` has one operand that is a 4-byte unsigned value in the 1514 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 D 1516 relative to the beginning of the ``.debug_info`` section that contains the 1517 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. It 1523 states that relocation of references from one executable or shared object 1524 file to another must be performed by the consumer. But given that DR is 1525 defined as an offset in a ``.debug_info`` section this seems impossible. 1526 If DR was defined as an implementation defined value, then the consumer 1527 could choose to interpret the value in an implementation defined manner to 1528 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 so 1531 standard dynamic relocations cannot be used. But even if they were loaded 1532 segments and dynamic relocations were used, DR would need to be the 1533 address of D, not an offset in a ``.debug_info`` section. That would also 1534 need DR to be the size of a global address. So it would not be possible to 1535 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 the 1537 relocated address was in so it could determine the containing compilation 1538 unit. 1539 1540 GDB only interprets DR as an offset in the ``.debug_info`` section that 1541 contains the current compilation unit. 1542 1543 This comment also applies to ``DW_OP_implicit_pointer`` and 1544 ``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 current 1554 operation expression continues from the first operation of E. Execution 1555 continues until one past the last operation of E is reached, at which 1556 point execution continues with the operation following the call operation. 1557 The operations of E are evaluated with the same current context, except 1558 current compilation unit is the one that contains D and the stack is the 1559 same as that being used by the call operation. After the call operation 1560 has been evaluated, the stack is therefore as it is left by the evaluation 1561 of the operations of E. Since E is evaluated on the same stack as the call 1562 operation, E can use, and/or remove entries already on the stack, and can 1563 add new entries to the stack. 1564 1565 *Values on the stack at the time of the call may be used as parameters by 1566 the called expression and values left on the stack by the called expression 1567 may be used as return values by prior agreement between the calling and 1568 called expressions.* 1569 1570 * If D has a ``DW_AT_location`` attribute that is encoded as a ``loclist`` or 1571 ``loclistsptr``, then the specified location list expression E is 1572 evaluated. The evaluation of E uses the current context, except the result 1573 kind is a location description, the compilation unit is the one that 1574 contains D, and the initial stack is empty. The location description 1575 result is pushed on the stack. 1576 1577 .. note:: 1578 1579 This rule avoids having to define how to execute a matched location list 1580 entry operation expression on the same stack as the call when there are 1581 multiple matches. But it allows the call to obtain the location 1582 description for a variable or formal parameter which may use a location 1583 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 the 1587 specified location list expression E' matches a single location list 1588 entry with operation expression E, the same as the ``exprloc`` case and 1589 evaluate on the same stack. 1590 1591 But this is not attractive as if the attribute is for a variable that 1592 happens to end with a non-singleton stack, it will not simply put a 1593 location description on the stack. Presumably the intent of using 1594 ``DW_OP_call*`` on a variable or formal parameter debugger information 1595 entry is to push just one location description on the stack. That 1596 location description may have more than one single location description. 1597 1598 The previous rule for ``exprloc`` also has the same problem, as normally 1599 a variable or formal parameter location expression may leave multiple 1600 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 the 1604 first one and ignores the rest. This seems fundamentally at odds with 1605 the desire to support multiple places for variables. 1606 1607 So, it feels like ``DW_OP_call*`` should both support pushing a location 1608 description on the stack for a variable or formal parameter, and also 1609 support being able to execute an operation expression on the same stack. 1610 Being able to specify a different operation expression for different 1611 program locations seems a desirable feature to retain. 1612 1613 A solution to that is to have a distinct ``DW_AT_LLVM_proc`` attribute 1614 for the ``DW_TAG_dwarf_procedure`` debugging information entry. Then the 1615 ``DW_AT_location`` attribute expression is always executed separately 1616 and pushes a location description (that may have multiple single 1617 location descriptions), and the ``DW_AT_LLVM_proc`` attribute expression 1618 is always executed on the same stack and can leave anything on the 1619 stack. 1620 1621 The ``DW_AT_LLVM_proc`` attribute could have the new classes 1622 ``exprproc``, ``loclistproc``, and ``loclistsptrproc`` to indicate that 1623 the expression is executed on the same stack. ``exprproc`` is the same 1624 encoding as ``exprloc``. ``loclistproc`` and ``loclistsptrproc`` are the 1625 same encoding as their non-\ ``proc`` counterparts, except the DWARF is 1626 ill-formed if the location list does not match exactly one location list 1627 entry and a default entry is required. These forms indicate explicitly 1628 that the matched single operation expression must be executed on the 1629 same stack. This is better than ad hoc special rules for ``loclistproc`` 1630 and ``loclistsptrproc`` which are currently clearly defined to always 1631 return a location description. The producer then explicitly indicates 1632 the intent through the attribute classes. 1633 1634 Such a change would be a breaking change for how GDB implements 1635 ``DW_OP_call*``. However, are the breaking cases actually occurring in 1636 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 some 1638 other features. 1639 1640 Another option is to limit the execution to be on the same stack only to 1641 the evaluation of an expression E that is the value of a 1642 ``DW_AT_location`` attribute of a ``DW_TAG_dwarf_procedure`` debugging 1643 information entry. The DWARF would be ill-formed if E is a location list 1644 expression that does not match exactly one location list entry. In all 1645 other cases the evaluation of an expression E that is the value of a 1646 ``DW_AT_location`` attribute would evaluate E with the current context, 1647 except the result kind is a location description, the compilation unit 1648 is the one that contains D, and the initial stack is empty. The location 1649 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 as 1652 if a ``DW_OP_implicit_value V`` operation was executed. 1653 1654 *This allows a call operation to be used to compute the location 1655 description for any variable or formal parameter regardless of whether the 1656 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`` for 1662 ``DW_TAG_variable`` and ``DW_TAG_formal_parameter`` debugger information 1663 entries that are constants and instead use ``DW_AT_location`` with an 1664 operation expression that results in a location description with one 1665 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`` then 1672 ``DW_OP_call*`` is defined to have no effect. It is unclear that this is 1673 the right definition as a producer should be able to rely on using 1674 ``DW_OP_call*`` to get a location description for any non-\ 1675 ``DW_TAG_dwarf_procedure`` debugging information entries. Also, the 1676 producer should not be creating DWARF with ``DW_OP_call*`` to a 1677 ``DW_TAG_dwarf_procedure`` that does not have a ``DW_AT_location`` 1678 attribute. So, should this case be defined as an ill-formed DWARF 1679 expression? 1680 1681 *The* ``DW_TAG_dwarf_procedure`` *debugging information entry can be used to 1682 define DWARF procedures that can be called.* 1683 1684.. _amdgpu-dwarf-value-operations: 1685 1686A.2.5.4.3 Value Operations 1687########################## 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 a 1692literal value of any supported base type of the target architecture. The base 1693type 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 Operations 1700^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 type 1710size 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 0 1715 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, or 1720 8-byte unsigned integer constant U, respectively. They push the value U with 1721 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, or 1726 8-byte signed integer constant S, respectively. They push the value S with 1727 the generic type. 1728 17294. ``DW_OP_constu`` 1730 1731 ``DW_OP_constu`` has a single unsigned LEB128 integer operand N. It pushes 1732 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 the 1737 value N with the generic type. 1738 17396. ``DW_OP_constx`` 1740 1741 ``DW_OP_constx`` has a single unsigned LEB128 integer operand that 1742 represents a zero-based index into the ``.debug_addr`` section relative to 1743 the value of the ``DW_AT_addr_base`` attribute of the associated compilation 1744 unit. The value N in the ``.debug_addr`` section has the size of the generic 1745 type. It pushes the value N with the generic type. 1746 1747 *The* ``DW_OP_constx`` *operation is provided for constants that require 1748 link-time relocation but should not be interpreted by the consumer as a 1749 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 LEB128 1754 integer DR that represents the byte offset of a debugging information entry 1755 D relative to the beginning of the current compilation unit, that provides 1756 the type T of the constant value. The second is a 1-byte unsigned integral 1757 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 are 1760 interpreted as a value V of the type D. It pushes the value V with the type 1761 D. 1762 1763 The DWARF is ill-formed if D is not a ``DW_TAG_base_type`` debugging 1764 information entry in the current compilation unit, or if TS divided by 8 1765 (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 D 1768 definition, it is encoded explicitly into the operation so that the 1769 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 generic 1775 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 language 1779 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 the 1782 ``DW_AT_LLVM_lanes`` attribute, otherwise the DWARF expression is 1783 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 with 1788 the generic type. 1789 1790 *For source language implementations with optimizations that cause multiple 1791 loop iterations to execute concurrently, this is the zero-based iteration 1792 number that corresponds to the source language concurrent loop iteration 1793 upon which the user is focused.* 1794 1795 The value must be greater than or equal to 0 and less than the value of the 1796 ``DW_AT_LLVM_iterations`` attribute, otherwise the DWARF expression is 1797 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 Operations 1802^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 Operations 1811^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 Operations 1820^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1821 1822.. note:: 1823 1824 This section replaces parts of DWARF Version 5 sections 2.5.1.2, 2.5.1.3, and 1825 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 LEB128 1832 integer that represents a register number R. The second is an unsigned 1833 LEB128 integer DR that represents the byte offset of a debugging information 1834 entry D relative to the beginning of the current compilation unit, that 1835 provides the type T of the register value. 1836 1837 The operation is equivalent to performing ``DW_OP_regx R; DW_OP_deref_type 1838 DR``. 1839 1840 .. note:: 1841 1842 Should DWARF allow the type T to be a larger size than the size of the 1843 register R? Restricting a larger bit size avoids any issue of conversion 1844 as the, possibly truncated, bit contents of the register is simply 1845 interpreted as a value of T. If a conversion is wanted it can be done 1846 explicitly using a ``DW_OP_convert`` operation. 1847 1848 GDB has a per register hook that allows a target specific conversion on a 1849 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 common 1851 architectures. If the compiler for a target architecture did want some 1852 form of conversion, including a larger result type, it could always 1853 explicitly use the ``DW_OP_convert`` operation. 1854 1855 If T is a larger type than the register size, then the default GDB 1856 register hook reads bytes from the next register (or reads out of bounds 1857 for the last register!). Removing use of the target hook does not cause 1858 any test failures in common architectures (except an illegal hand written 1859 assembly test). If a target architecture requires this behavior, these 1860 extensions allow a composite location description to be used to combine 1861 multiple registers. 1862 18632. ``DW_OP_deref`` 1864 1865 S is the bit size of the generic type divided by 8 (the byte size) and 1866 rounded up to a whole number. DR is the offset of a hypothetical debug 1867 information entry D in the current compilation unit for a base type of the 1868 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 that 1875 represents a byte result size S. 1876 1877 TS is the smaller of the generic type bit size and S scaled by 8 (the byte 1878 size). If TS is smaller than the generic type bit size then T is an unsigned 1879 integral type of bit size TS, otherwise T is the generic type. DR is the 1880 offset of a hypothetical debug information entry D in the current 1881 compilation unit for a base type T. 1882 1883 .. note:: 1884 1885 Truncating the value when S is larger than the generic type matches what 1886 GDB does. This allows the generic type size to not be an integral byte 1887 size. It does allow S to be arbitrarily large. Should S be restricted to 1888 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``, except 1891 if T is not the generic type, the value V pushed is zero-extended to the 1892 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 unsigned 1897 integral constant S. The second is an unsigned LEB128 integer DR that 1898 represents the byte offset of a debugging information entry D relative to 1899 the beginning of the current compilation unit, that provides the type T of 1900 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 is 1905 encoded explicitly as the operand S so that the operation can be parsed 1906 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 base 1912 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 by 1917 one of the single location descriptions SL of L. 1918 1919 *If L, or the location description of any composite location description 1920 part that is a subcomponent of L, has more than one single location 1921 description, then any one of them can be selected as they are required to 1922 all have the same value. For any single location description SL, bits are 1923 retrieved from the associated storage location starting at the bit offset 1924 specified by SL. For a composite location description, the retrieved bits 1925 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 location 1933 description that has less than TS bits remaining in the register storage. 1934 Particularly since these extensions extend location descriptions to have 1935 a bit offset, it would be odd to define this as performing sign extension 1936 based on the type, or be target architecture dependent, as the number of 1937 remaining bits could be any number. This matches the GDB implementation 1938 for ``DW_OP_deref_type``. 1939 1940 These extensions define ``DW_OP_*breg*`` in terms of 1941 ``DW_OP_regval_type``. ``DW_OP_regval_type`` is defined in terms of 1942 ``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 the 1944 address size of the address space. This matches the GDB implementation for 1945 ``DW_OP_*breg*``. 1946 1947 The DWARF is ill-formed if D is not in the current compilation unit, D is 1948 not a ``DW_TAG_base_type`` debugging information entry, or if TS divided by 1949 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 no 1954 reason to restrict it. 1955 1956 It is an evaluation error if any bit of the value is retrieved from the 1957 undefined location storage or the offset of any bit exceeds the size of the 1958 location storage LS specified by any single location description SL of L. 1959 1960 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special 1961 rules concerning implicit location descriptions created by the 1962 ``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 type 1968 value that represents an address A. The second must be an integral type 1969 value that represents a target architecture specific address space 1970 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 left 1974 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 that 1982 represents a byte result size S. 1983 1984 It pops two stack entries. The first must be an integral type value that 1985 represents an address A. The second must be an integral type value that 1986 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-extended 1990 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 unsigned 1998 integral constant S. The second operand is an unsigned LEB128 integer DR 1999 that represents the byte offset of a debugging information entry D relative 2000 to the beginning of the current compilation unit, that provides the type T 2001 of the result value. 2002 2003 It pops two stack entries. The first must be an integral type value that 2004 represents an address A. The second must be an integral type value that 2005 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 V 2009 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 in 2017 the context of the calling frame. 2018 2019 *It may be used to determine the value of arguments on entry to the current 2020 call frame provided they are not clobbered.* 2021 2022 It has two operands. The first is an unsigned LEB128 integer S. The second 2023 is a block of bytes, with a length equal S, interpreted as a DWARF 2024 operation expression E. 2025 2026 E is evaluated with the current context, except the result kind is 2027 unspecified, the call frame is the one that called the current frame, the 2028 program location is the call site in the calling frame, the object is 2029 unspecified, and the initial stack is empty. The calling frame information 2030 is obtained by virtually unwinding the current call frame using the call 2031 frame information (see :ref:`amdgpu-dwarf-call-frame-information`). 2032 2033 If the result of E is a location description L (see 2034 :ref:`amdgpu-dwarf-register-location-description-operations`), and the last 2035 operation executed by E is a ``DW_OP_reg*`` for register R with a target 2036 architecture specific base type of T, then the contents of the register are 2037 retrieved as if a ``DW_OP_deref_type DR`` operation was performed where DR 2038 is the offset of a hypothetical debug information entry in the current 2039 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 the 2042 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, as 2047 ``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 is 2054 provided by other means. DWARF Version 5 added the* 2055 ``DW_TAG_call_site_parameter`` *debugger information entry for call sites 2056 that has* ``DW_AT_call_value``\ *,* ``DW_AT_call_data_location``\ *, and* 2057 ``DW_AT_call_data_value`` *attributes that provide DWARF expressions to 2058 compute actual parameter values at the time of the call, and requires the 2059 producer to ensure the expressions are valid to evaluate even when virtually 2060 unwound. The* ``DW_OP_LLVM_call_frame_entry_reg`` *operation provides access 2061 to registers in the virtually unwound calling frame.* 2062 2063 .. note:: 2064 2065 GDB only implements ``DW_OP_entry_value`` when E is exactly 2066 ``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 Operations 2071######################################### 2072 2073This section describes the operations that push location descriptions on the 2074stack. 2075 2076.. _amdgpu-dwarf-general-location-description-operations: 2077 2078A.2.5.4.4.1 General Location Description Operations 2079^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 integral 2088 type value that represents a byte displacement B. The second must be a 2089 location description L. 2090 2091 It adds the value of B scaled by 8 (the byte size) to the bit offset of each 2092 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 0 2095 or greater than or equal to the size of the location storage specified by 2096 SL. 2097 20982. ``DW_OP_LLVM_offset_uconst`` *New* 2099 2100 ``DW_OP_LLVM_offset_uconst`` has a single unsigned LEB128 integer operand 2101 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 field 2107 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 match 2113 ``DW_OP_plus_uconst``, or ``DW_OP_LLVM_offset_constu`` to match 2114 ``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 an 2119 integral type value that represents a bit displacement B. The second must be 2120 a location description L. 2121 2122 It adds the value of B to the bit offset of each single location description 2123 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 0 2126 or greater than or equal to the size of the location storage specified by 2127 SL. 2128 21294. ``DW_OP_push_object_address`` 2130 2131 ``DW_OP_push_object_address`` pushes the location description L of the 2132 current object. 2133 2134 *This object may correspond to an independent variable that is part of a 2135 user presented expression that is being evaluated. The object location 2136 description may be determined from the variable's own debugging information 2137 entry or it may be a component of an array, structure, or class whose 2138 address has been dynamically determined by an earlier step during user 2139 expression evaluation.* 2140 2141 *This operation provides explicit functionality (especially for arrays 2142 involving descriptors) that is analogous to the implicit push of the base 2143 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 description 2149 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 initial 2152 stack. The latter approach is more composable as access to the object may 2153 be needed at any point of the expression, and passing it as the initial 2154 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 a 2156 ``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 an 2159 operation to get the Nth one such as ``DW_OP_arg N``. A vector of 2160 arguments would then be passed in the expression context rather than an 2161 initial stack. This could also resolve the issues with ``DW_OP_call*`` by 2162 allowing a specific number of arguments passed in and returned to be 2163 specified. The ``DW_OP_call*`` operation could then always execute on a 2164 separate stack: the number of arguments would be specified in a new call 2165 operation and taken from the callers stack, and similarly the number of 2166 return results specified and copied from the called stack back to the 2167 callee stack when the called expression was complete. 2168 2169 The only attribute that specifies a current object is 2170 ``DW_AT_data_location`` so the non-normative text seems to overstate how 2171 this is being used. Or are there other attributes that need to state they 2172 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 integer 2177 operand that represents a target architecture register number R. 2178 2179 It pushes a location description L that holds the value of register R on 2180 entry to the current subprogram as defined by the call frame information 2181 (see :ref:`amdgpu-dwarf-call-frame-information`). 2182 2183 *If there is no call frame information defined, then the default rules for 2184 the target architecture are used. If the register rule is* undefined\ *, then 2185 the undefined location description is pushed. If the register rule is* same 2186 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 Operations 2191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 is 2198present 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 bit 2203offset for an undefined location description. The ``DW_OP_LLVM_*offset`` 2204operations leave an undefined location description unchanged. The 2205``DW_OP_*piece`` operations can explicitly or implicitly specify an undefined 2206location description, allowing any size and offset to be specified, and results 2207in 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 one 2212 undefined location description SL. 2213 2214.. _amdgpu-dwarf-memory-location-description-operations: 2215 2216A.2.5.4.4.3 Memory Location Description Operations 2217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 corresponding 2225memory location storage that denotes the linear addressable memory of that 2226address space. The size of each memory location storage corresponds to the range 2227of the addresses in the corresponding address space. 2228 2229*It is target architecture defined how address space location storage maps to 2230target architecture physical memory. For example, they may be independent 2231memory, or more than one location storage may alias the same physical memory 2232possibly at different offsets and with different interleaving. The mapping may 2233also be dictated by the source language address classes.* 2234 2235A memory location description specifies a memory location storage. The bit 2236offset corresponds to a bit position within a byte of the memory. Bits accessed 2237using a memory location description, access the corresponding target 2238architecture memory starting at the bit position within the byte specified by 2239the bit offset. 2240 2241A memory location description that has a bit offset that is a multiple of 8 (the 2242byte size) is defined to be a byte address memory location description. It has a 2243memory 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 multiple 2246of 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 byte 2248address 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 the 2251address space that corresponds to the memory location storage associated with 2252the memory location description. 2253 2254A location description that is comprised of one byte address memory location 2255description SL is defined to be a memory byte address location description. It 2256has a byte address equal to A and an address space equal to AS of the 2257corresponding SL. 2258 2259``DW_ASPACE_LLVM_none`` is defined as the target architecture default address 2260space. See :ref:`amdgpu-dwarf-address-spaces`. 2261 2262If a stack entry is required to be a location description, but it is a value V 2263with the generic type, then it is implicitly converted to a location description 2264L with one memory location description SL. SL specifies the memory location 2265storage that corresponds to the target architecture default address space with a 2266bit 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 to 2271 a memory location description in the target architecture default address 2272 space: 2273 2274 If a stack entry is required to be a location description, but is a value V 2275 with an integral type, then it is implicitly converted to a location 2276 description L with a one memory location description SL. If the type size of 2277 V is less than the generic type size, then the value V is zero extended to 2278 the size of the generic type. The least significant generic type size bits 2279 are treated as an unsigned value to be used as an address A. SL specifies 2280 memory location storage corresponding to the target architecture default 2281 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 an 2285 error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a 2286 hook function, then it is called. The target specific hook function can modify 2287 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 implicit 2291pointer value IPV with the target architecture default address space, then it is 2292implicitly converted to a location description with one single location 2293description specified by IPV. See 2294:ref:`amdgpu-dwarf-implicit-location-description-operations`. 2295 2296.. note:: 2297 2298 Is this rule required for DWARF Version 5 backwards compatibility? If not, it 2299 can be eliminated, and the producer can use 2300 ``DW_OP_LLVM_form_aspace_address``. 2301 2302If a stack entry is required to be a value, but it is a location description L 2303with one memory location description SL in the target architecture default 2304address space with a bit offset B that is a multiple of 8, then it is implicitly 2305converted to a value equal to B divided by 8 (the byte size) with the generic 2306type. 2307 23081. ``DW_OP_addr`` 2309 2310 ``DW_OP_addr`` has a single byte constant value operand, which has the size 2311 of the generic type, that represents an address A. 2312 2313 It pushes a location description L with one memory location description SL 2314 on the stack. SL specifies the memory location storage corresponding to the 2315 target architecture default address space with a bit offset equal to A 2316 scaled by 8 (the byte size). 2317 2318 *If the DWARF is part of a code object, then A may need to be relocated. For 2319 example, in the ELF code object format, A must be adjusted by the difference 2320 between the ELF segment virtual address and the virtual address at which the 2321 segment is loaded.* 2322 23232. ``DW_OP_addrx`` 2324 2325 ``DW_OP_addrx`` has a single unsigned LEB128 integer operand that represents 2326 a zero-based index into the ``.debug_addr`` section relative to the value of 2327 the ``DW_AT_addr_base`` attribute of the associated compilation unit. The 2328 address value A in the ``.debug_addr`` section has the size of the generic 2329 type. 2330 2331 It pushes a location description L with one memory location description SL 2332 on the stack. SL specifies the memory location storage corresponding to the 2333 target architecture default address space with a bit offset equal to A 2334 scaled by 8 (the byte size). 2335 2336 *If the DWARF is part of a code object, then A may need to be relocated. For 2337 example, in the ELF code object format, A must be adjusted by the difference 2338 between the ELF segment virtual address and the virtual address at which the 2339 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 first 2344 must be an integral type value that represents a target architecture 2345 specific address space identifier AS. The second must be an integral type 2346 value that represents an address A. 2347 2348 The address size S is defined as the address bit size of the target 2349 architecture specific address space that corresponds to AS. 2350 2351 A is adjusted to S bits by zero extending if necessary, and then treating 2352 the least significant S bits as an unsigned value A'. 2353 2354 It pushes a location description L with one memory location description SL 2355 on the stack. SL specifies the memory location storage LS that corresponds 2356 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 LS 2359 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 location 2362 storage for the current thread. For languages that are implemented using a 2363 SIMT execution model, then if AS is for per lane storage then LS is the 2364 location storage for the current lane of the current thread. Therefore, if L 2365 is accessed by an operation, the location storage selected when the location 2366 description was created is accessed, and not the location storage associated 2367 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 by 2370 the target architecture specific ``DW_ASPACE_LLVM_*`` values. 2371 2372 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special 2373 rules concerning implicit pointer values produced by dereferencing implicit 2374 location descriptions created by the ``DW_OP_implicit_pointer`` and 2375 ``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 integral 2380 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 SL 2383 on the stack. SL is the target architecture specific memory location 2384 description that corresponds to the thread-local storage address TA. 2385 2386 The meaning of the thread-local storage address TA is defined by the 2387 run-time environment. If the run-time environment supports multiple 2388 thread-local storage blocks for a single thread, then the block 2389 corresponding to the executable or shared library containing this DWARF 2390 expression is used. 2391 2392 *Some implementations of C, C++, Fortran, and other languages, support a 2393 thread-local storage class. Variables with this storage class have distinct 2394 values and addresses in distinct threads, much as automatic variables have 2395 distinct values and addresses in each subprogram invocation. Typically, 2396 there is a single block of storage containing all thread-local variables 2397 declared in the main executable, and a separate block for the variables 2398 declared in each shared library. Each thread-local variable can then be 2399 accessed in its block using an identifier. This identifier is typically a 2400 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 complex 2403 (in some cases, the compiler emits a function call to do it), and difficult 2404 to describe using ordinary DWARF location descriptions. Instead of forcing 2405 complex thread-local storage calculations into the DWARF expressions, the* 2406 ``DW_OP_form_tls_address`` *allows the consumer to perform the computation 2407 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 Canonical 2412 Frame Address (CFA) of the current subprogram, obtained from the call frame 2413 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 debugger 2416 information entry corresponding to the current subprogram can be computed 2417 using a location list expression, in some cases this would require an 2418 extensive location list because the values of the registers used in 2419 computing the CFA change during a subprogram execution. If the call frame 2420 information is present, then it already encodes such changes, and it is 2421 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 a 2427 byte displacement B. 2428 2429 The location description L for the *frame base* of the current subprogram is 2430 obtained from the ``DW_AT_frame_base`` attribute of the debugger information 2431 entry corresponding to the current subprogram as described in 2432 :ref:`amdgpu-dwarf-low-level-information`. 2433 2434 The location description L is updated as if the ``DW_OP_LLVM_offset_uconst 2435 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 to 2441 the N in the operation name. 2442 2443 They have a single signed LEB128 integer operand that represents a byte 2444 displacement B. 2445 2446 The address space identifier AS is defined as the one corresponding to the 2447 target architecture specific default address space. 2448 2449 The address size S is defined as the address bit size of the target 2450 architecture specific address space corresponding to AS. 2451 2452 The contents of the register specified by R are retrieved as if a 2453 ``DW_OP_regval_type R, DR`` operation was performed where DR is the offset 2454 of a hypothetical debug information entry in the current compilation unit 2455 for an unsigned integral base type of size S bits. B is added and the least 2456 significant S bits are treated as an unsigned value to be used as an address 2457 A. 2458 2459 They push a location description L comprising one memory location 2460 description LS on the stack. LS specifies the memory location storage that 2461 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 integer 2466 that represents a register number R. The second is a signed LEB128 2467 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 as 2470 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 unsigned 2475 LEB128 integer that represents a register number R. The second is a signed 2476 LEB128 integer that represents a byte displacement B. It pops one stack 2477 entry that is required to be an integral type value that represents a target 2478 architecture specific address space identifier AS. 2479 2480 The action is the same as for ``DW_OP_breg<N>``, except that R is used as 2481 the register number, B is used as the byte displacement, and AS is used as 2482 the address space identifier. 2483 2484 The DWARF expression is ill-formed if AS is not one of the values defined by 2485 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 save 2491 encoding size. 2492 2493.. _amdgpu-dwarf-register-location-description-operations: 2494 2495A.2.5.4.4.4 Register Location Description Operations 2496^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 target 2503architecture registers. The size of each register location storage corresponds 2504to the size of the corresponding target architecture register. 2505 2506A register location description specifies a register location storage. The bit 2507offset corresponds to a bit position within the register. Bits accessed using a 2508register location description access the corresponding target architecture 2509register 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 register 2515 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 represents 2522 a target architecture register number R. 2523 2524 If the current call frame is the top call frame, it pushes a location 2525 description L that specifies one register location description SL on the 2526 stack. SL specifies the register location storage that corresponds to R with 2527 a bit offset of 0 for the current thread. 2528 2529 If the current call frame is not the top call frame, call frame information 2530 (see :ref:`amdgpu-dwarf-call-frame-information`) is used to determine the 2531 location description that holds the register for the current call frame and 2532 current program location of the current thread. The resulting location 2533 description L is pushed. 2534 2535 *Note that if call frame information is used, the resulting location 2536 description may be register, memory, or undefined.* 2537 2538 *An implementation may evaluate the call frame information immediately, or 2539 may defer evaluation until L is accessed by an operation. If evaluation is 2540 deferred, R and the current context can be recorded in L. When accessed, the 2541 recorded context is used to evaluate the call frame information, not the 2542 current context of the access operation.* 2543 2544*These operations obtain a register location. To fetch the contents of a 2545register, 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 Operations 2552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 no 2559actual location in the program but whose contents are nonetheless known, either 2560as 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 bit 2563offset corresponds to a bit position within the implicit location storage. Bits 2564accessed using an implicit location description, access the corresponding 2565implicit 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 LEB128 2570 integer that represents a byte size S. The second is a block of bytes with a 2571 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 a 2574 size of S. 2575 2576 It pushes location description L with one implicit location description SL 2577 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 using 2584 the size, encoding, and endianity specified by V's base type. 2585 2586 It pushes a location description L with one implicit location description SL 2587 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 not 2590 exist in memory, but its value is nonetheless known. In this form, the 2591 location description specifies the actual value of the object, rather than 2592 specifying the memory or register storage that holds the value.* 2593 2594 See ``DW_OP_implicit_pointer`` (following) for special rules concerning 2595 implicit pointer values produced by dereferencing implicit location 2596 descriptions created by the ``DW_OP_implicit_pointer`` and 2597 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. 2598 2599 Note: Since location descriptions are allowed on the stack, the 2600 ``DW_OP_stack_value`` operation no longer terminates the DWARF operation 2601 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 the 2606 value that the pointer addressed.* ``DW_OP_implicit_pointer`` *allows a 2607 producer to describe this value.* 2608 2609 ``DW_OP_implicit_pointer`` *specifies an object is a pointer to the target 2610 architecture default address space that cannot be represented as a real 2611 pointer, even though the value it would point to can be described. In this 2612 form, the location description specifies a debugging information entry that 2613 represents the actual location description of the object to which the 2614 pointer would point. Thus, a consumer of the debug information would be able 2615 to access the dereferenced pointer, even when it cannot access the pointer 2616 itself.* 2617 2618 ``DW_OP_implicit_pointer`` has two operands. The first operand is a 4-byte 2619 unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in 2620 the 64-bit DWARF format, that represents the byte offset DR of a debugging 2621 information entry D relative to the beginning of the ``.debug_info`` section 2622 that contains the current compilation unit. The second operand is a signed 2623 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 the 2631 target architecture specific default address space. 2632 2633 The address size S is defined as the address bit size of the target 2634 architecture specific address space corresponding to AS. 2635 2636 An implicit location storage LS is created with the debugging information 2637 entry D, address space AS, and size of S. 2638 2639 It pushes a location description L that comprises one implicit location 2640 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 location 2643 description L', and retrieves S bits, such that any retrieved bits come from 2644 an implicit location storage that is the same as LS, unless both the 2645 following conditions are met: 2646 2647 1. All retrieved bits come from an implicit location description that 2648 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 location 2651 description, as L' may involve composite location descriptions.* 2652 2653 2. The bits come from consecutive ascending offsets within their respective 2654 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 the 2659 ``DW_OP_deref*`` operation is an implicit pointer value IPV with a target 2660 architecture specific address space of AS, a debugging information entry of 2661 D, and a base type of T. If AS is the target architecture default address 2662 space, then T is the generic type. Otherwise, T is a target architecture 2663 specific integral type with a bit size equal to S. 2664 2665 If IPV is either implicitly converted to a location description (only done 2666 if AS is the target architecture default address space) or used by 2667 ``DW_OP_LLVM_form_aspace_address`` (only done if the address space popped by 2668 ``DW_OP_LLVM_form_aspace_address`` is AS), then the resulting location 2669 description RL is: 2670 2671 * If D has a ``DW_AT_location`` attribute, the DWARF expression E from the 2672 ``DW_AT_location`` attribute is evaluated with the current context, except 2673 that the result kind is a location description, the compilation unit is 2674 the one that contains D, the object is unspecified, and the initial stack 2675 is empty. RL is the expression result. 2676 2677 *Note that E is evaluated with the context of the expression accessing 2678 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 location 2683 storage RLS is created from the ``DW_AT_const_value`` attribute's value 2684 with a size matching the size of the ``DW_AT_const_value`` attribute's 2685 value. RL comprises one implicit location description SRL. SRL specifies 2686 RLS with a bit offset of 0. 2687 2688 .. note:: 2689 2690 If using ``DW_AT_const_value`` for variables and formal parameters is 2691 deprecated and instead ``DW_AT_location`` is used with an implicit 2692 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 created 2705 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 implicit 2707 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 as 2712 for ``DW_OP_implicit_pointer``. 2713 2714 It pops one stack entry that must be an integral type value that represents 2715 a target architecture specific address space identifier AS. 2716 2717 The location description L that is pushed on the stack is the same as for 2718 ``DW_OP_implicit_pointer``, except that the address space identifier used is 2719 AS. 2720 2721 The DWARF expression is ill-formed if AS is not one of the values defined by 2722 the target architecture specific ``DW_ASPACE_LLVM_*`` values. 2723 2724 .. note:: 2725 2726 This definition of ``DW_OP_LLVM_aspace_implicit_pointer`` may change when 2727 full support for address classes is added as required for languages such 2728 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 expression 2732E*\ :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 information 2737entry D*\ :sub:`2` *whose* ``DW_AT_location`` *attribute gives a second DWARF 2738expression E*\ :sub:`2`\ *.* 2739 2740*D*\ :sub:`1` *and E*\ :sub:`1` *are describing the location of a pointer type 2741object. D*\ :sub:`2` *and E*\ :sub:`2` *are describing the location of the 2742object 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 can 2747reconstruct the value of the object when asked to dereference the pointer 2748described 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 Operations 2754^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 be 2761contained in part of another location storage or contained in parts of more 2762than one location storage. 2763 2764Each part has a part location description L and a part bit size S. L can have 2765one or more single location descriptions SL. If there are more than one SL then 2766that indicates that part is located in more than one place. The bits of each 2767place of the part comprise S contiguous bits from the location storage LS 2768specified by SL starting at the bit offset specified by SL. All the bits must 2769be 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 are 2772contiguous such that the zero-based location storage bit index will range over 2773each part with no gaps between them. Therefore, the size of a composite location 2774storage is the sum of the size of its parts. The DWARF expression is ill-formed 2775if the size of the contiguous location storage is larger than the size of the 2776memory location storage corresponding to the largest target architecture 2777specific address space. 2778 2779A composite location description specifies a composite location storage. The bit 2780offset 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 be 2785incrementally created. Each part is created by a separate operation. There may 2786be one or more operations to create the final composite location storage. A 2787series of such operations describes the parts of the composite location storage 2788that are in the order that the associated part operations are executed. 2789 2790To support incremental creation, a composite location storage can be in an 2791incomplete state. When an incremental operation operates on an incomplete 2792composite location storage, it adds a new part, otherwise it creates a new 2793composite location storage. The ``DW_OP_LLVM_piece_end`` operation explicitly 2794makes an incomplete composite location storage complete. 2795 2796A composite location description that specifies a composite location storage 2797that is incomplete is termed an incomplete composite location description. A 2798composite location description that specifies a composite location storage that 2799is complete is termed a complete composite location description. 2800 2801If the top stack entry is a location description that has one incomplete 2802composite location description SL after the execution of an operation expression 2803has completed, SL is converted to a complete composite location description. 2804 2805*Note that this conversion does not happen after the completion of an operation 2806expression that is evaluated on the same stack by the* ``DW_OP_call*`` 2807*operations. Such executions are not a separate evaluation of an operation 2808expression, but rather the continued evaluation of the same operation expression 2809that contains the* ``DW_OP_call*`` *operation.* 2810 2811If a stack entry is required to be a location description L, but L has an 2812incomplete composite location description, then the DWARF expression is 2813ill-formed. The exception is for the operations involved in incrementally 2814creating a composite location description as described below. 2815 2816*Note that a DWARF operation expression may arbitrarily compose composite 2817location descriptions from any other location description, including those that 2818have multiple single location descriptions, and those that have composite 2819location descriptions.* 2820 2821*The incremental composite location description operations are defined to be 2822compatible 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 byte 2827 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 one 2832 incomplete composite location description SL is pushed on the stack. 2833 2834 An incomplete composite location storage LS is created with a single part 2835 P. P specifies a location description PL and has a bit size of S scaled by 2836 8 (the byte size). PL is comprised of one undefined location description 2837 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 of 2842 one incomplete composite location description SL, then the incomplete 2843 composite location storage LS that SL specifies is updated to append a new 2844 part P. P specifies a location description PL and has a bit size of S 2845 scaled by 8 (the byte size). PL is comprised of one undefined location 2846 description PSL. L is left on the stack. 2847 2848 * Otherwise, if the top stack entry is a location description or can be 2849 converted to one, then it is popped and treated as a part location 2850 description PL. Then: 2851 2852 * If the top stack entry (after popping PL) is a location description L 2853 comprised of one incomplete composite location description SL, then the 2854 incomplete composite location storage LS that SL specifies is updated to 2855 append a new part P. P specifies the location description PL and has a 2856 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 incomplete 2859 composite location description SL is pushed on the stack. 2860 2861 An incomplete composite location storage LS is created with a single 2862 part P. P specifies the location description PL and has a bit size of S 2863 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-formed 2868 2869 *Many compilers store a single variable in sets of registers or store a 2870 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 as 2875 the part location description of a* ``DW_OP_piece`` *operation.* 2876 2877 *The evaluation rules for the* ``DW_OP_piece`` *operation allow it to be 2878 compatible with the DWARF Version 5 definition.* 2879 2880 .. note:: 2881 2882 Since these extensions allow location descriptions to be entries on the 2883 stack, a simpler operation to create composite location descriptions could 2884 be defined. For example, just one operation that specifies how many parts, 2885 and pops pairs of stack entries for the part size and location 2886 description. Not only would this be a simpler operation and avoid the 2887 complexities of incomplete composite location descriptions, but it may 2888 also have a smaller encoding in practice. However, the desire for 2889 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 LEB128 2894 integer that represents the part bit size S. The second is an unsigned 2895 LEB128 integer that represents a bit displacement B. 2896 2897 The action is the same as for ``DW_OP_piece``, except that any part created 2898 has the bit size S, and the location description PL of any created part is 2899 updated as if the ``DW_OP_constu B; DW_OP_LLVM_bit_offset`` operations were 2900 applied. 2901 2902 ``DW_OP_bit_piece`` *is used instead of* ``DW_OP_piece`` *when the piece to 2903 be assembled is not byte-sized or is not at the start of the part location 2904 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 as 2908 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 be 2913 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 one 2918 incomplete composite location description SL, then the DWARF expression is 2919 ill-formed. 2920 2921 Otherwise, the incomplete composite location storage LS specified by SL is 2922 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 LEB128 2927 integer that represents the element bit size S. The second is an unsigned 2928 LEB128 integer that represents a count C. 2929 2930 It pops one stack entry that must be a location description and is treated 2931 as the part location description PL. 2932 2933 A location description L comprised of one complete composite location 2934 description SL is pushed on the stack. 2935 2936 A complete composite location storage LS is created with C identical parts 2937 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 unsigned 2946 LEB128 integer that represents the element bit size S. The second is an 2947 unsigned LEB128 integer that represents a count C. 2948 2949 It pops three stack entries. The first must be an integral type value that 2950 represents a bit mask value M. The second must be a location description 2951 that represents the one-location description L1. The third must be a 2952 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` specifies 2956 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 was 2959 applied to PLX\ :sub:`N`\ . 2960 2961 PLX\ :sub:`N` is the same as L0 if the N\ :sup:`th` least significant bit of 2962 M is a zero, otherwise it is the same as L1. 2963 2964 A location description L comprised of one complete composite location 2965 description SL is pushed on the stack. SL specifies LS with a bit offset of 2966 0. 2967 2968 The DWARF expression is ill-formed if S or C are 0, or if the bit size of M 2969 is less than C. 2970 2971 .. note:: 2972 2973 Should the count operand for DW_OP_extend and DW_OP_select_bit_piece be 2974 changed to get the count value off the stack? This would allow support for 2975 architectures that have variable length vector instructions such as ARM 2976 and RISC-V. 2977 29786. ``DW_OP_LLVM_overlay`` *New* 2979 2980 ``DW_OP_LLVM_overlay`` pops four stack entries. The first must be an 2981 integral type value that represents the overlay byte size value S. The 2982 second must be an integral type value that represents the overlay byte 2983 offset value O. The third must be a location description that represents the 2984 overlay location description OL. The fourth must be a location description 2985 that represents the base location description BL. 2986 2987 The action is the same as for ``DW_OP_LLVM_bit_overlay``, except that the 2988 overlay bit size BS and overlay bit offset BO used are S and O respectively 2989 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 an 2994 integral type value that represents the overlay bit size value BS. The 2995 second must be an integral type value that represents the overlay bit offset 2996 value BO. The third must be a location description that represents the 2997 overlay location description OL. The fourth must be a location description 2998 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 as 3003 follows. LS is the location storage and LO is the location bit offset 3004 specified by a single location description SL of L. The remaining bit 3005 storage size RBSS of SL is the bit size of LS minus LO. *rbss(L)* is the 3006 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 to 3015 push a composite location description. 3016 3017 *The composite location description is conceptually the base location 3018 description BL with the overlay location description OL positioned as an 3019 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_piece 3022 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 performing 3025 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 Expressions 3031+++++++++++++++++++++++++++++++++++++++ 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 whose 3039location changes over the object’s lifetime, and may reside at multiple 3040locations during parts of an object's lifetime. Location list expressions are 3041used in place of operation expressions whenever the object whose location is 3042being described has these requirements.* 3043 3044A location list expression consists of a series of location list entries. Each 3045location 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 that 3050 evaluates to the location description of an object that is valid over a 3051 lifetime bounded by a starting and ending address. The starting address is the 3052 lowest address of the address range over which the location is valid. The 3053 ending address is the address of the first location past the highest address 3054 of the address range. 3055 3056 The location list entry matches when the current program location is within 3057 the given range. 3058 3059 There are several kinds of bounded location description entries which differ 3060 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 that 3065 evaluates to the location description of an object that is valid when no 3066 bounded location description entry applies. 3067 3068 The location list entry matches when the current program location is not 3069 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 base 3074 address for beginning and ending address offsets given in certain kinds of 3075 bounded location description entries. The applicable base address of a bounded 3076 location description entry is the address specified by the closest preceding 3077 base address entry in the same location list. If there is no preceding base 3078 address entry, then the applicable base address defaults to the base address 3079 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 contained 3082 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 list 3087 expression. 3088 3089The address ranges defined by the bounded location description entries of a 3090location list expression may overlap. When they do, they describe a situation in 3091which an object exists simultaneously in more than one place. 3092 3093If all of the address ranges in a given location list expression do not 3094collectively cover the entire range over which the object in question is 3095defined, and there is no following default location description entry, it is 3096assumed that the object is not available for the portion of the range that is 3097not 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 evaluation 3102 error. 3103 3104 .. note:: 3105 3106 If the location list only has a single default entry, should that be 3107 considered a match if there is no program location? If there are non-default 3108 entries then it seems it has to be an evaluation error when there is no 3109 program location as that indicates the location depends on the program 3110 location which is not known. 3111 3112* If there are no matching location list entries, then the result is a location 3113 description that comprises one undefined location description. 3114 3115* Otherwise, the operation expression E of each matching location list entry is 3116 evaluated with the current context, except that the result kind is a location 3117 description, the object is unspecified, and the initial stack is empty. The 3118 location list entry result is the location description returned by the 3119 evaluation of E. 3120 3121 The result is a location description that is comprised of the union of the 3122 single location descriptions of the location description result of each 3123 matching location list entry. 3124 3125A location list expression can only be used as the value of a debugger 3126information entry attribute that is encoded using class ``loclist`` or 3127``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the 3128attribute provides an index into a separate object file section called 3129``.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 to 3133specify a debugger information entry attribute that has a location list 3134expression. Several debugger information entry attributes allow DWARF 3135expressions that are evaluated with an initial stack that includes a location 3136description that may originate from the evaluation of a location list 3137expression. 3138 3139*This location list representation, the* ``loclist`` *and* ``loclistsptr`` 3140*class, and the related* ``DW_AT_loclists_base`` *attribute are new in DWARF 3141Version 5. Together they eliminate most, or all of the code object relocations 3142previously 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 Spaces 3151~~~~~~~~~~~~~~~~~~~~~ 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 linear 3158addressable memory areas. They are used in DWARF expression location 3159descriptions to describe in which target architecture specific memory area data 3160resides. 3161 3162*Target architecture specific DWARF address spaces may correspond to hardware 3163supported facilities such as memory utilizing base address registers, scratchpad 3164memory, and memory with special interleaving. The size of addresses in these 3165address spaces may vary. Their access and allocation may be hardware managed 3166with each thread or group of threads having access to independent storage. For 3167these reasons they may have properties that do not allow them to be viewed as 3168part of the unified global virtual address space accessible by all threads.* 3169 3170*It is target architecture specific whether multiple DWARF address spaces are 3171supported and how source language memory spaces map to target architecture 3172specific DWARF address spaces. A target architecture may map multiple source 3173language memory spaces to the same target architecture specific DWARF address 3174class. Optimization may determine that variable lifetime and access pattern 3175allows them to be allocated in faster scratchpad memory represented by a 3176different DWARF address space than the default for the source language memory 3177space.* 3178 3179Although DWARF address space identifiers are target architecture specific, 3180``DW_ASPACE_LLVM_none`` is a common address space supported by all target 3181architectures, 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``, and 3189 ``DW_OP_xderef*``. 3190 3191* The CFI instructions: ``DW_CFA_def_aspace_cfa`` and 3192 ``DW_CFA_def_aspace_cfa_sf``. 3193 3194.. note:: 3195 3196 Currently, DWARF defines address class values as being target architecture 3197 specific, and defines a DW_AT_address_class attribute. With the removal of 3198 DW_AT_segment in DWARF 6, it is unclear how the address class is intended to 3199 be used as the term is not used elsewhere. Should these be replaced by this 3200 proposal's more complete address space? Or are they intended to represent 3201 source language memory spaces such as in OpenCL? 3202 3203.. _amdgpu-dwarf-memory-spaces: 3204 3205A.2.14 Memory Spaces 3206~~~~~~~~~~~~~~~~~~~~ 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 of 3213memory spaces. They are used in the ``DW_AT_LLVM_memory_space`` attribute for 3214pointer type, reference type, variable, formal parameter, and constant debugger 3215information entries. 3216 3217Each DWARF memory space is conceptually a separate source language memory space 3218with its own lifetime and aliasing rules. DWARF memory spaces are used to 3219specify the source language memory spaces that pointer type and reference type 3220values refer, and to specify the source language memory space in which variables 3221are allocated. 3222 3223Although DWARF memory space identifiers are source language specific, 3224``DW_MSPACE_LLVM_none`` is a common memory space supported by all source 3225languages, and defined as the source language default memory space. 3226 3227The set of currently defined DWARF memory spaces, together with source language 3228mappings, is given in :ref:`amdgpu-dwarf-source-language-memory-spaces-table`. 3229 3230Vendor defined source language memory spaces may be defined using codes in the 3231range ``DW_MSPACE_LLVM_lo_user`` to ``DW_MSPACE_LLVM_hi_user``. 3232 3233.. table:: Source language memory spaces 3234 :name: amdgpu-dwarf-source-language-memory-spaces-table 3235 3236 =========================== ============ ============== ============== ============== 3237 Memory Space Name Meaning C/C++ OpenCL CUDA/HIP 3238 =========================== ============ ============== ============== ============== 3239 ``DW_MSPACE_LLVM_none`` generic *default* generic *default* 3240 ``DW_MSPACE_LLVM_global`` global global 3241 ``DW_MSPACE_LLVM_constant`` constant constant constant 3242 ``DW_MSPACE_LLVM_group`` thread-group local shared 3243 ``DW_MSPACE_LLVM_private`` thread private 3244 ``DW_MSPACE_LLVM_lo_user`` 3245 ``DW_MSPACE_LLVM_hi_user`` 3246 =========================== ============ ============== ============== ============== 3247 3248.. note:: 3249 3250 The approach presented in 3251 :ref:`amdgpu-dwarf-source-language-memory-spaces-table` is to define the 3252 default ``DW_MSPACE_LLVM_none`` to be the generic address class and not the 3253 global address class. This matches how CLANG and LLVM have added support for 3254 CUDA-like languages on top of existing C++ language support. This allows all 3255 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 the 3258 global memory space and then change ``DW_MSPACE_LLVM_global`` to 3259 ``DW_MSPACE_LLVM_generic``. This would match the reality that languages that 3260 do not support multiple memory spaces only have one default global memory 3261 space. Generally, in these languages if they expose that the target 3262 architecture supports multiple memory spaces, the default one is still the 3263 global memory space. Then a language that does support multiple memory spaces 3264 has to explicitly indicate which pointers have the added ability to reference 3265 more than the global memory space. However, compilers generating DWARF for 3266 CUDA-like languages would then have to define every CUDA-like language pointer 3267 type or reference type with a ``DW_AT_LLVM_memory_space`` attribute of 3268 ``DW_MSPACE_LLVM_generic`` to match the language semantics. 3269 3270A.3 Program Scope Entries 3271------------------------- 3272 3273.. note:: 3274 3275 This section provides changes to existing debugger information entry 3276 attributes. These would be incorporated into the corresponding DWARF Version 5 3277 chapter 3 sections. 3278 3279A.3.1 Unit Entries 3280~~~~~~~~~~~~~~~~~~ 3281 3282.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries: 3283 3284A.3.1.1 Full and Partial Compilation Unit Entries 3285+++++++++++++++++++++++++++++++++++++++++++++++++ 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`` attribute 3292are defined in :ref:`amdgpu-dwarf-language-names-table`. 3293 3294.. table:: Language Names 3295 :name: amdgpu-dwarf-language-names-table 3296 3297 ==================== ============================= 3298 Language Name Meaning 3299 ==================== ============================= 3300 ``DW_LANG_LLVM_HIP`` HIP Language. 3301 ==================== ============================= 3302 3303The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending 3304the 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 unit 3311 may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an 3312 augmentation string. 3313 3314 *The augmentation string allows producers to indicate that there is 3315 additional vendor or target specific information in the debugging 3316 information entries. For example, this might be information about the 3317 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 no 3320 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 Y 3327 version number of the extensions used, and *options* is an optional string 3328 providing additional information about the extensions. The version number 3329 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 Entries 3339~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3340 3341.. _amdgpu-dwarf-low-level-information: 3342 3343A.3.3.5 Low-Level Information 3344+++++++++++++++++++++++++++++ 3345 33461. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3347 ``DW_TAG_entry_point`` debugger information entry may have a 3348 ``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 that 3351 has a result kind of a location description, an unspecified object, the 3352 compilation unit that contains E, an empty initial stack, and other context 3353 elements corresponding to the source language thread of execution upon which 3354 the user is focused, if any. The result of the evaluation is the location 3355 description L of the place where the return address for the current call 3356 frame's subprogram or entry point is stored. 3357 3358 The DWARF is ill-formed if L is not comprised of one memory location 3359 description for one of the target architecture specific address spaces. 3360 3361 .. note:: 3362 3363 It is unclear why ``DW_TAG_inlined_subroutine`` has a 3364 ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or 3365 ``DW_AT_static_link`` attribute. Seems it would either have all of them or 3366 none. Since inlined subprograms do not have a call frame it seems they 3367 would have none of these attributes. 3368 33692. A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry 3370 may have a ``DW_AT_frame_base`` attribute, whose value is a DWARF expression 3371 E. 3372 3373 The result of the attribute is obtained by evaluating E with a context that 3374 has a result kind of a location description, an unspecified object, the 3375 compilation unit that contains E, an empty initial stack, and other context 3376 elements corresponding to the source language thread of execution upon which 3377 the user is focused, if any. 3378 3379 The DWARF is ill-formed if E contains a ``DW_OP_fbreg`` operation, or the 3380 resulting location description L is not comprised of one single location 3381 description SL. 3382 3383 If SL is a register location description for register R, then L is replaced 3384 with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This 3385 computes the frame base memory location description in the target 3386 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 required 3394 location description directly using ``DW_OP_call_frame_cfa``, 3395 ``DW_OP_breg*``, or ``DW_OP_LLVM_aspace_bregx``. This would also then 3396 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 location 3399 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 a 3404 stack pointer register plus or minus some offset.* 3405 3406 *The frame base for a subprogram is typically an address relative to the 3407 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 all 3412 variables' location descriptions can be simpler ones involving the frame 3413 base.* 3414 3415 2. *It can be used in resolving "up-level" addressing within 3416 nested routines. (See also* ``DW_AT_static_link``\ *, below)* 3417 3418 *Some languages support nested subroutines. In such languages, it is 3419 possible to reference the local variables of an outer subroutine from within 3420 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 information 3424 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 that 3428 has a result kind of a location description, an unspecified object, the 3429 compilation unit that contains E, an empty initial stack, and other context 3430 elements corresponding to the source language thread of execution upon which 3431 the user is focused, if any. The result of the evaluation is the location 3432 description L of the *canonical frame address* (see 3433 :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of 3434 the subprogram instance that immediately lexically encloses the current call 3435 frame's subprogram or entry point. 3436 3437 The DWARF is ill-formed if L is not comprised of one memory location 3438 description for one of the target architecture specific address spaces. 3439 3440 In the context of supporting nested subroutines, the DW_AT_frame_base 3441 attribute value obeys the following constraints: 3442 3443 1. It computes a value that does not change during the life of the 3444 subprogram, and 3445 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's 3449 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 the 3453 lexical parent and the* ``DW_AT_static_link`` *value to identify the 3454 appropriate active frame of the parent. It can then attempt to find the 3455 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, a 3462 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3463 ``DW_TAG_entry_point`` debugger information entry may have a 3464 ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is 3465 the number of source language threads of execution per target architecture 3466 thread. 3467 3468 *For example, a compiler may map source language threads of execution onto 3469 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 target 3472 architecture thread. It is not the dynamic number of source language threads 3473 of execution with which the target architecture thread was initiated, for 3474 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, a 3481 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3482 ``DW_TAG_entry_point`` debugging information entry may have a 3483 ``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 that 3486 has a result kind of a location description, an unspecified object, the 3487 compilation unit that contains E, an empty initial stack, and other context 3488 elements corresponding to the source language thread of execution upon which 3489 the user is focused, if any. 3490 3491 The resulting location description L is for a lane count sized vector of 3492 generic type elements. The lane count is the value of the 3493 ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program 3494 location of the corresponding lane. If the lane was not active when the 3495 current subprogram was called, its element is an undefined location 3496 description. 3497 3498 The DWARF is ill-formed if L does not have exactly one single location 3499 description. 3500 3501 ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where 3502 each SIMT lane of a target architecture thread is positioned even when it is 3503 in divergent control flow that is not active.* 3504 3505 *Typically, the result is a location description with one composite location 3506 description with each part being a location description with either one 3507 undefined location description or one memory location description.* 3508 3509 If not present, the target architecture thread is not being used in a SIMT 3510 manner, and the thread's current program location is used. 3511 35126. For languages that are implemented using a SIMT execution model, a 3513 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3514 ``DW_TAG_entry_point`` debugger information entry may have a 3515 ``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 location 3518 description, an unspecified object, the compilation unit that contains E, an 3519 empty initial stack, and other context elements corresponding to the source 3520 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 location 3523 description SL. 3524 3525 The active lane bit mask V for the current program location is obtained by 3526 reading from SL using a target architecture specific integral base type T 3527 that has a bit size equal to the value of the ``DW_AT_LLVM_lanes`` attribute 3528 of the subprogram corresponding to context's frame and program location. The 3529 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 is 3531 inactive. The result of the attribute is the value V. 3532 3533 *Some targets may update the target architecture execution mask for regions 3534 of code that must execute with different sets of lanes than the current 3535 active lanes. For example, some code must execute with all lanes made 3536 temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to 3537 provide the means to determine the source language active lanes at any 3538 program location. Typically, this attribute will use a loclist to express 3539 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 target 3542 architecture execution mask is used. 3543 35447. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3545 ``DW_TAG_entry_point`` debugger information entry may have a 3546 ``DW_AT_LLVM_iterations`` attribute whose value is an integer constant or a 3547 DWARF expression E. Its value is the number of source language loop 3548 iterations executing concurrently by the target architecture for a single 3549 source language thread of execution. 3550 3551 *A compiler may generate code that executes more than one iteration of a 3552 source language loop concurrently using optimization techniques such as 3553 software pipelining or SIMD vectorization. The number of concurrent 3554 iterations may vary for different loop nests in the same subprogram. 3555 Typically, this attribute will use a loclist to express different values at 3556 different program locations.* 3557 3558 If the attribute is an integer constant, then the value is the constant. The 3559 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 a 3562 location description, an unspecified object, the compilation unit that 3563 contains E, an empty initial stack, and other context elements corresponding 3564 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 description 3566 comprised of one implicit location description, that when read as the 3567 generic type, results in a value V that is less than or equal to 0. The 3568 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 Parameters 3573~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3574 3575A.3.4.2 Call Site Parameters 3576++++++++++++++++++++++++++++ 3577 35781. The call site entry may own ``DW_TAG_call_site_parameter`` debugging 3579 information entries representing the parameters passed to the call. Call 3580 site parameter entries occur in the same order as the corresponding 3581 parameters in the source. Each such entry has a ``DW_AT_location`` attribute 3582 which is a location description. This location description describes where 3583 the parameter is passed (usually either some register, or a memory location 3584 expressible as the contents of the stack register plus some offset). 3585 35862. A ``DW_TAG_call_site_parameter`` debugger information entry may have a 3587 ``DW_AT_call_value`` attribute, whose value is a DWARF operation expression 3588 E\ :sub:`1`\ . 3589 3590 The result of the ``DW_AT_call_value`` attribute is obtained by evaluating 3591 E\ :sub:`1` with a context that has a result kind of a value, an unspecified 3592 object, the compilation unit that contains E, an empty initial stack, and 3593 other context elements corresponding to the source language thread of 3594 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 the 3596 call site. 3597 3598 For parameters passed by reference, where the code passes a pointer to a 3599 location which contains the parameter, or for reference type parameters, the 3600 ``DW_TAG_call_site_parameter`` debugger information entry may also have a 3601 ``DW_AT_call_data_location`` attribute whose value is a DWARF operation 3602 expression E\ :sub:`2`\ , and a ``DW_AT_call_data_value`` attribute whose 3603 value is a DWARF operation expression E\ :sub:`3`\ . 3604 3605 The value of the ``DW_AT_call_data_location`` attribute is obtained by 3606 evaluating E\ :sub:`2` with a context that has a result kind of a location 3607 description, an unspecified object, the compilation unit that contains E, an 3608 empty initial stack, and other context elements corresponding to the source 3609 language thread of execution upon which the user is focused, if any. The 3610 resulting location description L\ :sub:`2` is the location where the 3611 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 the 3613 ``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 used 3618 but does not state what object must be specified in the context. Either 3619 ``DW_OP_push_object_address`` cannot be used, or the object to be passed 3620 in the context must be defined. 3621 3622 The value of the ``DW_AT_call_data_value`` attribute is obtained by 3623 evaluating E\ :sub:`3` with a context that has a result kind of a value, an 3624 unspecified object, the compilation unit that contains E, an empty initial 3625 stack, and other context elements corresponding to the source language 3626 thread of execution upon which the user is focused, if any. The resulting 3627 value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made 3628 by the call site. 3629 3630 The result of these attributes is undefined if the current call frame is not 3631 for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger 3632 information entry or the current program location is not for the call site 3633 containing the ``DW_TAG_call_site_parameter`` debugger information entry in 3634 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 these 3638 attributes. This will ensure the source language thread of execution upon 3639 which the user is focused corresponds to the call site needed to evaluate 3640 the expression.* 3641 3642 If it is not possible to avoid the expressions of these attributes from 3643 accessing registers or memory locations that might be clobbered by the 3644 subprogram being called by the call site, then the associated attribute 3645 should not be provided. 3646 3647 *The reason for the restriction is that the parameter may need to be 3648 accessed during the execution of the callee. The consumer may virtually 3649 unwind from the called subprogram back to the caller and then evaluate the 3650 attribute expressions. The call frame information (see* 3651 :ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore 3652 registers that have been clobbered, and clobbered memory will no longer have 3653 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 or 3658 ``DW_AT_name`` attribute describing the parameter's name. 3659 3660*Examples using call site entries and related attributes are found in Appendix 3661D.15.* 3662 3663.. _amdgpu-dwarf-lexical-block-entries: 3664 3665A.3.5 Lexical Block Entries 3666~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 Entries 3673--------------------------------------- 3674 3675.. note:: 3676 3677 This section provides changes to existing debugger information entry 3678 attributes. These would be incorporated into the corresponding DWARF Version 5 3679 chapter 4 sections. 3680 3681.. _amdgpu-dwarf-data-object-entries: 3682 3683A.4.1 Data Object Entries 3684~~~~~~~~~~~~~~~~~~~~~~~~~ 3685 3686Program variables, formal parameters and constants are represented by debugging 3687information 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 or 3693constant may have the following attributes: 3694 36951. A ``DW_AT_location`` attribute, whose value is a DWARF expression E that 3696 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 that 3699 has a result kind of a location description, an unspecified object, the 3700 compilation unit that contains E, an empty initial stack, and other context 3701 elements corresponding to the source language thread of execution upon which 3702 the user is focused, if any. The result of the evaluation is the location 3703 description of the base of the data object. 3704 3705 See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules 3706 used by the ``DW_OP_call*`` operations. 3707 3708 .. note:: 3709 3710 Delete the description of how the ``DW_OP_call*`` operations evaluate a 3711 ``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 the 3716 ``DW_OP_call*`` operation. Having each attribute only have a single 3717 purpose and single execution semantics seems desirable. It makes it easier 3718 for the consumer that no longer have to track the context. It makes it 3719 easier for the producer as it can rely on a single semantics for each 3720 attribute. 3721 3722 For that reason, limiting the ``DW_AT_location`` attribute to only 3723 supporting evaluating the location description of an object, and using a 3724 different attribute and encoding class for the evaluation of DWARF 3725 expression *procedures* on the same operation expression stack seems 3726 desirable. 3727 37282. ``DW_AT_const_value`` 3729 3730 .. note:: 3731 3732 Could deprecate using the ``DW_AT_const_value`` attribute for 3733 ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information 3734 entries that have been optimized to a constant. Instead, 3735 ``DW_AT_location`` could be used with a DWARF expression that produces an 3736 implicit location description now that any location description can be 3737 used within a DWARF expression. This allows the ``DW_OP_call*`` operations 3738 to be used to push the location description of any variable regardless of 3739 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 source 3744 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 Entries 3749~~~~~~~~~~~~~~~~~~~~~~~~~~ 3750 3751A common block entry also has a ``DW_AT_location`` attribute whose value is a 3752DWARF 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 has 3754a result kind of a location description, an unspecified object, the compilation 3755unit that contains E, an empty initial stack, and other context elements 3756corresponding to the source language thread of execution upon which the user is 3757focused, if any. The result of the evaluation is the location description of the 3758base of the common block. See :ref:`amdgpu-dwarf-control-flow-operations` for 3759special evaluation rules used by the ``DW_OP_call*`` operations. 3760 3761A.5 Type Entries 3762---------------- 3763 3764.. note:: 3765 3766 This section provides changes to existing debugger information entry 3767 attributes. These would be incorporated into the corresponding DWARF Version 5 3768 chapter 5 sections. 3769 3770.. _amdgpu-dwarf-base-type-entries: 3771 3772A.5.1 Base Type Entries 3773~~~~~~~~~~~~~~~~~~~~~~~ 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 have 3780 a ``DW_AT_LLVM_vector_size`` attribute whose value is an integer constant 3781 that is the vector type size N. 3782 3783 The representation of a vector base type is as N contiguous elements, each 3784 one having the representation of a base type T' that is the same as T 3785 without the ``DW_AT_LLVM_vector_size`` attribute. 3786 3787 If a ``DW_TAG_base_type`` debugger information entry does not have a 3788 ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector 3789 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 is 3796 intended to support vector types. However, that was not for a base type so 3797 would not be suitable as the type of a stack value entry. But perhaps that 3798 could be replaced by using this attribute. 3799 3800 .. note:: 3801 3802 Compare this with the ``DW_AT_GNU_vector`` extension supported by GNU. Is 3803 it better to add an attribute to the existing ``DW_TAG_base_type`` debug 3804 entry, or allow some forms of ``DW_TAG_array_type`` (those that have the 3805 ``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 encoding 3808 ``DW_ATE_address`` may have a ``DW_AT_LLVM_address_space`` attribute whose 3809 value is an architecture specific address space (see 3810 :ref:`amdgpu-dwarf-address-spaces`). If omitted it defaults to 3811 ``DW_ASPACE_LLVM_none``. 3812 3813.. _amdgpu-dwarf-type-modifier-entries: 3814 3815A.5.3 Type Modifier Entries 3816~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 (using 3823``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or 3824``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_memory_space`` 3825attribute with a constant value representing a source language specific DWARF 3826memory space (see :ref:`amdgpu-dwarf-memory-spaces`). If omitted, defaults to 3827DW_MSPACE_LLVM_none. 3828 3829A modified type entry describing a pointer or reference type (using 3830``DW_TAG_pointer_type``, ``DW_TAG_reference_type`` or 3831``DW_TAG_rvalue_reference_type``\ ) may have a ``DW_AT_LLVM_address_space`` 3832attribute with a constant value AS representing an architecture specific DWARF 3833address space (see :ref:`amdgpu-dwarf-address-spaces`). If omitted, defaults to 3834``DW_ASPACE_LLVM_none``. DR is the offset of a hypothetical debug information 3835entry D in the current compilation unit for an integral base type matching the 3836address size of AS. An object P having the given pointer or reference type are 3837dereferenced 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 evaluated 3839with the current context except: the result kind is location description; the 3840initial 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 architecture 3845 defined? 3846 3847.. note:: 3848 3849 With the expanded support for DWARF address spaces, it may be worth examining 3850 if they can be used for what was formerly supported by DWARF 5 segments. That 3851 would include specifying the address space of all code addresses (compilation 3852 units, subprograms, subprogram entries, labels, subprogram types, etc.). 3853 Either the code address attributes could be extended to allow a exprloc form 3854 (so that ``DW_OP_form_aspace_address`` can be used) or the 3855 ``DW_AT_LLVM_address_space`` attribute be allowed on all DIEs that allow 3856 ``DW_AT_segment``. 3857 3858A.5.7 Structure, Union, Class and Interface Type Entries 3859~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3860 3861A.5.7.3 Derived or Extended Structures, Classes and Interfaces 3862++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 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 in 3867 bytes from the beginning of the containing entity. 3868 3869 The result of the attribute is obtained by evaluating a 3870 ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the 3871 location description of the beginning of the containing entity. The 3872 result of the evaluation is the location description of the base of the 3873 member entry. 3874 3875 *If the beginning of the containing entity is not byte aligned, then the 3876 beginning of the member entry has the same bit displacement within a 3877 byte.* 3878 3879 2. Otherwise, the attribute must be a DWARF expression E which is evaluated 3880 with a context that has a result kind of a location description, an 3881 unspecified object, the compilation unit that contains E, an initial 3882 stack comprising the location description of the beginning of the 3883 containing entity, and other context elements corresponding to the 3884 source language thread of execution upon which the user is focused, if 3885 any. The result of the evaluation is the location description of the 3886 base of the member entry. 3887 3888 .. note:: 3889 3890 The beginning of the containing entity can now be any location 3891 description, including those with more than one single location 3892 description, and those with single location descriptions that are of any 3893 kind and have any bit offset. 3894 3895A.5.7.8 Member Function Entries 3896+++++++++++++++++++++++++++++++ 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 that 3902 has a result kind of a location description, an unspecified object, the 3903 compilation unit that contains E, an initial stack comprising the location 3904 description of the object of the enclosing type, and other context elements 3905 corresponding to the source language thread of execution upon which the user 3906 is focused, if any. The result of the evaluation is the location description 3907 of the slot for the function within the virtual function table for the 3908 enclosing class. 3909 3910A.5.14 Pointer to Member Type Entries 3911~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3912 39131. The ``DW_TAG_ptr_to_member_type`` debugging information entry has a 3914 ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is 3915 used to compute the location description of the member of the class to which 3916 the pointer to member entry points. 3917 3918 *The method used to find the location description of a given member of a 3919 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. The 3921 method is thus associated with the pointer to member type, rather than with 3922 each object that has a pointer to member type.* 3923 3924 The ``DW_AT_use_location`` DWARF expression is used in conjunction with the 3925 location description for a particular object of the given pointer to member 3926 type and for a particular structure or class instance. 3927 3928 The result of the attribute is obtained by evaluating E with a context that 3929 has a result kind of a location description, an unspecified object, the 3930 compilation unit that contains E, an initial stack comprising two entries, 3931 and other context elements corresponding to the source language thread of 3932 execution upon which the user is focused, if any. The first stack entry is 3933 the value of the pointer to member object itself. The second stack entry is 3934 the location description of the base of the entire class, structure, or 3935 union instance containing the member whose location is being calculated. The 3936 result of the evaluation is the location description of the member of the 3937 class to which the pointer to member entry points. 3938 3939A.5.18 Dynamic Properties of Types 3940~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3941 3942A.5.18.1 Data Location 3943++++++++++++++++++++++ 3944 3945*Some languages may represent objects using descriptors to hold information, 3946including a location and/or run-time parameters, about the data that represents 3947the value for that object.* 3948 39491. The ``DW_AT_data_location`` attribute may be used with any type that 3950 provides one or more levels of hidden indirection and/or run-time parameters 3951 in its representation. Its value is a DWARF operation expression E which 3952 computes the location description of the data for an object. When this 3953 attribute is omitted, the location description of the data is the same as 3954 the location description of the object. 3955 3956 The result of the attribute is obtained by evaluating E with a context that 3957 has a result kind of a location description, an object that is the location 3958 description of the data descriptor, the compilation unit that contains E, an 3959 empty initial stack, and other context elements corresponding to the source 3960 language thread of execution upon which the user is focused, if any. The 3961 result of the evaluation is the location description of the base of the 3962 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 location 3966 description of the object which can then serve as a descriptor in subsequent 3967 calculation.* 3968 3969 .. note:: 3970 3971 Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and 3972 ``DW_AT_vtable_elem_location`` allow both operation expressions and 3973 location list expressions, why does ``DW_AT_data_location`` not allow 3974 both? In all cases they apply to data objects so less likely that 3975 optimization would cause different operation expressions for different 3976 program location ranges. But if supporting for some then should be for 3977 all. 3978 3979 It seems odd this attribute is not the same as 3980 ``DW_AT_data_member_location`` in having an initial stack with the 3981 location description of the object since the expression has to need it. 3982 3983A.6 Other Debugging Information 3984------------------------------- 3985 3986.. note:: 3987 3988 This section provides changes to existing debugger information entry 3989 attributes. These would be incorporated into the corresponding DWARF Version 5 3990 chapter 6 sections. 3991 3992A.6.1 Accelerated Access 3993~~~~~~~~~~~~~~~~~~~~~~~~ 3994 3995.. _amdgpu-dwarf-lookup-by-name: 3996 3997A.6.1.1 Lookup By Name 3998++++++++++++++++++++++ 3999 4000A.6.1.1.1 Contents of the Name Index 4001#################################### 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 the 4008 optional ``.debug_names`` section is extended to also include named 4009 ``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 that 4013defines a named subprogram, label, variable, type, or namespace, subject to the 4014following 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 are 4019 excluded. 4020 4021A.6.1.1.4 Data Representation of the Name Index 4022############################################### 4023 4024.. _amdgpu-dwarf-name-index-section-header: 4025 4026 4027A.6.1.1.4.1 Section Header 4028^^^^^^^^^^^^^^^^^^^^^^^^^^ 4029 4030.. note:: 4031 4032 The following provides an addition to DWARF Version 5 section 6.1.1.4.1 item 4033 14 ``augmentation_string``. 4034 4035A null-terminated UTF-8 vendor specific augmentation string, which provides 4036additional information about the contents of this index. If provided, the 4037recommended 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 Y 4042version number of the extensions used in the DWARF of the compilation unit, and 4043*options* is an optional string providing additional information about the 4044extensions. The version number must conform to semantic versioning [:ref:`SEMVER 4045<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 with 4057 the other augmentation strings and allows multiple vendor extensions to be 4058 supported. 4059 4060.. _amdgpu-dwarf-line-number-information: 4061 4062A.6.2 Line Number Information 4063~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4064 4065A.6.2.4 The Line Number Program Header 4066++++++++++++++++++++++++++++++++++++++ 4067 4068A.6.2.4.1 Standard Content Descriptions 4069####################################### 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 as 4081 ``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. If 4084 the source is available but is an empty file then the value is a 4085 null-terminated single "\ ``\n``\ ". 4086 4087 *When the source field is present, consumers can use the embedded source 4088 instead of attempting to discover the source on disk using the file path 4089 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 runtime 4093 compilation and runtime generation of source text. In these cases, the 4094 source text does not reside in any permanent file. For example, the OpenCL 4095 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, if 4100 present, is valid: when 0 it is not valid and when 1 it is valid. If 4101 ``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 without 4107 MD5 checksums. This can happen when multiple relocatable files are linked 4108 together.* 4109 4110.. _amdgpu-dwarf-call-frame-information: 4111 4112A.6.4 Call Frame Information 4113~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4114 4115.. note:: 4116 4117 This section provides changes to existing call frame information and defines 4118 instructions added by these extensions. Additional support is added for 4119 address spaces. Register unwind DWARF expressions are generalized to allow any 4120 location description, including those with composite and implicit location 4121 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 Information 4128+++++++++++++++++++++++++++++++++++++++++++ 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 (see 4135 :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 this 4143 register is the location description L that specifies one register location 4144 description SL. SL specifies the register location storage that corresponds to 4145 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 this 4148 register is the location description obtained using the call frame information 4149 for the callee frame and callee program location invoked by the current caller 4150 frame for the same register. 4151 4152 *By convention, the register is preserved by the callee, but the callee has 4153 not modified it.* 4154 4155*offset(N)* 4156 N is a signed byte offset. The previous value of this register is saved at the 4157 location description computed as if the DWARF operation expression 4158 ``DW_OP_LLVM_offset N`` is evaluated with the current context, except the 4159 result kind is a location description, the compilation unit is unspecified, 4160 the object is unspecified, and an initial stack comprising the location 4161 description of the current CFA (see 4162 :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 memory 4166 byte address of the location description computed as if the DWARF operation 4167 expression ``DW_OP_LLVM_offset N`` is evaluated with the current context, 4168 except the result kind is a location description, the compilation unit is 4169 unspecified, the object is unspecified, and an initial stack comprising the 4170 location description of the current CFA (see 4171 :ref:`amdgpu-dwarf-operation-expressions`). 4172 4173 The DWARF is ill-formed if the CFA location description is not a memory byte 4174 address location description, or if the register size does not match the size 4175 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 address 4178 location description, the value of val_offset(N) will also be a memory byte 4179 address location description since it is offsetting the CFA location 4180 description by N bytes. Furthermore, the value of val_offset(N) will be a 4181 memory byte address in the same address space as the CFA location 4182 description.* 4183 4184 .. note:: 4185 4186 Should DWARF allow the address size to be a different size to the size of 4187 the register? Requiring them to be the same bit size avoids any issue of 4188 conversion as the bit contents of the register is simply interpreted as a 4189 value of the address. 4190 4191 GDB has a per register hook that allows a target specific conversion on a 4192 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 bounds 4194 for the last register) for smaller registers. There are no GDB tests that 4195 read a register out of bounds (except an illegal hand written assembly 4196 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 using 4202 the call frame information for the current frame and current program location 4203 for register R. 4204 4205 The DWARF is ill-formed if the size of this register does not match the size 4206 of register R or if there is a cyclic dependency in the call frame 4207 information. 4208 4209 .. note:: 4210 4211 Should this also allow R to be larger than this register? If so is the value 4212 stored in the low order bits and it is undefined what is stored in the 4213 extra upper bits? 4214 4215*expression(E)* 4216 The previous value of this register is located at the location description 4217 produced by evaluating the DWARF operation expression E (see 4218 :ref:`amdgpu-dwarf-operation-expressions`). 4219 4220 E is evaluated with the current context, except the result kind is a location 4221 description, the compilation unit is unspecified, the object is unspecified, 4222 and an initial stack comprising the location description of the current CFA 4223 (see :ref:`amdgpu-dwarf-operation-expressions`). 4224 4225*val_expression(E)* 4226 The previous value of this register is located at the implicit location 4227 description created from the value produced by evaluating the DWARF operation 4228 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 initial 4232 stack comprising the location description of the current CFA (see 4233 :ref:`amdgpu-dwarf-operation-expressions`). 4234 4235 The DWARF is ill-formed if the resulting value type size does not match the 4236 register size. 4237 4238 .. note:: 4239 4240 This has limited usefulness as the DWARF expression E can only produce 4241 values up to the size of the generic type. This is due to not allowing any 4242 operations that specify a type in a CFI operation expression. This makes it 4243 unusable for registers that are larger than the generic type. However, 4244 *expression(E)* can be used to create an implicit location description of 4245 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. Most 4251of 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 the 4253differences starting at the beginning address of each subroutine in the 4254program.* 4255 4256The virtual unwind information is encoded in a self-contained section called 4257``.debug_frame``. Entries in a ``.debug_frame`` section are aligned on a 4258multiple of the address size relative to the start of the section and come in 4259two 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 be 4262multiple CIEs and FDEs corresponding to the parts of that function.* 4263 4264A Common Information Entry (CIE) holds information that is shared among many 4265Frame Description Entries (FDE). There is at least one CIE in every non-empty 4266``.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, not 4271 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 integral 4273 multiple of the address size specified in the ``address_size`` field. 4274 42752. ``CIE_id`` (4 or 8 bytes, see 4276 :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 is 4281 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 is 4286 specific to the call frame information and is independent of the DWARF 4287 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 CIE 4298 or to the FDEs that use it. If a reader encounters an augmentation string 4299 that is unexpected, then only the following fields can be read: 4300 4301 * CIE: length, CIE_id, version, augmentation 4302 * FDE: length, CIE_pointer, initial_location, address_range 4303 4304 If there is no augmentation, this value is a zero byte. 4305 4306 *The augmentation string allows users to indicate that there is additional 4307 vendor and target architecture specific information in the CIE or FDE which 4308 is needed to virtually unwind a stack frame. For example, this might be 4309 information about dynamically allocated data which needs to be freed on exit 4310 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-8 4314 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 Y 4321 version number of the extensions used, and *options* is an optional string 4322 providing additional information about the extensions. The version number 4323 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 the 4336 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, in 4341 bytes. 4342 43437. ``code_alignment_factor`` (unsigned LEB128) 4344 4345 A constant that is factored out of all advance location instructions (see 4346 :ref:`amdgpu-dwarf-row-creation-instructions`). The resulting value is 4347 ``(operand * code_alignment_factor)``. 4348 43498. ``data_alignment_factor`` (signed LEB128) 4350 4351 A constant that is factored out of certain offset instructions (see 4352 :ref:`amdgpu-dwarf-cfa-definition-instructions` and 4353 :ref:`amdgpu-dwarf-register-rule-instructions`). The resulting value is 4354 ``(operand * data_alignment_factor)``. 4355 43569. ``return_address_register`` (unsigned LEB128) 4357 4358 An unsigned LEB128 constant that indicates which column in the rule table 4359 represents the return address of the subprogram. Note that this column might 4360 not correspond to an actual machine register. 4361 4362 The value of the return address register is used to determine the program 4363 location of the caller frame. The program location of the top frame is the 4364 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 of 4369 each column in the table. 4370 4371 The default rule for all columns before interpretation of the initial 4372 instructions is the undefined rule. However, an ABI authoring body or a 4373 compilation system authoring body may specify an alternate default value for 4374 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 the 4379 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 instruction 4386 stream for this subprogram, not including the length field itself (see 4387 Section 7.2.2 Initial Length Values). The size of the length field plus the 4388 value of length must be an integral multiple of the address size. 4389 43902. ``CIE_pointer`` (4 or 8 bytes, see 4391 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`) 4392 4393 A constant offset into the ``.debug_frame`` section that denotes the CIE 4394 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 the 4399 segment_selector_size field of this FDE’s CIE is non-zero, the initial 4400 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 in 4409 :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 the 4414 length value above. 4415 4416.. _amdgpu-dwarf-call-frame-instructions: 4417 4418A.6.4.2 Call Frame Instructions 4419+++++++++++++++++++++++++++++++ 4420 4421Each call frame instruction is defined to take 0 or more operands. Some of the 4422operands may be encoded as part of the opcode (see 4423:ref:`amdgpu-dwarf-call-frame-information-encoding`). The instructions are 4424defined in the following sections. 4425 4426Some call frame instructions have operands that are encoded as DWARF operation 4427expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF 4428operations 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 depend 4435 on other debug sections. 4436 4437* ``DW_OP_push_object_address`` is not allowed because there is no object 4438 context to provide a value to push. 4439 4440* ``DW_OP_LLVM_push_lane`` and ``DW_OP_LLVM_push_iteration`` are not allowed 4441 because the call frame instructions describe the actions for the whole target 4442 architecture thread, not the lanes or iterations independently. 4443 4444* ``DW_OP_call_frame_cfa`` and ``DW_OP_entry_value`` are not allowed because 4445 their use would be circular. 4446 4447* ``DW_OP_LLVM_call_frame_entry_reg`` is not allowed if evaluating E causes a 4448 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`` *operation 4452 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 Instructions 4463################################### 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 Instructions 4472##################################### 4473 44741. ``DW_CFA_def_cfa`` 4475 4476 The ``DW_CFA_def_cfa`` instruction takes two unsigned LEB128 operands 4477 representing a register number R and a (non-factored) byte displacement B. 4478 AS is set to the target architecture default address space identifier. The 4479 required action is to define the current CFA rule to be equivalent to the 4480 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 LEB128 4486 value representing a register number R and a signed LEB128 factored byte 4487 displacement B. AS is set to the target architecture default address space 4488 identifier. The required action is to define the current CFA rule to be 4489 equivalent to the result of evaluating the DWARF operation expression 4490 ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B * data_alignment_factor`` as 4491 a location description. 4492 4493 *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second 4494 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 LEB128 4499 operands representing a register number R, a (non-factored) byte 4500 displacement B, and a target architecture specific address space identifier 4501 AS. The required action is to define the current CFA rule to be equivalent 4502 to the result of evaluating the DWARF operation expression ``DW_OP_constu 4503 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 specific 4506 ``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: an 4511 unsigned LEB128 value representing a register number R, a signed LEB128 4512 factored byte displacement B, and an unsigned LEB128 value representing a 4513 target architecture specific address space identifier AS. The required 4514 action is to define the current CFA rule to be equivalent to the result of 4515 evaluating the DWARF operation expression ``DW_OP_constu AS; 4516 DW_OP_LLVM_aspace_bregx R, B * data_alignment_factor`` as a location 4517 description. 4518 4519 If AS is not one of the values defined by the target architecture specific 4520 ``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 the 4523 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 LEB128 4528 operand representing a register number R. The required action is to define 4529 the current CFA rule to be equivalent to the result of evaluating the DWARF 4530 operation expression ``DW_OP_constu AS; DW_OP_LLVM_aspace_bregx R, B`` as a 4531 location description. B and AS are the old CFA byte displacement and address 4532 space respectively. 4533 4534 If the subprogram has no current CFA rule, or the rule was defined by a 4535 ``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 LEB128 4540 operand representing a (non-factored) byte displacement B. The required 4541 action is to define the current CFA rule to be equivalent to the result of 4542 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 the 4544 old CFA register number and address space respectively. 4545 4546 If the subprogram has no current CFA rule, or the rule was defined by a 4547 ``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 operand 4552 representing a factored byte displacement B. The required action is to 4553 define the current CFA rule to be equivalent to the result of evaluating the 4554 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 CFA 4556 register number and address space respectively. 4557 4558 If the subprogram has no current CFA rule, or the rule was defined by a 4559 ``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 the 4562 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 encoded 4567 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 to 4569 the result of evaluating E with the current context, except the result kind 4570 is a location description, the compilation unit is unspecified, the object 4571 is unspecified, and an empty initial stack. 4572 4573 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on 4574 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 byte 4577 address location description. 4578 4579.. _amdgpu-dwarf-register-rule-instructions: 4580 4581A.6.4.2.3 Register Rule Instructions 4582#################################### 4583 45841. ``DW_CFA_undefined`` 4585 4586 The ``DW_CFA_undefined`` instruction takes a single unsigned LEB128 operand 4587 that represents a register number R. The required action is to set the rule 4588 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 operand 4593 that represents a register number R. The required action is to set the rule 4594 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 R 4599 (encoded with the opcode) and an unsigned LEB128 constant representing a 4600 factored displacement B. The required action is to change the rule for the 4601 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 is 4606 unsigned factored. 4607 46084. ``DW_CFA_offset_extended`` 4609 4610 The ``DW_CFA_offset_extended`` instruction takes two unsigned LEB128 4611 operands representing a register number R and a factored displacement B. 4612 This instruction is identical to ``DW_CFA_offset``, except for the encoding 4613 and size of the register operand. 4614 4615 .. note:: 4616 4617 Seems this should be named ``DW_CFA_offset_extended_uf`` since the 4618 displacement is unsigned factored. 4619 46205. ``DW_CFA_offset_extended_sf`` 4621 4622 The ``DW_CFA_offset_extended_sf`` instruction takes two operands: an 4623 unsigned LEB128 value representing a register number R and a signed LEB128 4624 factored displacement B. This instruction is identical to 4625 ``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 operands 4630 representing a register number R and a factored displacement B. The required 4631 action is to change the rule for the register indicated by R to be a 4632 *val_offset(B \* data_alignment_factor)* rule. 4633 4634 .. note:: 4635 4636 Seems this should be named ``DW_CFA_val_offset_uf`` since the displacement 4637 is unsigned factored. 4638 4639 .. note:: 4640 4641 An alternative is to define ``DW_CFA_val_offset`` to implicitly use the 4642 target architecture default address space, and add another operation that 4643 specifies the address space. 4644 46457. ``DW_CFA_val_offset_sf`` 4646 4647 The ``DW_CFA_val_offset_sf`` instruction takes two operands: an unsigned 4648 LEB128 value representing a register number R and a signed LEB128 factored 4649 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 operands 4655 representing register numbers R1 and R2 respectively. The required action is 4656 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 LEB128 4661 value representing a register number R, and a ``DW_FORM_block`` value 4662 representing a DWARF operation expression E. The required action is to 4663 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 can 4667 be retrieved.* 4668 4669 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on 4670 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 unsigned 4675 LEB128 value representing a register number R, and a ``DW_FORM_block`` value 4676 representing a DWARF operation expression E. The required action is to 4677 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 on 4683 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 that 4686 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 the 4691 opcode) that represents a register number R. The required action is to 4692 change the rule for the register specified by R to the rule assigned it by 4693 the ``initial_instructions`` in the CIE. 4694 469512. ``DW_CFA_restore_extended`` 4696 4697 The ``DW_CFA_restore_extended`` instruction takes a single unsigned LEB128 4698 operand that represents a register number R. This instruction is identical 4699 to ``DW_CFA_restore``, except for the encoding and size of the register 4700 operand. 4701 4702A.6.4.2.4 Row State Instructions 4703################################ 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 Instruction 4710############################# 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 Usage 4717++++++++++++++++++++++++++++++++++++ 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 Address 4726++++++++++++++++++++++++++++++++++ 4727 4728.. note:: 4729 4730 The same as in DWARF Version 5 section 6.4.4. 4731 4732A.7 Data Representation 4733----------------------- 4734 4735.. note:: 4736 4737 This section provides changes to existing debugger information entry 4738 attributes. These would be incorporated into the corresponding DWARF Version 5 4739 chapter 7 sections. 4740 4741.. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats: 4742 4743A.7.4 32-Bit and 64-Bit DWARF Formats 4744~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 roles 4751 :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table 4752 4753 ================================== =================================== 4754 Form Role 4755 ================================== =================================== 4756 DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info`` 4757 ================================== =================================== 4758 4759A.7.5 Format of Debugging Information 4760~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4761 4762A.7.5.4 Attribute Encodings 4763+++++++++++++++++++++++++++ 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 information 4770entry attributes. 4771 4772.. table:: Attribute encodings 4773 :name: amdgpu-dwarf-attribute-encodings-table 4774 4775 ================================== ====== =================================== 4776 Attribute Name Value Classes 4777 ================================== ====== =================================== 4778 ``DW_AT_LLVM_active_lane`` 0x3e08 exprloc, loclist 4779 ``DW_AT_LLVM_augmentation`` 0x3e09 string 4780 ``DW_AT_LLVM_lanes`` 0x3e0a constant 4781 ``DW_AT_LLVM_lane_pc`` 0x3e0b exprloc, loclist 4782 ``DW_AT_LLVM_vector_size`` 0x3e0c constant 4783 ``DW_AT_LLVM_iterations`` 0x3e0a constant, exprloc, loclist 4784 ``DW_AT_LLVM_address_space`` TBA constant 4785 ``DW_AT_LLVM_memory_space`` TBA constant 4786 ================================== ====== =================================== 4787 4788.. _amdgpu-dwarf-classes-and-forms: 4789 4790A.7.5.5 Classes and Forms 4791+++++++++++++++++++++++++ 4792 4793.. note:: 4794 4795 The following modifies the matching text in DWARF Version 5 section 7.5.5. 4796 4797* reference 4798 There are four types of reference. 4799 4800 - The first type of reference... 4801 4802 - The second type of reference can identify any debugging information 4803 entry within a .debug_info section; in particular, it may refer to an 4804 entry in a different compilation unit from the unit containing the 4805 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 the 4807 beginning of the .debug_info section of the target executable or shared 4808 object file, or, for references within a supplementary object file, an 4809 offset from the beginning of the local .debug_info section; it is 4810 relocatable in a relocatable object file and frequently relocated in an 4811 executable or shared object file. In the 32-bit DWARF format, this 4812 offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an 4813 8-byte unsigned value (see 4814 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`). 4815 4816 *A debugging information entry that may be referenced by another 4817 compilation unit using DW_FORM_ref_addr must have a global symbolic 4818 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 or 4822 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 the 4824 debug information is first read, or when the reference is used.* 4825 4826A.7.7 DWARF Expressions 4827~~~~~~~~~~~~~~~~~~~~~~~ 4828 4829.. note:: 4830 4831 Rename DWARF Version 5 section 7.7 to reflect the unification of location 4832 descriptions into DWARF expressions. 4833 4834A.7.7.1 Operation Expressions 4835+++++++++++++++++++++++++++++ 4836 4837.. note:: 4838 4839 Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect the 4840 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 new 4843 table describing vendor extension operations for ``DW_OP_LLVM_user``. 4844 4845A DWARF operation expression is stored in a block of contiguous bytes. The bytes 4846form a sequence of operations. Each operation is a 1-byte code that identifies 4847that operation, followed by zero or more bytes of additional data. The encoding 4848for the operation ``DW_OP_LLVM_user`` is described in 4849:ref:`amdgpu-dwarf-operation-encodings-table`, and the encoding of all 4850``DW_OP_LLVM_user`` vendor extensions operations are described in 4851:ref:`amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table`. 4852 4853.. table:: DWARF Operation Encodings 4854 :name: amdgpu-dwarf-operation-encodings-table 4855 4856 ====================================== ===== ======== ========================================================================================= 4857 Operation Code Number Notes 4858 of 4859 Operands 4860 ====================================== ===== ======== ========================================================================================= 4861 ``DW_OP_LLVM_user`` 0xe9 1+ ULEB128 vendor extension opcode, followed by vendor extension operands 4862 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 Encodings 4866 :name: amdgpu-dwarf-dw-op-llvm-user-vendor-extension-operation-encodings-table 4867 4868 ====================================== ========= ========== =============================== 4869 Operation Vendor Number Notes 4870 Extension of 4871 Opcode Additional 4872 Operands 4873 ====================================== ========= ========== =============================== 4874 ``DW_OP_LLVM_form_aspace_address`` 0x02 0 4875 ``DW_OP_LLVM_push_lane`` 0x03 0 4876 ``DW_OP_LLVM_offset`` 0x04 0 4877 ``DW_OP_LLVM_offset_uconst`` 0x05 1 ULEB128 byte displacement 4878 ``DW_OP_LLVM_bit_offset`` 0x06 0 4879 ``DW_OP_LLVM_call_frame_entry_reg`` 0x07 1 ULEB128 register number 4880 ``DW_OP_LLVM_undefined`` 0x08 0 4881 ``DW_OP_LLVM_aspace_bregx`` 0x09 2 ULEB128 register number, 4882 SLEB128 byte displacement 4883 ``DW_OP_LLVM_piece_end`` 0x0a 0 4884 ``DW_OP_LLVM_extend`` 0x0b 2 ULEB128 bit size, 4885 ULEB128 count 4886 ``DW_OP_LLVM_select_bit_piece`` 0x0c 2 ULEB128 bit size, 4887 ULEB128 count 4888 ``DW_OP_LLVM_aspace_implicit_pointer`` TBA 2 4-byte or 8-byte offset of DIE, 4889 SLEB128 byte displacement 4890 ``DW_OP_LLVM_push_iteration`` TBA 0 4891 ``DW_OP_LLVM_overlay`` TBA 0 4892 ``DW_OP_LLVM_bit_overlay`` TBA 0 4893 ====================================== ========= ========== =============================== 4894 4895A.7.7.3 Location List Expressions 4896+++++++++++++++++++++++++++++++++ 4897 4898.. note:: 4899 4900 Rename DWARF Version 5 section 7.7.3 to reflect that location lists are a kind 4901 of DWARF expression. 4902 4903A.7.12 Source Languages 4904~~~~~~~~~~~~~~~~~~~~~~~ 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 encodings 4913 :name: amdgpu-dwarf-language-encodings-table 4914 4915 ==================== ====== =================== 4916 Language Name Value Default Lower Bound 4917 ==================== ====== =================== 4918 ``DW_LANG_LLVM_HIP`` 0x8100 0 4919 ==================== ====== =================== 4920 4921A.7.14 Address Space Encodings 4922~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4923 4924.. note:: 4925 4926 This is a new section after DWARF Version 5 section 7.13 "Address Class and 4927 Address Space Encodings". 4928 4929The value of the common address space encoding ``DW_ASPACE_LLVM_none`` is 0. 4930 4931A.7.15 Memory Space Encodings 4932~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4933 4934.. note:: 4935 4936 This is a new section after DWARF Version 5 section 7.13 "Address Class and 4937 Address Space Encodings". 4938 4939The encodings of the constants used for the currently defined memory spaces 4940are given in :ref:`amdgpu-dwarf-memory-space-encodings-table`. 4941 4942.. table:: Memory space encodings 4943 :name: amdgpu-dwarf-memory-space-encodings-table 4944 4945 =========================== ====== 4946 Memory Space Name Value 4947 =========================== ====== 4948 ``DW_MSPACE_LLVM_none`` 0x0000 4949 ``DW_MSPACE_LLVM_global`` 0x0001 4950 ``DW_MSPACE_LLVM_constant`` 0x0002 4951 ``DW_MSPACE_LLVM_group`` 0x0003 4952 ``DW_MSPACE_LLVM_private`` 0x0004 4953 ``DW_MSPACE_LLVM_lo_user`` 0x8000 4954 ``DW_MSPACE_LLVM_hi_user`` 0xffff 4955 =========================== ====== 4956 4957A.7.22 Line Number Information 4958~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 header 4965entry formats. 4966 4967.. table:: Line number header entry format encodings 4968 :name: amdgpu-dwarf-line-number-header-entry-format-encodings-table 4969 4970 ==================================== ==================== 4971 Line number header entry format name Value 4972 ==================================== ==================== 4973 ``DW_LNCT_LLVM_source`` 0x2001 4974 ``DW_LNCT_LLVM_is_MD5`` 0x2002 4975 ==================================== ==================== 4976 4977.. _amdgpu-dwarf-call-frame-information-encoding: 4978 4979A.7.24 Call Frame Information 4980~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 information 4987instructions. 4988 4989.. table:: Call frame instruction encodings 4990 :name: amdgpu-dwarf-call-frame-instruction-encodings-table 4991 4992 ================================= ====== ====== ================ ================ ===================== 4993 Instruction High 2 Low 6 Operand 1 Operand 2 Operand 3 4994 Bits Bits 4995 ================================= ====== ====== ================ ================ ===================== 4996 ``DW_CFA_LLVM_def_aspace_cfa`` 0 0x30 ULEB128 register ULEB128 offset ULEB128 address space 4997 ``DW_CFA_LLVM_def_aspace_cfa_sf`` 0 0x31 ULEB128 register SLEB128 offset ULEB128 address space 4998 ================================= ====== ====== ================ ================ ===================== 4999 5000A.7.32 Type Signature Computation 5001~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5002 5003.. note:: 5004 5005 This augments (in alphabetical order) DWARF Version 5 section 7.32, Table 5006 7.32. 5007 5008.. table:: Attributes used in type signature computation 5009 :name: amdgpu-dwarf-attributes-used-in-type-signature-computation-table 5010 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 to 5025debugger information entries. 5026 5027.. table:: Attributes by tag value 5028 :name: amdgpu-dwarf-attributes-by-tag-value-table 5029 5030 ================================== ============================= 5031 Tag Name Applicable Attributes 5032 ================================== ============================= 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 Examples 5066~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5067 5068D.1.3 DWARF Location Description Examples 5069+++++++++++++++++++++++++++++++++++++++++ 5070 5071``DW_OP_offset_uconst 4`` 5072 A structure member is four bytes from the start of the structure instance. The 5073 location description of the base of the structure instance is assumed to be 5074 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 value 5078 contained in register 5 upon entering the current subprogram. 5079 5080D.2 Aggregate Examples 5081~~~~~~~~~~~~~~~~~~~~~~ 5082 5083D.2.1 Fortran Simple Array Example 5084++++++++++++++++++++++++++++++++++ 5085 5086Figure D.4: Fortran array example: DWARF description 5087 5088.. code:: 5089 :number-lines: 5090 5091 ------------------------------------------------------------------------------- 5092 ! Description for type of 'ap' 5093 ! 5094 1$: DW_TAG_array_type 5095 ! No name, default (Fortran) ordering, default stride 5096 DW_AT_type(reference to REAL) 5097 DW_AT_associated(expression= ! Test 'ptr_assoc' flag 5098 DW_OP_push_object_address 5099 DW_OP_lit<n> ! where n == offset(ptr_assoc) 5100 DW_OP_offset 5101 DW_OP_deref 5102 DW_OP_lit1 ! mask for 'ptr_assoc' flag 5103 DW_OP_and) 5104 DW_AT_data_location(expression= ! Get raw data address 5105 DW_OP_push_object_address 5106 DW_OP_lit<n> ! where n == offset(base) 5107 DW_OP_offset 5108 DW_OP_deref) ! Type of index of array 'ap' 5109 2$: DW_TAG_subrange_type 5110 ! No name, default stride 5111 DW_AT_type(reference to INTEGER) 5112 DW_AT_lower_bound(expression= 5113 DW_OP_push_object_address 5114 DW_OP_lit<n> ! where n == 5115 ! offset(desc, dims) + 5116 ! offset(dims_str, lower_bound) 5117 DW_OP_offset 5118 DW_OP_deref) 5119 DW_AT_upper_bound(expression= 5120 DW_OP_push_object_address 5121 DW_OP_lit<n> ! where n == 5122 ! offset(desc, dims) + 5123 ! offset(dims_str, upper_bound) 5124 DW_OP_offset 5125 DW_OP_deref) 5126 ! Note: for the m'th dimension, the second operator becomes 5127 ! DW_OP_lit<n> where 5128 ! 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 successive 5132 ! dimension (other than to express the larger offsets involved). 5133 3$: DW_TAG_structure_type 5134 DW_AT_name("array_ptr") 5135 DW_AT_byte_size(constant sizeof(REAL) + sizeof(desc<1>)) 5136 4$: DW_TAG_member 5137 DW_AT_name("myvar") 5138 DW_AT_type(reference to REAL) 5139 DW_AT_data_member_location(constant 0) 5140 5$: DW_TAG_member 5141 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_type 5145 ! No name, default (Fortran) ordering, default stride 5146 DW_AT_type(reference to 3$) 5147 DW_AT_allocated(expression= ! Test 'ptr_alloc' flag 5148 DW_OP_push_object_address 5149 DW_OP_lit<n> ! where n == offset(ptr_alloc) 5150 DW_OP_offset 5151 DW_OP_deref 5152 DW_OP_lit2 ! Mask for 'ptr_alloc' flag 5153 DW_OP_and) 5154 DW_AT_data_location(expression= ! Get raw data address 5155 DW_OP_push_object_address 5156 DW_OP_lit<n> ! where n == offset(base) 5157 DW_OP_offset 5158 DW_OP_deref) 5159 7$: DW_TAG_subrange_type 5160 ! No name, default stride 5161 DW_AT_type(reference to INTEGER) 5162 DW_AT_lower_bound(expression= 5163 DW_OP_push_object_address 5164 DW_OP_lit<n> ! where n == ... 5165 DW_OP_offset 5166 DW_OP_deref) 5167 DW_AT_upper_bound(expression= 5168 DW_OP_push_object_address 5169 DW_OP_lit<n> ! where n == ... 5170 DW_OP_offset 5171 DW_OP_deref) 5172 8$: DW_TAG_variable 5173 DW_AT_name("arrayvar") 5174 DW_AT_type(reference to 6$) 5175 DW_AT_location(expression= 5176 ...as appropriate...) ! Assume static allocation 5177 ------------------------------------------------------------------------------- 5178 5179D.2.3 Fortran 2008 Assumed-rank Array Example 5180+++++++++++++++++++++++++++++++++++++++++++++ 5181 5182Figure D.13: Sample DWARF for the array descriptor in Figure D.12 5183 5184.. code:: 5185 :number-lines: 5186 5187 ---------------------------------------------------------------------------- 5188 10$: DW_TAG_array_type 5189 DW_AT_type(reference to real) 5190 DW_AT_rank(expression= 5191 DW_OP_push_object_address 5192 DW_OP_lit<n> 5193 DW_OP_offset 5194 DW_OP_deref) 5195 DW_AT_data_location(expression= 5196 DW_OP_push_object_address 5197 DW_OP_lit<n> 5198 DW_OP_offset 5199 DW_OP_deref) 5200 11$: DW_TAG_generic_subrange 5201 DW_AT_type(reference to integer) 5202 ! offset of rank in descriptor 5203 ! offset of data in descriptor 5204 DW_AT_lower_bound(expression= 5205 ! Looks up the lower bound of dimension i. 5206 ! Operation ! Stack effect 5207 ! (implicit) ! i 5208 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]+offset 5212 DW_OP_push_object_address ! dim[i]+offsetof(dim) objptr 5213 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].lowerbound 5217 DW_OP_deref) ! *objptr.dim[i].lowerbound 5218 DW_AT_upper_bound(expression= 5219 ! Looks up the upper bound of dimension i. 5220 DW_OP_lit<n> ! sizeof(dim) 5221 DW_OP_mul 5222 DW_OP_lit<n> ! offsetof(dim) 5223 DW_OP_plus 5224 DW_OP_push_object_address 5225 DW_OP_swap 5226 DW_OP_offset 5227 DW_OP_lit<n> ! offset of upperbound in dim 5228 DW_OP_offset 5229 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. The 5241 attribute definition should be updated to state this. 5242 5243D.2.6 Ada Example 5244+++++++++++++++++ 5245 5246Figure D.20: Ada example: DWARF description 5247 5248.. code:: 5249 :number-lines: 5250 5251 ---------------------------------------------------------------------------- 5252 11$: DW_TAG_variable 5253 DW_AT_name("M") 5254 DW_AT_type(reference to INTEGER) 5255 12$: DW_TAG_array_type 5256 ! No name, default (Ada) order, default stride 5257 DW_AT_type(reference to INTEGER) 5258 13$: DW_TAG_subrange_type 5259 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_variable 5263 DW_AT_name("VEC1") 5264 DW_AT_type(reference to array type at 12$) 5265 ... 5266 21$: DW_TAG_subrange_type 5267 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_type 5273 DW_AT_name("REC2") 5274 27$: DW_TAG_member 5275 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_type 5279 ! No name, default (Ada) order, default stride 5280 ! Default data location 5281 DW_AT_type(reference to INTEGER) 5282 29$: DW_TAG_subrange_type 5283 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_member 5287 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_variable 5294 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 Examples 5302=================== 5303 5304The AMD GPU specific usage of the features in these extensions, including 5305examples, is available at *User Guide for AMDGPU Backend* section 5306:ref:`amdgpu-dwarf-debug-information`. 5307 5308.. note:: 5309 5310 Change examples to use ``DW_OP_LLVM_offset`` instead of ``DW_OP_add`` when 5311 acting on a location description. 5312 5313 Need to provide examples of new features. 5314 5315.. _amdgpu-dwarf-references: 5316 5317D. References 5318============= 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-Developer-Tools/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