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-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 631. 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 compliment 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 246See ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and 247``DW_OP_LLVM_bit_offset`` in 248:ref:`amdgpu-dwarf-general-location-description-operations`. 249 2502.5 Generalize Creation of Undefined Location Descriptions 251---------------------------------------------------------- 252 253Current DWARF uses an empty expression to indicate an undefined location 254description. Since 255:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` 256allows location descriptions to be created on the stack, it is necessary to have 257an explicit way to specify an undefined location description. 258 259For example, the ``DW_OP_LLVM_select_bit_piece`` (see 260:ref:`amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware`) 261operation takes more than one location description on the stack. Without this 262ability, it is not possible to specify that a particular one of the input 263location descriptions is undefined. 264 265See the ``DW_OP_LLVM_undefined`` operation in 266:ref:`amdgpu-dwarf-undefined-location-description-operations`. 267 2682.6 Generalize Creation of Composite Location Descriptions 269---------------------------------------------------------- 270 271To allow composition of composite location descriptions, an explicit operation 272that indicates the end of the definition of a composite location description is 273required. This can be implied if the end of a DWARF expression is reached, 274allowing current DWARF expressions to remain legal. 275 276See ``DW_OP_LLVM_piece_end`` in 277:ref:`amdgpu-dwarf-composite-location-description-operations`. 278 2792.7 Generalize DWARF Base Objects to Allow Any Location Description Kind 280------------------------------------------------------------------------ 281 282The number of registers and the cost of memory operations is much higher for 283AMDGPU than a typical CPU. The compiler attempts to optimize whole variables and 284arrays into registers. 285 286Currently DWARF only allows ``DW_OP_push_object_address`` and related operations 287to work with a global memory location. To support AMDGPU optimized code it is 288required to generalize DWARF to allow any location description to be used. This 289allows registers, or composite location descriptions that may be a mixture of 290memory, registers, or even implicit values. 291 292See ``DW_OP_push_object_address`` in 293:ref:`amdgpu-dwarf-general-location-description-operations`. 294 2952.8 General Support for Address Spaces 296-------------------------------------- 297 298AMDGPU needs to be able to describe addresses that are in different kinds of 299memory. Optimized code may need to describe a variable that resides in pieces 300that are in different kinds of storage which may include parts of registers, 301memory that is in a mixture of memory kinds, implicit values, or be undefined. 302 303DWARF has the concept of segment addresses. However, the segment cannot be 304specified within a DWARF expression, which is only able to specify the offset 305portion of a segment address. The segment index is only provided by the entity 306that specifies the DWARF expression. Therefore, the segment index is a property 307that can only be put on complete objects, such as a variable. That makes it only 308suitable for describing an entity (such as variable or subprogram code) that is 309in a single kind of memory. 310 311Therefore, AMDGPU uses the DWARF concept of address spaces. For example, a 312variable may be allocated in a register that is partially spilled to the call 313stack which is in the private address space, and partially spilled to the local 314address space. 315 316DWARF uses the concept of an address in many expression operations but does not 317define how it relates to address spaces. For example, 318``DW_OP_push_object_address`` pushes the address of an object. Other contexts 319implicitly push an address on the stack before evaluating an expression. For 320example, the ``DW_AT_use_location`` attribute of the 321``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type 322which may apply to objects allocated in different kinds of storage. Therefore, 323it is desirable that the expression that uses the address can do so without 324regard to what kind of storage it specifies, including the address space of a 325memory location description. For example, a pointer to member value may want to 326be applied to an object that may reside in any address space. 327 328The DWARF ``DW_OP_xderef*`` operations allow a value to be converted into an 329address of a specified address space which is then read. But it provides no 330way to create a memory location description for an address in the non-default 331address space. For example, AMDGPU variables can be allocated in the local 332address space at a fixed address. 333 334The ``DW_OP_LLVM_form_aspace_address`` (see 335:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is defined 336to create a memory location description from an address and address space. If 337can be used to specify the location of a variable that is allocated in a 338specific address space. This allows the size of addresses in an address space to 339be larger than the generic type. It also allows a consumer great implementation 340freedom. It allows the implicit conversion back to a value to be limited only to 341the default address space to maintain compatibility with DWARF Version 5. For 342other address spaces the producer can use the new operations that explicitly 343specify the address space. 344 345In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been 346defined to produce a value, and an implicit conversion to a memory location 347description was defined, then it would be limited to the size of the generic 348type (which matches the size of the default address space). An implementation 349would likely have to use *reserved ranges* of value to represent different 350address spaces. Such a value would likely not match any address value in the 351actual hardware. That would require the consumer to have special treatment for 352such values. 353 354``DW_OP_breg*`` treats the register as containing an address in the default 355address space. A ``DW_OP_LLVM_aspace_bregx`` (see 356:ref:`amdgpu-dwarf-memory-location-description-operations`) operation is added 357to allow the address space of the address held in a register to be specified. 358 359Similarly, ``DW_OP_implicit_pointer`` treats its implicit pointer value as being 360in the default address space. A ``DW_OP_LLVM_aspace_implicit_pointer`` 361(:ref:`amdgpu-dwarf-implicit-location-description-operations`) operation is 362added to allow the address space to be specified. 363 364Almost all uses of addresses in DWARF are limited to defining location 365descriptions, or to be dereferenced to read memory. The exception is 366``DW_CFA_val_offset`` which uses the address to set the value of a register. In 367order to support address spaces, the CFA DWARF expression is defined to be a 368memory location description. This allows it to specify an address space which is 369used to convert the offset address back to an address in that address space. See 370:ref:`amdgpu-dwarf-call-frame-information`. 371 372This approach of extending memory location descriptions to support address 373spaces, allows all existing DWARF Version 5 expressions to have the identical 374semantics. It allows the compiler to explicitly specify the address space it is 375using. For example, a compiler could choose to access private memory in a 376swizzled manner when mapping a source language thread to the lane of a wavefront 377in a SIMT manner. Or a compiler could choose to access it in an unswizzled 378manner if mapping the same language with the wavefront being the thread. 379 380It also allows the compiler to mix the address space it uses to access private 381memory. For example, for SIMT it can still spill entire vector registers in an 382unswizzled manner, while using a swizzled private memory for SIMT variable 383access. 384 385This approach also allows memory location descriptions for different address 386spaces to be combined using the regular ``DW_OP_*piece`` operations. 387 388Location descriptions are an abstraction of storage. They give freedom to the 389consumer on how to implement them. They allow the address space to encode lane 390information so they can be used to read memory with only the memory location 391description and no extra information. The same set of operations can operate on 392locations independent of their kind of storage. The ``DW_OP_deref*`` therefore 393can be used on any storage kind, including memory location descriptions of 394different address spaces. Therefore, the ``DW_OP_xderef*`` operations are 395unnecessary, except to become a more compact way to encode a non-default address 396space address followed by dereferencing it. See 397:ref:`amdgpu-dwarf-general-operations`. 398 3992.9 Support for Vector Base Types 400--------------------------------- 401 402The vector registers of the AMDGPU are represented as their full wavefront 403size, meaning the wavefront size times the dword size. This reflects the 404actual hardware and allows the compiler to generate DWARF for languages that 405map a thread to the complete wavefront. It also allows more efficient DWARF to 406be generated to describe the CFI as only a single expression is required for 407the whole vector register, rather than a separate expression for each lane's 408dword of the vector register. It also allows the compiler to produce DWARF 409that indexes the vector register if it spills scalar registers into portions 410of a vector register. 411 412Since DWARF stack value entries have a base type and AMDGPU registers are a 413vector of dwords, the ability to specify that a base type is a vector is 414required. 415 416See ``DW_AT_LLVM_vector_size`` in :ref:`amdgpu-dwarf-literal-operations`. 417 418.. _amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions: 419 4202.10 DWARF Operations to Create Vector Composite Location Descriptions 421---------------------------------------------------------------------- 422 423AMDGPU optimized code may spill vector registers to non-global address space 424memory, and this spilling may be done only for SIMT lanes that are active on 425entry to the subprogram. 426 427To support this, a composite location description that can be created as a 428masked select is required. In addition, an operation that creates a composite 429location description that is a vector on another location description is needed. 430 431An example that uses these operations is referenced in the 432:ref:`amdgpu-dwarf-examples` appendix. 433 434See ``DW_OP_LLVM_select_bit_piece`` and ``DW_OP_LLVM_extend`` in 435:ref:`amdgpu-dwarf-composite-location-description-operations`. 436 4372.11 DWARF Operation to Access Call Frame Entry Registers 438--------------------------------------------------------- 439 440As described in 441:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`, 442a DWARF expression involving the set of SIMT lanes active on entry to a 443subprogram is required. The SIMT active lane mask may be held in a register that 444is modified as the subprogram executes. However, its value may be saved on entry 445to the subprogram. 446 447The Call Frame Information (CFI) already encodes such register saving, so it is 448more efficient to provide an operation to return the location of a saved 449register than have to generate a loclist to describe the same information. This 450is now possible since 451:ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` 452allows location descriptions on the stack. 453 454See ``DW_OP_LLVM_call_frame_entry_reg`` in 455:ref:`amdgpu-dwarf-general-location-description-operations` and 456:ref:`amdgpu-dwarf-call-frame-information`. 457 4582.12 Support for Source Languages Mapped to SIMT Hardware 459--------------------------------------------------------- 460 461If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner, 462then the variable DWARF location expressions must compute the location for a 463single lane of the wavefront. Therefore, a DWARF operation is required to denote 464the current lane, much like ``DW_OP_push_object_address`` denotes the current 465object. 466 467See ``DW_OP_LLVM_push_lane`` in :ref:`amdgpu-dwarf-base-type-entries`. 468 469.. _amdgpu-dwarf-support-for-divergent-control-flow-of-simt-hardware: 470 4712.13 Support for Divergent Control Flow of SIMT Hardware 472-------------------------------------------------------- 473 474If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner the 475compiler can use the AMDGPU execution mask register to control which lanes are 476active. To describe the conceptual location of non-active lanes requires an 477attribute that has an expression that computes the source location PC for each 478lane. 479 480For efficiency, the expression calculates the source location the wavefront as a 481whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see 482:ref:`amdgpu-dwarf-operation-to-create-vector-composite-location-descriptions`) 483operation. 484 485The AMDGPU may update the execution mask to perform whole wavefront operations. 486Therefore, there is a need for an attribute that computes the current active 487lane mask. This can have an expression that may evaluate to the SIMT active lane 488mask register or to a saved mask when in whole wavefront execution mode. 489 490An example that uses these attributes is referenced in the 491:ref:`amdgpu-dwarf-examples` appendix. 492 493See ``DW_AT_LLVM_lane_pc`` and ``DW_AT_LLVM_active_lane`` in 494:ref:`amdgpu-dwarf-composite-location-description-operations`. 495 4962.14 Define Source Language Address Classes 497------------------------------------------- 498 499AMDGPU supports languages, such as OpenCL [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`], 500that define source language address classes. Support is added to define language 501specific address classes so they can be used in a consistent way by consumers. 502 503It would also be desirable to add support for using address classes in defining 504source language types. DWARF Version 5 only supports using target architecture 505specific address spaces. 506 507See :ref:`amdgpu-dwarf-segment_addresses`. 508 5092.15 Define Augmentation Strings to Support Multiple Extensions 510--------------------------------------------------------------- 511 512A ``DW_AT_LLVM_augmentation`` attribute is added to a compilation unit debugger 513information entry to indicate that there is additional target architecture 514specific information in the debugging information entries of that compilation 515unit. This allows a consumer to know what extensions are present in the debugger 516information entries as is possible with the augmentation string of other 517sections. See . 518 519The format that should be used for an augmentation string is also recommended. 520This allows a consumer to parse the string when it contains information from 521multiple vendors. Augmentation strings occur in the ``DW_AT_LLVM_augmentation`` 522attribute, in the lookup by name table, and in the CFI Common Information Entry 523(CIE). 524 525See :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`, 526:ref:`amdgpu-dwarf-name-index-section-header`, and 527:ref:`amdgpu-dwarf-structure_of-call-frame-information`. 528 5292.16 Support Embedding Source Text for Online Compilation 530--------------------------------------------------------- 531 532AMDGPU supports programming languages that include online compilation where the 533source text may be created at runtime. For example, the OpenCL and HIP language 534runtimes support online compilation. To support is, a way to embed the source 535text in the debug information is provided. 536 537See :ref:`amdgpu-dwarf-line-number-information`. 538 5392.17 Allow MD5 Checksums to be Optionally Present 540------------------------------------------------- 541 542In DWARF Version 5 the file timestamp and file size can be optional, but if the 543MD5 checksum is present it must be valid for all files. This is a problem if 544using link time optimization to combine compilation units where some have MD5 545checksums and some do not. Therefore, sSupport to allow MD5 checksums to be 546optionally present in the line table is added. 547 548See :ref:`amdgpu-dwarf-line-number-information`. 549 5502.18 Add the HIP Programing Language 551------------------------------------ 552 553The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported 554by the AMDGPU, is added. 555 556See :ref:`amdgpu-dwarf-language-names-table`. 557 558.. _amdgpu-dwarf-changes-relative-to-dwarf-version-5: 559 560A. Changes Relative to DWARF Version 5 561====================================== 562 563.. note:: 564 565 This appendix provides changes relative to DWARF Version 5. It has been 566 defined such that it is backwards compatible with DWARF Version 5. 567 Non-normative text is shown in *italics*. The section numbers generally 568 correspond to those in the DWARF Version 5 standard unless specified 569 otherwise. Definitions are given for the additional operations, as well as 570 clarifying how existing expression operations, CFI operations, and attributes 571 behave with respect to generalized location descriptions that support address 572 spaces and multiple places. 573 574 The names for the new operations, attributes, and constants include "\ 575 ``LLVM``\ " and are encoded with vendor specific codes so these extensions can 576 be implemented as an LLVM vendor extension to DWARF Version 5. 577 578 .. note:: 579 580 Notes are included to describe how the changes are to be applied to the 581 DWARF Version 5 standard. They also describe rational and issues that may 582 need further consideration. 583 584A.2 General Description 585----------------------- 586 587A.2.2 Attribute Types 588~~~~~~~~~~~~~~~~~~~~~ 589 590.. note:: 591 592 This augments DWARF Version 5 section 2.2 and Table 2.2. 593 594The following table provides the additional attributes. 595 596.. table:: Attribute names 597 :name: amdgpu-dwarf-attribute-names-table 598 599 =========================== ==================================== 600 Attribute Usage 601 =========================== ==================================== 602 ``DW_AT_LLVM_active_lane`` SIMD or SIMT active lanes (see :ref:`amdgpu-dwarf-low-level-information`) 603 ``DW_AT_LLVM_augmentation`` Compilation unit augmentation string (see :ref:`amdgpu-dwarf-full-and-partial-compilation-unit-entries`) 604 ``DW_AT_LLVM_lane_pc`` SIMD or SIMT lane program location (see :ref:`amdgpu-dwarf-low-level-information`) 605 ``DW_AT_LLVM_lanes`` SIMD or SIMT thread lane count (see :ref:`amdgpu-dwarf-low-level-information`) 606 ``DW_AT_LLVM_vector_size`` Base type vector size (see :ref:`amdgpu-dwarf-base-type-entries`) 607 =========================== ==================================== 608 609.. _amdgpu-dwarf-expressions: 610 611A.2.5 DWARF Expressions 612~~~~~~~~~~~~~~~~~~~~~~~ 613 614.. note:: 615 616 This section, and its nested sections, replaces DWARF Version 5 section 2.5 617 and section 2.6. The new DWARF expression operation extensions are defined as 618 well as clarifying the extensions to already existing DWARF Version 5 619 operations. It is based on the text of the existing DWARF Version 5 standard. 620 621DWARF expressions describe how to compute a value or specify a location. 622 623*The evaluation of a DWARF expression can provide the location of an object, the 624value of an array bound, the length of a dynamic string, the desired value 625itself, and so on.* 626 627If the evaluation of a DWARF expression does not encounter an error, then it can 628either result in a value (see :ref:`amdgpu-dwarf-expression-value`) or a 629location description (see :ref:`amdgpu-dwarf-location-description`). When a 630DWARF expression is evaluated, it may be specified whether a value or location 631description is required as the result kind. 632 633If a result kind is specified, and the result of the evaluation does not match 634the specified result kind, then the implicit conversions described in 635:ref:`amdgpu-dwarf-memory-location-description-operations` are performed if 636valid. Otherwise, the DWARF expression is ill-formed. 637 638If the evaluation of a DWARF expression encounters an evaluation error, then the 639result is an evaluation error. 640 641.. note:: 642 643 Decided to define the concept of an evaluation error. An alternative is to 644 introduce an undefined value base type in a similar way to location 645 descriptions having an undefined location description. Then operations that 646 encounter an evaluation error can return the undefined location description or 647 value with an undefined base type. 648 649 All operations that act on values would return an undefined entity if given an 650 undefined value. The expression would then always evaluate to completion, and 651 can be tested to determine if it is an undefined entity. 652 653 However, this would add considerable additional complexity and does not match 654 that GDB throws an exception when these evaluation errors occur. 655 656If a DWARF expression is ill-formed, then the result is undefined. 657 658The following sections detail the rules for when a DWARF expression is 659ill-formed or results in an evaluation error. 660 661A DWARF expression can either be encoded as an operation expression (see 662:ref:`amdgpu-dwarf-operation-expressions`), or as a location list expression 663(see :ref:`amdgpu-dwarf-location-list-expressions`). 664 665.. _amdgpu-dwarf-expression-evaluation-context: 666 667A.2.5.1 DWARF Expression Evaluation Context 668+++++++++++++++++++++++++++++++++++++++++++ 669 670A DWARF expression is evaluated in a context that can include a number of 671context elements. If multiple context elements are specified then they must be 672self consistent or the result of the evaluation is undefined. The context 673elements that can be specified are: 674 675*A current result kind* 676 677 The kind of result required by the DWARF expression evaluation. If specified 678 it can be a location description or a value. 679 680*A current thread* 681 682 The target architecture thread identifier of the source program thread of 683 execution for which a user presented expression is currently being evaluated. 684 685 It is required for operations that are related to target architecture threads. 686 687 *For example, the* ``DW_OP_regval_type`` *operation, or the* 688 ``DW_OP_form_tls_address`` *and* ``DW_OP_LLVM_form_aspace_address`` 689 *operations when given an address space that is thread specific.* 690 691*A current lane* 692 693 The target architecture lane identifier of the source program thread of 694 execution for which a user presented expression is currently being evaluated. 695 This applies to languages that are implemented using a SIMD or SIMT execution 696 model. 697 698 It is required for operations that are related to target architecture lanes. 699 700 *For example, the* ``DW_OP_LLVM_push_lane`` *operation and* 701 ``DW_OP_LLVM_form_aspace_address`` *operation when given an address space that 702 is lane specific.* 703 704 If specified, it must be consistent with any specified current thread and 705 current target architecture. It is consistent with a thread if it identifies a 706 lane of the thread. It is consistent with a target architecture if it is a 707 valid lane identifier of the target architecture. Otherwise the result is 708 undefined. 709 710*A current call frame* 711 712 The target architecture call frame identifier. It identifies a call frame that 713 corresponds to an active invocation of a subprogram in the current thread. It 714 is identified by its address on the call stack. The address is referred to as 715 the Canonical Frame Address (CFA). The call frame information is used to 716 determine the CFA for the call frames of the current thread's call stack (see 717 :ref:`amdgpu-dwarf-call-frame-information`). 718 719 It is required for operations that specify target architecture registers to 720 support virtual unwinding of the call stack. 721 722 *For example, the* ``DW_OP_*reg*`` *operations.* 723 724 If specified, it must be an active call frame in the current thread. If the 725 current lane is specified, then that lane must have been active on entry to 726 the call frame (see the ``DW_AT_LLVM_lane_pc`` attribute). Otherwise the 727 result is undefined. 728 729 If it is the currently executing call frame, then it is termed the top call 730 frame. 731 732*A current program location* 733 734 The target architecture program location corresponding to the current call 735 frame of the current thread. 736 737 The program location of the top call frame is the target architecture program 738 counter for the current thread. The call frame information is used to obtain 739 the value of the return address register to determine the program location of 740 the other call frames (see :ref:`amdgpu-dwarf-call-frame-information`). 741 742 It is required for the evaluation of location list expressions to select 743 amongst multiple program location ranges. It is required for operations that 744 specify target architecture registers to support virtual unwinding of the call 745 stack (see :ref:`amdgpu-dwarf-call-frame-information`). 746 747 If specified: 748 749 * If the current lane is not specified: 750 751 * If the current call frame is the top call frame, it must be the current 752 target architecture program location. 753 754 * If the current call frame F is not the top call frame, it must be the 755 program location associated with the call site in the current caller frame 756 F that invoked the callee frame. 757 758 * If the current lane is specified and the architecture program location LPC 759 computed by the ``DW_AT_LLVM_lane_pc`` attribute for the current lane is not 760 the undefined location description (indicating the lane was not active on 761 entry to the call frame), it must be LPC. 762 763 * Otherwise the result is undefined. 764 765*A current compilation unit* 766 767 The compilation unit debug information entry that contains the DWARF expression 768 being evaluated. 769 770 It is required for operations that reference debug information associated with 771 the same compilation unit, including indicating if such references use the 772 32-bit or 64-bit DWARF format. It can also provide the default address space 773 address size if no current target architecture is specified. 774 775 *For example, the* ``DW_OP_constx`` *and* ``DW_OP_addrx`` *operations.* 776 777 *Note that this compilation unit may not be the same as the compilation unit 778 determined from the loaded code object corresponding to the current program 779 location. For example, the evaluation of the expression E associated with a* 780 ``DW_AT_location`` *attribute of the debug information entry operand of the* 781 ``DW_OP_call*`` *operations is evaluated with the compilation unit that 782 contains E and not the one that contains the* ``DW_OP_call*`` *operation 783 expression.* 784 785*A current target architecture* 786 787 The target architecture. 788 789 It is required for operations that specify target architecture specific 790 entities. 791 792 *For example, target architecture specific entities include DWARF register 793 identifiers, DWARF lane identifiers, DWARF address space identifiers, the 794 default address space, and the address space address sizes.* 795 796 If specified: 797 798 * If the current thread is specified, then the current target architecture 799 must be the same as the target architecture of the current thread. 800 801 * If the current compilation unit is specified, then the current target 802 architecture default address space address size must be the same as the 803 ``address_size`` field in the header of the current compilation unit and any 804 associated entry in the ``.debug_aranges`` section. 805 806 * If the current program location is specified, then the current target 807 architecture must be the same as the target architecture of any line number 808 information entry (see :ref:`amdgpu-dwarf-line-number-information`) 809 corresponding to the current program location. 810 811 * If the current program location is specified, then the current target 812 architecture default address space address size must be the same as the 813 ``address_size`` field in the header of any entry corresponding to the 814 current program location in the ``.debug_addr``, ``.debug_line``, 815 ``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and 816 ``.debug_loclists.dwo`` sections. 817 818 * Otherwise the result is undefined. 819 820*A current object* 821 822 The location description of a program object. 823 824 It is required for the ``DW_OP_push_object_address`` operation. 825 826 *For example, the* ``DW_AT_data_location`` *attribute on type debug 827 information entries specifies the program object corresponding to a runtime 828 descriptor as the current object when it evaluates its associated expression.* 829 830 The result is undefined if the location descriptor is invalid (see 831 :ref:`amdgpu-dwarf-location-description`). 832 833*An initial stack* 834 835 This is a list of values or location descriptions that will be pushed on the 836 operation expression evaluation stack in the order provided before evaluation 837 of an operation expression starts. 838 839 Some debugger information entries have attributes that evaluate their DWARF 840 expression value with initial stack entries. In all other cases the initial 841 stack is empty. 842 843 The result is undefined if any location descriptors are invalid (see 844 :ref:`amdgpu-dwarf-location-description`). 845 846If the evaluation requires a context element that is not specified, then the 847result of the evaluation is an error. 848 849*A DWARF expression for a location description may be able to be evaluated 850without a thread, lane, call frame, program location, or architecture context. 851For example, the location of a global variable may be able to be evaluated 852without such context. If the expression evaluates with an error then it may 853indicate the variable has been optimized and so requires more context.* 854 855*The DWARF expression for call frame information (see 856:ref:`amdgpu-dwarf-call-frame-information`) operations are restricted to those 857that do not require the compilation unit context to be specified.* 858 859The DWARF is ill-formed if all the ``address_size`` fields in the headers of all 860the entries in the ``.debug_info``, ``.debug_addr``, ``.debug_line``, 861``.debug_rnglists``, ``.debug_rnglists.dwo``, ``.debug_loclists``, and 862``.debug_loclists.dwo`` sections corresponding to any given program location do 863not match. 864 865.. _amdgpu-dwarf-expression-value: 866 867A.2.5.2 DWARF Expression Value 868++++++++++++++++++++++++++++++ 869 870A value has a type and a literal value. It can represent a literal value of any 871supported base type of the target architecture. The base type specifies the 872size, encoding, and endianity of the literal value. 873 874.. note:: 875 876 It may be desirable to add an implicit pointer base type encoding. It would be 877 used for the type of the value that is produced when the ``DW_OP_deref*`` 878 operation retrieves the full contents of an implicit pointer location storage 879 created by the ``DW_OP_implicit_pointer`` or 880 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. The literal value would 881 record the debugging information entry and byte displacement specified by the 882 associated ``DW_OP_implicit_pointer`` or 883 ``DW_OP_LLVM_aspace_implicit_pointer`` operations. 884 885There is a distinguished base type termed the generic type, which is an integral 886type that has the size of an address in the target architecture default address 887space, a target architecture defined endianity, and unspecified signedness. 888 889*The generic type is the same as the unspecified type used for stack operations 890defined in DWARF Version 4 and before.* 891 892An integral type is a base type that has an encoding of ``DW_ATE_signed``, 893``DW_ATE_signed_char``, ``DW_ATE_unsigned``, ``DW_ATE_unsigned_char``, 894``DW_ATE_boolean``, or any target architecture defined integral encoding in the 895inclusive range ``DW_ATE_lo_user`` to ``DW_ATE_hi_user``. 896 897.. note:: 898 899 It is unclear if ``DW_ATE_address`` is an integral type. GDB does not seem to 900 consider it as integral. 901 902.. _amdgpu-dwarf-location-description: 903 904A.2.5.3 DWARF Location Description 905++++++++++++++++++++++++++++++++++ 906 907*Debugging information must provide consumers a way to find the location of 908program variables, determine the bounds of dynamic arrays and strings, and 909possibly to find the base address of a subprogram’s call frame or the return 910address of a subprogram. Furthermore, to meet the needs of recent computer 911architectures and optimization techniques, debugging information must be able to 912describe the location of an object whose location changes over the object’s 913lifetime, and may reside at multiple locations simultaneously during parts of an 914object's lifetime.* 915 916Information about the location of program objects is provided by location 917descriptions. 918 919Location descriptions can consist of one or more single location descriptions. 920 921A single location description specifies the location storage that holds a 922program object and a position within the location storage where the program 923object starts. The position within the location storage is expressed as a bit 924offset relative to the start of the location storage. 925 926A location storage is a linear stream of bits that can hold values. Each 927location storage has a size in bits and can be accessed using a zero-based bit 928offset. The ordering of bits within a location storage uses the bit numbering 929and direction conventions that are appropriate to the current language on the 930target architecture. 931 932There are five kinds of location storage: 933 934*memory location storage* 935 Corresponds to the target architecture memory address spaces. 936 937*register location storage* 938 Corresponds to the target architecture registers. 939 940*implicit location storage* 941 Corresponds to fixed values that can only be read. 942 943*undefined location storage* 944 Indicates no value is available and therefore cannot be read or written. 945 946*composite location storage* 947 Allows a mixture of these where some bits come from one location storage and 948 some from another location storage, or from disjoint parts of the same 949 location storage. 950 951.. note:: 952 953 It may be better to add an implicit pointer location storage kind used by the 954 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer`` 955 operations. It would specify the debugger information entry and byte offset 956 provided by the operations. 957 958*Location descriptions are a language independent representation of addressing 959rules.* 960 961* *They can be the result of evaluating a debugger information entry attribute 962 that specifies an operation expression of arbitrary complexity. In this usage 963 they can describe the location of an object as long as its lifetime is either 964 static or the same as the lexical block (see 965 :ref:`amdgpu-dwarf-lexical-block-entries`) that owns it, and it does not move 966 during its lifetime.* 967 968* *They can be the result of evaluating a debugger information entry attribute 969 that specifies a location list expression. In this usage they can describe the 970 location of an object that has a limited lifetime, changes its location during 971 its lifetime, or has multiple locations over part or all of its lifetime.* 972 973If a location description has more than one single location description, the 974DWARF expression is ill-formed if the object value held in each single location 975description's position within the associated location storage is not the same 976value, except for the parts of the value that are uninitialized. 977 978*A location description that has more than one single location description can 979only be created by a location list expression that has overlapping program 980location ranges, or certain expression operations that act on a location 981description that has more than one single location description. There are no 982operation expression operations that can directly create a location description 983with more than one single location description.* 984 985*A location description with more than one single location description can be 986used to describe objects that reside in more than one piece of storage at the 987same time. An object may have more than one location as a result of 988optimization. For example, a value that is only read may be promoted from memory 989to a register for some region of code, but later code may revert to reading the 990value from memory as the register may be used for other purposes. For the code 991region where the value is in a register, any change to the object value must be 992made in both the register and the memory so both regions of code will read the 993updated value.* 994 995*A consumer of a location description with more than one single location 996description can read the object's value from any of the single location 997descriptions (since they all refer to location storage that has the same value), 998but must write any changed value to all the single location descriptions.* 999 1000The evaluation of an expression may require context elements to create a 1001location description. If such a location description is accessed, the storage it 1002denotes is that associated with the context element values specified when the 1003location description was created, which may differ from the context at the time 1004it is accessed. 1005 1006*For example, creating a register location description requires the thread 1007context: the location storage is for the specified register of that thread. 1008Creating a memory location description for an address space may required a 1009thread and a lane context: the location storage is the memory associated with 1010that thread and lane.* 1011 1012If any of the context elements required to create a location description change, 1013the location description becomes invalid and accessing it is undefined. 1014 1015*Examples of context that can invalidate a location description are:* 1016 1017* *The thread context is required and execution causes the thread to terminate.* 1018* *The call frame context is required and further execution causes the call 1019 frame to return to the calling frame.* 1020* *The program location is required and further execution of the thread occurs. 1021 That could change the location list entry or call frame information entry that 1022 applies.* 1023* *An operation uses call frame information:* 1024 1025 * *Any of the frames used in the virtual call frame unwinding return.* 1026 * *The top call frame is used, the program location is used to select the call 1027 frame information entry, and further execution of the thread occurs.* 1028 1029*A DWARF expression can be used to compute a location description for an object. 1030A subsequent DWARF expression evaluation can be given the object location 1031description as the object context or initial stack context to compute a 1032component of the object. The final result is undefined if the object location 1033description becomes invalid between the two expression evaluations.* 1034 1035A change of a thread's program location may not make a location description 1036invalid, yet may still render it as no longer meaningful. Accessing such a 1037location description, or using it as the object context or initial stack context 1038of an expression evaluation, may produce an undefined result. 1039 1040*For example, a location description may specify a register that no longer holds 1041the intended program object after a program location change. One way to avoid 1042such problems is to recompute location descriptions associated with threads when 1043their program locations change.* 1044 1045.. _amdgpu-dwarf-operation-expressions: 1046 1047A.2.5.4 DWARF Operation Expressions 1048+++++++++++++++++++++++++++++++++++ 1049 1050An operation expression is comprised of a stream of operations, each consisting 1051of an opcode followed by zero or more operands. The number of operands is 1052implied by the opcode. 1053 1054Operations represent a postfix operation on a simple stack machine. Each stack 1055entry can hold either a value or a location description. Operations can act on 1056entries on the stack, including adding entries and removing entries. If the kind 1057of a stack entry does not match the kind required by the operation and is not 1058implicitly convertible to the required kind (see 1059:ref:`amdgpu-dwarf-memory-location-description-operations`), then the DWARF 1060operation expression is ill-formed. 1061 1062Evaluation of an operation expression starts with an empty stack on which the 1063entries from the initial stack provided by the context are pushed in the order 1064provided. Then the operations are evaluated, starting with the first operation 1065of the stream. Evaluation continues until either an operation has an evaluation 1066error, or until one past the last operation of the stream is reached. 1067 1068The result of the evaluation is: 1069 1070* If an operation has an evaluation error, or an operation evaluates an 1071 expression that has an evaluation error, then the result is an evaluation 1072 error. 1073 1074* If the current result kind specifies a location description, then: 1075 1076 * If the stack is empty, the result is a location description with one 1077 undefined location description. 1078 1079 *This rule is for backwards compatibility with DWARF Version 5 which has no 1080 explicit operation to create an undefined location description, and uses an 1081 empty operation expression for this purpose.* 1082 1083 * If the top stack entry is a location description, or can be converted 1084 to one (see :ref:`amdgpu-dwarf-memory-location-description-operations`), 1085 then the result is that, possibly converted, location description. Any other 1086 entries on the stack are discarded. 1087 1088 * Otherwise the DWARF expression is ill-formed. 1089 1090 .. note:: 1091 1092 Could define this case as returning an implicit location description as 1093 if the ``DW_OP_implicit`` operation is performed. 1094 1095* If the current result kind specifies a value, then: 1096 1097 * If the top stack entry is a value, or can be converted to one (see 1098 :ref:`amdgpu-dwarf-memory-location-description-operations`), then the result 1099 is that, possibly converted, value. Any other entries on the stack are 1100 discarded. 1101 1102 * Otherwise the DWARF expression is ill-formed. 1103 1104* If the current result kind is not specified, then: 1105 1106 * If the stack is empty, the result is a location description with one 1107 undefined location description. 1108 1109 *This rule is for backwards compatibility with DWARF Version 5 which has no 1110 explicit operation to create an undefined location description, and uses an 1111 empty operation expression for this purpose.* 1112 1113 .. note:: 1114 1115 This rule is consistent with the rule above for when a location 1116 description is requested. However, GDB appears to report this as an error 1117 and no GDB tests appear to cause an empty stack for this case. 1118 1119 * Otherwise, the top stack entry is returned. Any other entries on the stack 1120 are discarded. 1121 1122An operation expression is encoded as a byte block with some form of prefix that 1123specifies the byte count. It can be used: 1124 1125* as the value of a debugging information entry attribute that is encoded using 1126 class ``exprloc`` (see :ref:`amdgpu-dwarf-classes-and-forms`), 1127 1128* as the operand to certain operation expression operations, 1129 1130* as the operand to certain call frame information operations (see 1131 :ref:`amdgpu-dwarf-call-frame-information`), 1132 1133* and in location list entries (see 1134 :ref:`amdgpu-dwarf-location-list-expressions`). 1135 1136.. _amdgpu-dwarf-stack-operations: 1137 1138A.2.5.4.1 Stack Operations 1139########################## 1140 1141.. note:: 1142 1143 This section replaces DWARF Version 5 section 2.5.1.3. 1144 1145The following operations manipulate the DWARF stack. Operations that index the 1146stack assume that the top of the stack (most recently added entry) has index 0. 1147They allow the stack entries to be either a value or location description. 1148 1149If any stack entry accessed by a stack operation is an incomplete composite 1150location description (see 1151:ref:`amdgpu-dwarf-composite-location-description-operations`), then the DWARF 1152expression is ill-formed. 1153 1154.. note:: 1155 1156 These operations now support stack entries that are values and location 1157 descriptions. 1158 1159.. note:: 1160 1161 If it is desired to also make them work with incomplete composite location 1162 descriptions, then would need to define that the composite location storage 1163 specified by the incomplete composite location description is also replicated 1164 when a copy is pushed. This ensures that each copy of the incomplete composite 1165 location description can update the composite location storage they specify 1166 independently. 1167 11681. ``DW_OP_dup`` 1169 1170 ``DW_OP_dup`` duplicates the stack entry at the top of the stack. 1171 11722. ``DW_OP_drop`` 1173 1174 ``DW_OP_drop`` pops the stack entry at the top of the stack and discards it. 1175 11763. ``DW_OP_pick`` 1177 1178 ``DW_OP_pick`` has a single unsigned 1-byte operand that represents an index 1179 I. A copy of the stack entry with index I is pushed onto the stack. 1180 11814. ``DW_OP_over`` 1182 1183 ``DW_OP_over`` pushes a copy of the entry with index 1. 1184 1185 *This is equivalent to a* ``DW_OP_pick 1`` *operation.* 1186 11875. ``DW_OP_swap`` 1188 1189 ``DW_OP_swap`` swaps the top two stack entries. The entry at the top of the 1190 stack becomes the second stack entry, and the second stack entry becomes the 1191 top of the stack. 1192 11936. ``DW_OP_rot`` 1194 1195 ``DW_OP_rot`` rotates the first three stack entries. The entry at the top of 1196 the stack becomes the third stack entry, the second entry becomes the top of 1197 the stack, and the third entry becomes the second entry. 1198 1199.. _amdgpu-dwarf-control-flow-operations: 1200 1201A.2.5.4.2 Control Flow Operations 1202################################# 1203 1204.. note:: 1205 1206 This section replaces DWARF Version 5 section 2.5.1.5. 1207 1208The following operations provide simple control of the flow of a DWARF operation 1209expression. 1210 12111. ``DW_OP_nop`` 1212 1213 ``DW_OP_nop`` is a place holder. It has no effect on the DWARF stack 1214 entries. 1215 12162. ``DW_OP_le``, ``DW_OP_ge``, ``DW_OP_eq``, ``DW_OP_lt``, ``DW_OP_gt``, 1217 ``DW_OP_ne`` 1218 1219 .. note:: 1220 1221 The same as in DWARF Version 5 section 2.5.1.5. 1222 12233. ``DW_OP_skip`` 1224 1225 ``DW_OP_skip`` is an unconditional branch. Its single operand is a 2-byte 1226 signed integer constant. The 2-byte constant is the number of bytes of the 1227 DWARF expression to skip forward or backward from the current operation, 1228 beginning after the 2-byte constant. 1229 1230 If the updated position is at one past the end of the last operation, then 1231 the operation expression evaluation is complete. 1232 1233 Otherwise, the DWARF expression is ill-formed if the updated operation 1234 position is not in the range of the first to last operation inclusive, or 1235 not at the start of an operation. 1236 12374. ``DW_OP_bra`` 1238 1239 ``DW_OP_bra`` is a conditional branch. Its single operand is a 2-byte signed 1240 integer constant. This operation pops the top of stack. If the value popped 1241 is not the constant 0, the 2-byte constant operand is the number of bytes of 1242 the DWARF operation expression to skip forward or backward from the current 1243 operation, beginning after the 2-byte constant. 1244 1245 If the updated position is at one past the end of the last operation, then 1246 the operation expression evaluation is complete. 1247 1248 Otherwise, the DWARF expression is ill-formed if the updated operation 1249 position is not in the range of the first to last operation inclusive, or 1250 not at the start of an operation. 1251 12525. ``DW_OP_call2, DW_OP_call4, DW_OP_call_ref`` 1253 1254 ``DW_OP_call2``, ``DW_OP_call4``, and ``DW_OP_call_ref`` perform DWARF 1255 procedure calls during evaluation of a DWARF expression. 1256 1257 ``DW_OP_call2`` and ``DW_OP_call4``, have one operand that is, respectively, 1258 a 2-byte or 4-byte unsigned offset DR that represents the byte offset of a 1259 debugging information entry D relative to the beginning of the current 1260 compilation unit. 1261 1262 ``DW_OP_call_ref`` has one operand that is a 4-byte unsigned value in the 1263 32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format, 1264 that represents the byte offset DR of a debugging information entry D 1265 relative to the beginning of the ``.debug_info`` section that contains the 1266 current compilation unit. D may not be in the current compilation unit. 1267 1268 .. note:: 1269 1270 DWARF Version 5 states that DR can be an offset in a ``.debug_info`` 1271 section other than the one that contains the current compilation unit. It 1272 states that relocation of references from one executable or shared object 1273 file to another must be performed by the consumer. But given that DR is 1274 defined as an offset in a ``.debug_info`` section this seems impossible. 1275 If DR was defined as an implementation defined value, then the consumer 1276 could choose to interpret the value in an implementation defined manner to 1277 reference a debug information in another executable or shared object. 1278 1279 In ELF the ``.debug_info`` section is in a non-\ ``PT_LOAD`` segment so 1280 standard dynamic relocations cannot be used. But even if they were loaded 1281 segments and dynamic relocations were used, DR would need to be the 1282 address of D, not an offset in a ``.debug_info`` section. That would also 1283 need DR to be the size of a global address. So it would not be possible to 1284 use the 32-bit DWARF format in a 64-bit global address space. In addition, 1285 the consumer would need to determine what executable or shared object the 1286 relocated address was in so it could determine the containing compilation 1287 unit. 1288 1289 GDB only interprets DR as an offset in the ``.debug_info`` section that 1290 contains the current compilation unit. 1291 1292 This comment also applies to ``DW_OP_implicit_pointer`` and 1293 ``DW_OP_LLVM_aspace_implicit_pointer``. 1294 1295 *Operand interpretation of* ``DW_OP_call2``\ *,* ``DW_OP_call4``\ *, and* 1296 ``DW_OP_call_ref`` *is exactly like that for* ``DW_FORM_ref2``\ *, 1297 ``DW_FORM_ref4``\ *, and* ``DW_FORM_ref_addr``\ *, respectively.* 1298 1299 The call operation is evaluated by: 1300 1301 * If D has a ``DW_AT_location`` attribute that is encoded as a ``exprloc`` 1302 that specifies an operation expression E, then execution of the current 1303 operation expression continues from the first operation of E. Execution 1304 continues until one past the last operation of E is reached, at which 1305 point execution continues with the operation following the call operation. 1306 The operations of E are evaluated with the same current context, except 1307 current compilation unit is the one that contains D and the stack is the 1308 same as that being used by the call operation. After the call operation 1309 has been evaluated, the stack is therefore as it is left by the evaluation 1310 of the operations of E. Since E is evaluated on the same stack as the call 1311 operation, E can use, and/or remove entries already on the stack, and can 1312 add new entries to the stack. 1313 1314 *Values on the stack at the time of the call may be used as parameters by 1315 the called expression and values left on the stack by the called expression 1316 may be used as return values by prior agreement between the calling and 1317 called expressions.* 1318 1319 * If D has a ``DW_AT_location`` attribute that is encoded as a ``loclist`` or 1320 ``loclistsptr``, then the specified location list expression E is 1321 evaluated. The evaluation of E uses the current context, except the result 1322 kind is a location description, the compilation unit is the one that 1323 contains D, and the initial stack is empty. The location description 1324 result is pushed on the stack. 1325 1326 .. note:: 1327 1328 This rule avoids having to define how to execute a matched location list 1329 entry operation expression on the same stack as the call when there are 1330 multiple matches. But it allows the call to obtain the location 1331 description for a variable or formal parameter which may use a location 1332 list expression. 1333 1334 An alternative is to treat the case when D has a ``DW_AT_location`` 1335 attribute that is encoded as a ``loclist`` or ``loclistsptr``, and the 1336 specified location list expression E' matches a single location list 1337 entry with operation expression E, the same as the ``exprloc`` case and 1338 evaluate on the same stack. 1339 1340 But this is not attractive as if the attribute is for a variable that 1341 happens to end with a non-singleton stack, it will not simply put a 1342 location description on the stack. Presumably the intent of using 1343 ``DW_OP_call*`` on a variable or formal parameter debugger information 1344 entry is to push just one location description on the stack. That 1345 location description may have more than one single location description. 1346 1347 The previous rule for ``exprloc`` also has the same problem, as normally 1348 a variable or formal parameter location expression may leave multiple 1349 entries on the stack and only return the top entry. 1350 1351 GDB implements ``DW_OP_call*`` by always executing E on the same stack. 1352 If the location list has multiple matching entries, it simply picks the 1353 first one and ignores the rest. This seems fundamentally at odds with 1354 the desire to support multiple places for variables. 1355 1356 So, it feels like ``DW_OP_call*`` should both support pushing a location 1357 description on the stack for a variable or formal parameter, and also 1358 support being able to execute an operation expression on the same stack. 1359 Being able to specify a different operation expression for different 1360 program locations seems a desirable feature to retain. 1361 1362 A solution to that is to have a distinct ``DW_AT_LLVM_proc`` attribute 1363 for the ``DW_TAG_dwarf_procedure`` debugging information entry. Then the 1364 ``DW_AT_location`` attribute expression is always executed separately 1365 and pushes a location description (that may have multiple single 1366 location descriptions), and the ``DW_AT_LLVM_proc`` attribute expression 1367 is always executed on the same stack and can leave anything on the 1368 stack. 1369 1370 The ``DW_AT_LLVM_proc`` attribute could have the new classes 1371 ``exprproc``, ``loclistproc``, and ``loclistsptrproc`` to indicate that 1372 the expression is executed on the same stack. ``exprproc`` is the same 1373 encoding as ``exprloc``. ``loclistproc`` and ``loclistsptrproc`` are the 1374 same encoding as their non-\ ``proc`` counterparts, except the DWARF is 1375 ill-formed if the location list does not match exactly one location list 1376 entry and a default entry is required. These forms indicate explicitly 1377 that the matched single operation expression must be executed on the 1378 same stack. This is better than ad hoc special rules for ``loclistproc`` 1379 and ``loclistsptrproc`` which are currently clearly defined to always 1380 return a location description. The producer then explicitly indicates 1381 the intent through the attribute classes. 1382 1383 Such a change would be a breaking change for how GDB implements 1384 ``DW_OP_call*``. However, are the breaking cases actually occurring in 1385 practice? GDB could implement the current approach for DWARF Version 5, 1386 and the new semantics for DWARF Version 6 which has been done for some 1387 other features. 1388 1389 Another option is to limit the execution to be on the same stack only to 1390 the evaluation of an expression E that is the value of a 1391 ``DW_AT_location`` attribute of a ``DW_TAG_dwarf_procedure`` debugging 1392 information entry. The DWARF would be ill-formed if E is a location list 1393 expression that does not match exactly one location list entry. In all 1394 other cases the evaluation of an expression E that is the value of a 1395 ``DW_AT_location`` attribute would evaluate E with the current context, 1396 except the result kind is a location description, the compilation unit 1397 is the one that contains D, and the initial stack is empty. The location 1398 description result is pushed on the stack. 1399 1400 * If D has a ``DW_AT_const_value`` attribute with a value V, then it is as 1401 if a ``DW_OP_implicit_value V`` operation was executed. 1402 1403 *This allows a call operation to be used to compute the location 1404 description for any variable or formal parameter regardless of whether the 1405 producer has optimized it to a constant. This is consistent with the* 1406 ``DW_OP_implicit_pointer`` *operation.* 1407 1408 .. note:: 1409 1410 Alternatively, could deprecate using ``DW_AT_const_value`` for 1411 ``DW_TAG_variable`` and ``DW_TAG_formal_parameter`` debugger information 1412 entries that are constants and instead use ``DW_AT_location`` with an 1413 operation expression that results in a location description with one 1414 implicit location description. Then this rule would not be required. 1415 1416 * Otherwise, there is no effect and no changes are made to the stack. 1417 1418 .. note:: 1419 1420 In DWARF Version 5, if D does not have a ``DW_AT_location`` then 1421 ``DW_OP_call*`` is defined to have no effect. It is unclear that this is 1422 the right definition as a producer should be able to rely on using 1423 ``DW_OP_call*`` to get a location description for any non-\ 1424 ``DW_TAG_dwarf_procedure`` debugging information entries. Also, the 1425 producer should not be creating DWARF with ``DW_OP_call*`` to a 1426 ``DW_TAG_dwarf_procedure`` that does not have a ``DW_AT_location`` 1427 attribute. So, should this case be defined as an ill-formed DWARF 1428 expression? 1429 1430 *The* ``DW_TAG_dwarf_procedure`` *debugging information entry can be used to 1431 define DWARF procedures that can be called.* 1432 1433.. _amdgpu-dwarf-value-operations: 1434 1435A.2.5.4.3 Value Operations 1436########################## 1437 1438This section describes the operations that push values on the stack. 1439 1440Each value stack entry has a type and a literal value. It can represent a 1441literal value of any supported base type of the target architecture. The base 1442type specifies the size, encoding, and endianity of the literal value. 1443 1444The base type of value stack entries can be the distinguished generic type. 1445 1446.. _amdgpu-dwarf-literal-operations: 1447 1448A.2.5.4.3.1 Literal Operations 1449^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1450 1451.. note:: 1452 1453 This section replaces DWARF Version 5 section 2.5.1.1. 1454 1455The following operations all push a literal value onto the DWARF stack. 1456 1457Operations other than ``DW_OP_const_type`` push a value V with the generic type. 1458If V is larger than the generic type, then V is truncated to the generic type 1459size and the low-order bits used. 1460 14611. ``DW_OP_lit0``, ``DW_OP_lit1``, ..., ``DW_OP_lit31`` 1462 1463 ``DW_OP_lit<N>`` operations encode an unsigned literal value N from 0 1464 through 31, inclusive. They push the value N with the generic type. 1465 14662. ``DW_OP_const1u``, ``DW_OP_const2u``, ``DW_OP_const4u``, ``DW_OP_const8u`` 1467 1468 ``DW_OP_const<N>u`` operations have a single operand that is a 1, 2, 4, or 1469 8-byte unsigned integer constant U, respectively. They push the value U with 1470 the generic type. 1471 14723. ``DW_OP_const1s``, ``DW_OP_const2s``, ``DW_OP_const4s``, ``DW_OP_const8s`` 1473 1474 ``DW_OP_const<N>s`` operations have a single operand that is a 1, 2, 4, or 1475 8-byte signed integer constant S, respectively. They push the value S with 1476 the generic type. 1477 14784. ``DW_OP_constu`` 1479 1480 ``DW_OP_constu`` has a single unsigned LEB128 integer operand N. It pushes 1481 the value N with the generic type. 1482 14835. ``DW_OP_consts`` 1484 1485 ``DW_OP_consts`` has a single signed LEB128 integer operand N. It pushes the 1486 value N with the generic type. 1487 14886. ``DW_OP_constx`` 1489 1490 ``DW_OP_constx`` has a single unsigned LEB128 integer operand that 1491 represents a zero-based index into the ``.debug_addr`` section relative to 1492 the value of the ``DW_AT_addr_base`` attribute of the associated compilation 1493 unit. The value N in the ``.debug_addr`` section has the size of the generic 1494 type. It pushes the value N with the generic type. 1495 1496 *The* ``DW_OP_constx`` *operation is provided for constants that require 1497 link-time relocation but should not be interpreted by the consumer as a 1498 relocatable address (for example, offsets to thread-local storage).* 1499 15007. ``DW_OP_const_type`` 1501 1502 ``DW_OP_const_type`` has three operands. The first is an unsigned LEB128 1503 integer DR that represents the byte offset of a debugging information entry 1504 D relative to the beginning of the current compilation unit, that provides 1505 the type T of the constant value. The second is a 1-byte unsigned integral 1506 constant S. The third is a block of bytes B, with a length equal to S. 1507 1508 TS is the bit size of the type T. The least significant TS bits of B are 1509 interpreted as a value V of the type D. It pushes the value V with the type 1510 D. 1511 1512 The DWARF is ill-formed if D is not a ``DW_TAG_base_type`` debugging 1513 information entry in the current compilation unit, or if TS divided by 8 1514 (the byte size) and rounded up to a whole number is not equal to S. 1515 1516 *While the size of the byte block B can be inferred from the type D 1517 definition, it is encoded explicitly into the operation so that the 1518 operation can be parsed easily without reference to the* ``.debug_info`` 1519 *section.* 1520 15218. ``DW_OP_LLVM_push_lane`` *New* 1522 1523 ``DW_OP_LLVM_push_lane`` pushes the target architecture lane identifier of 1524 the current lane as a value with the generic type. 1525 1526 *For languages that are implemented using a SIMD or SIMT execution model, 1527 this is the lane number that corresponds to the source language thread of 1528 execution upon which the user is focused.* 1529 1530.. _amdgpu-dwarf-arithmetic-logical-operations: 1531 1532A.2.5.4.3.2 Arithmetic and Logical Operations 1533^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1534 1535.. note:: 1536 1537 This section is the same as DWARF Version 5 section 2.5.1.4. 1538 1539.. _amdgpu-dwarf-type-conversions-operations: 1540 1541A.2.5.4.3.3 Type Conversion Operations 1542^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1543 1544.. note:: 1545 1546 This section is the same as DWARF Version 5 section 2.5.1.6. 1547 1548.. _amdgpu-dwarf-general-operations: 1549 1550A.2.5.4.3.4 Special Value Operations 1551^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1552 1553.. note:: 1554 1555 This section replaces parts of DWARF Version 5 sections 2.5.1.2, 2.5.1.3, and 1556 2.5.1.7. 1557 1558There are these special value operations currently defined: 1559 15601. ``DW_OP_regval_type`` 1561 1562 ``DW_OP_regval_type`` has two operands. The first is an unsigned LEB128 1563 integer that represents a register number R. The second is an unsigned 1564 LEB128 integer DR that represents the byte offset of a debugging information 1565 entry D relative to the beginning of the current compilation unit, that 1566 provides the type T of the register value. 1567 1568 The operation is equivalent to performing ``DW_OP_regx R; DW_OP_deref_type 1569 DR``. 1570 1571 .. note:: 1572 1573 Should DWARF allow the type T to be a larger size than the size of the 1574 register R? Restricting a larger bit size avoids any issue of conversion 1575 as the, possibly truncated, bit contents of the register is simply 1576 interpreted as a value of T. If a conversion is wanted it can be done 1577 explicitly using a ``DW_OP_convert`` operation. 1578 1579 GDB has a per register hook that allows a target specific conversion on a 1580 register by register basis. It defaults to truncation of bigger registers. 1581 Removing use of the target hook does not cause any test failures in common 1582 architectures. If the compiler for a target architecture did want some 1583 form of conversion, including a larger result type, it could always 1584 explicitly used the ``DW_OP_convert`` operation. 1585 1586 If T is a larger type than the register size, then the default GDB 1587 register hook reads bytes from the next register (or reads out of bounds 1588 for the last register!). Removing use of the target hook does not cause 1589 any test failures in common architectures (except an illegal hand written 1590 assembly test). If a target architecture requires this behavior, these 1591 extensions allow a composite location description to be used to combine 1592 multiple registers. 1593 15942. ``DW_OP_deref`` 1595 1596 S is the bit size of the generic type divided by 8 (the byte size) and 1597 rounded up to a whole number. DR is the offset of a hypothetical debug 1598 information entry D in the current compilation unit for a base type of the 1599 generic type. 1600 1601 The operation is equivalent to performing ``DW_OP_deref_type S, DR``. 1602 16033. ``DW_OP_deref_size`` 1604 1605 ``DW_OP_deref_size`` has a single 1-byte unsigned integral constant that 1606 represents a byte result size S. 1607 1608 TS is the smaller of the generic type bit size and S scaled by 8 (the byte 1609 size). If TS is smaller than the generic type bit size then T is an unsigned 1610 integral type of bit size TS, otherwise T is the generic type. DR is the 1611 offset of a hypothetical debug information entry D in the current 1612 compilation unit for a base type T. 1613 1614 .. note:: 1615 1616 Truncating the value when S is larger than the generic type matches what 1617 GDB does. This allows the generic type size to not be an integral byte 1618 size. It does allow S to be arbitrarily large. Should S be restricted to 1619 the size of the generic type rounded up to a multiple of 8? 1620 1621 The operation is equivalent to performing ``DW_OP_deref_type S, DR``, except 1622 if T is not the generic type, the value V pushed is zero-extended to the 1623 generic type bit size and its type changed to the generic type. 1624 16254. ``DW_OP_deref_type`` 1626 1627 ``DW_OP_deref_type`` has two operands. The first is a 1-byte unsigned 1628 integral constant S. The second is an unsigned LEB128 integer DR that 1629 represents the byte offset of a debugging information entry D relative to 1630 the beginning of the current compilation unit, that provides the type T of 1631 the result value. 1632 1633 TS is the bit size of the type T. 1634 1635 *While the size of the pushed value V can be inferred from the type T, it is 1636 encoded explicitly as the operand S so that the operation can be parsed 1637 easily without reference to the* ``.debug_info`` *section.* 1638 1639 .. note:: 1640 1641 It is unclear why the operand S is needed. Unlike ``DW_OP_const_type``, 1642 the size is not needed for parsing. Any evaluation needs to get the base 1643 type T to push with the value to know its encoding and bit size. 1644 1645 It pops one stack entry that must be a location description L. 1646 1647 A value V of TS bits is retrieved from the location storage LS specified by 1648 one of the single location descriptions SL of L. 1649 1650 *If L, or the location description of any composite location description 1651 part that is a subcomponent of L, has more than one single location 1652 description, then any one of them can be selected as they are required to 1653 all have the same value. For any single location description SL, bits are 1654 retrieved from the associated storage location starting at the bit offset 1655 specified by SL. For a composite location description, the retrieved bits 1656 are the concatenation of the N bits from each composite location part PL, 1657 where N is limited to the size of PL.* 1658 1659 V is pushed on the stack with the type T. 1660 1661 .. note:: 1662 1663 This definition makes it an evaluation error if L is a register location 1664 description that has less than TS bits remaining in the register storage. 1665 Particularly since these extensions extend location descriptions to have 1666 a bit offset, it would be odd to define this as performing sign extension 1667 based on the type, or be target architecture dependent, as the number of 1668 remaining bits could be any number. This matches the GDB implementation 1669 for ``DW_OP_deref_type``. 1670 1671 These extensions define ``DW_OP_*breg*`` in terms of 1672 ``DW_OP_regval_type``. ``DW_OP_regval_type`` is defined in terms of 1673 ``DW_OP_regx``, which uses a 0 bit offset, and ``DW_OP_deref_type``. 1674 Therefore, it requires the register size to be greater or equal to the 1675 address size of the address space. This matches the GDB implementation for 1676 ``DW_OP_*breg*``. 1677 1678 The DWARF is ill-formed if D is not in the current compilation unit, D is 1679 not a ``DW_TAG_base_type`` debugging information entry, or if TS divided by 1680 8 (the byte size) and rounded up to a whole number is not equal to S. 1681 1682 .. note:: 1683 1684 This definition allows the base type to be a bit size since there seems no 1685 reason to restrict it. 1686 1687 It is an evaluation error if any bit of the value is retrieved from the 1688 undefined location storage or the offset of any bit exceeds the size of the 1689 location storage LS specified by any single location description SL of L. 1690 1691 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special 1692 rules concerning implicit location descriptions created by the 1693 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_implicit_aspace_pointer`` 1694 operations. 1695 16965. ``DW_OP_xderef`` *Deprecated* 1697 1698 ``DW_OP_xderef`` pops two stack entries. The first must be an integral type 1699 value that represents an address A. The second must be an integral type 1700 value that represents a target architecture specific address space 1701 identifier AS. 1702 1703 The operation is equivalent to performing ``DW_OP_swap; 1704 DW_OP_LLVM_form_aspace_address; DW_OP_deref``. The value V retrieved is left 1705 on the stack with the generic type. 1706 1707 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address`` 1708 *operation can be used and provides greater expressiveness.* 1709 17106. ``DW_OP_xderef_size`` *Deprecated* 1711 1712 ``DW_OP_xderef_size`` has a single 1-byte unsigned integral constant that 1713 represents a byte result size S. 1714 1715 It pops two stack entries. The first must be an integral type value that 1716 represents an address A. The second must be an integral type value that 1717 represents a target architecture specific address space identifier AS. 1718 1719 The operation is equivalent to performing ``DW_OP_swap; 1720 DW_OP_LLVM_form_aspace_address; DW_OP_deref_size S``. The zero-extended 1721 value V retrieved is left on the stack with the generic type. 1722 1723 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address`` 1724 *operation can be used and provides greater expressiveness.* 1725 17267. ``DW_OP_xderef_type`` *Deprecated* 1727 1728 ``DW_OP_xderef_type`` has two operands. The first is a 1-byte unsigned 1729 integral constant S. The second operand is an unsigned LEB128 integer DR 1730 that represents the byte offset of a debugging information entry D relative 1731 to the beginning of the current compilation unit, that provides the type T 1732 of the result value. 1733 1734 It pops two stack entries. The first must be an integral type value that 1735 represents an address A. The second must be an integral type value that 1736 represents a target architecture specific address space identifier AS. 1737 1738 The operation is equivalent to performing ``DW_OP_swap; 1739 DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S DR``. The value V 1740 retrieved is left on the stack with the type T. 1741 1742 *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address`` 1743 *operation can be used and provides greater expressiveness.* 1744 17458. ``DW_OP_entry_value`` *Deprecated* 1746 1747 ``DW_OP_entry_value`` pushes the value of an expression that is evaluated in 1748 the context of the calling frame. 1749 1750 *It may be used to determine the value of arguments on entry to the current 1751 call frame provided they are not clobbered.* 1752 1753 It has two operands. The first is an unsigned LEB128 integer S. The second 1754 is a block of bytes, with a length equal S, interpreted as a DWARF 1755 operation expression E. 1756 1757 E is evaluated with the current context, except the result kind is 1758 unspecified, the call frame is the one that called the current frame, the 1759 program location is the call site in the calling frame, the object is 1760 unspecified, and the initial stack is empty. The calling frame information 1761 is obtained by virtually unwinding the current call frame using the call 1762 frame information (see :ref:`amdgpu-dwarf-call-frame-information`). 1763 1764 If the result of E is a location description L (see 1765 :ref:`amdgpu-dwarf-register-location-description-operations`), and the last 1766 operation executed by E is a ``DW_OP_reg*`` for register R with a target 1767 architecture specific base type of T, then the contents of the register are 1768 retrieved as if a ``DW_OP_deref_type DR`` operation was performed where DR 1769 is the offset of a hypothetical debug information entry in the current 1770 compilation unit for T. The resulting value V s pushed on the stack. 1771 1772 *Using* ``DW_OP_reg*`` *provides a more compact form for the case where the 1773 value was in a register on entry to the subprogram.* 1774 1775 .. note:: 1776 1777 It is unclear how this provides a more compact expression, as 1778 ``DW_OP_regval_type`` could be used which is marginally larger. 1779 1780 If the result of E is a value V, then V is pushed on the stack. 1781 1782 Otherwise, the DWARF expression is ill-formed. 1783 1784 *The* ``DW_OP_entry_value`` *operation is deprecated as its main usage is 1785 provided by other means. DWARF Version 5 added the* 1786 ``DW_TAG_call_site_parameter`` *debugger information entry for call sites 1787 that has* ``DW_AT_call_value``\ *,* ``DW_AT_call_data_location``\ *, and* 1788 ``DW_AT_call_data_value`` *attributes that provide DWARF expressions to 1789 compute actual parameter values at the time of the call, and requires the 1790 producer to ensure the expressions are valid to evaluate even when virtually 1791 unwound. The* ``DW_OP_LLVM_call_frame_entry_reg`` *operation provides access 1792 to registers in the virtually unwound calling frame.* 1793 1794 .. note:: 1795 1796 GDB only implements ``DW_OP_entry_value`` when E is exactly 1797 ``DW_OP_reg*`` or ``DW_OP_breg*; DW_OP_deref*``. 1798 1799.. _amdgpu-dwarf-location-description-operations: 1800 1801A.2.5.4.4 Location Description Operations 1802######################################### 1803 1804This section describes the operations that push location descriptions on the 1805stack. 1806 1807.. _amdgpu-dwarf-general-location-description-operations: 1808 1809A.2.5.4.4.1 General Location Description Operations 1810^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1811 1812.. note:: 1813 1814 This section replaces part of DWARF Version 5 section 2.5.1.3. 1815 18161. ``DW_OP_LLVM_offset`` *New* 1817 1818 ``DW_OP_LLVM_offset`` pops two stack entries. The first must be an integral 1819 type value that represents a byte displacement B. The second must be a 1820 location description L. 1821 1822 It adds the value of B scaled by 8 (the byte size) to the bit offset of each 1823 single location description SL of L, and pushes the updated L. 1824 1825 It is an evaluation error if the updated bit offset of any SL is less than 0 1826 or greater than or equal to the size of the location storage specified by 1827 SL. 1828 18292. ``DW_OP_LLVM_offset_uconst`` *New* 1830 1831 ``DW_OP_LLVM_offset_uconst`` has a single unsigned LEB128 integer operand 1832 that represents a byte displacement B. 1833 1834 The operation is equivalent to performing ``DW_OP_constu B; 1835 DW_OP_LLVM_offset``. 1836 1837 *This operation is supplied specifically to be able to encode more field 1838 displacements in two bytes than can be done with* ``DW_OP_lit*; 1839 DW_OP_LLVM_offset``\ *.* 1840 1841 .. note:: 1842 1843 Should this be named ``DW_OP_LLVM_offset_uconst`` to match 1844 ``DW_OP_plus_uconst``, or ``DW_OP_LLVM_offset_constu`` to match 1845 ``DW_OP_constu``? 1846 18473. ``DW_OP_LLVM_bit_offset`` *New* 1848 1849 ``DW_OP_LLVM_bit_offset`` pops two stack entries. The first must be an 1850 integral type value that represents a bit displacement B. The second must be 1851 a location description L. 1852 1853 It adds the value of B to the bit offset of each single location description 1854 SL of L, and pushes the updated L. 1855 1856 It is an evaluation error if the updated bit offset of any SL is less than 0 1857 or greater than or equal to the size of the location storage specified by 1858 SL. 1859 18604. ``DW_OP_push_object_address`` 1861 1862 ``DW_OP_push_object_address`` pushes the location description L of the 1863 current object. 1864 1865 *This object may correspond to an independent variable that is part of a 1866 user presented expression that is being evaluated. The object location 1867 description may be determined from the variable's own debugging information 1868 entry or it may be a component of an array, structure, or class whose 1869 address has been dynamically determined by an earlier step during user 1870 expression evaluation.* 1871 1872 *This operation provides explicit functionality (especially for arrays 1873 involving descriptors) that is analogous to the implicit push of the base 1874 location description of a structure prior to evaluation of a* 1875 ``DW_AT_data_member_location`` *to access a data member of a structure.* 1876 1877 .. note:: 1878 1879 This operation could be removed and the object location description 1880 specified as the initial stack as for ``DW_AT_data_member_location``. 1881 1882 Or this operation could be used instead of needing to specify an initial 1883 stack. The latter approach is more composable as access to the object may 1884 be needed at any point of the expression, and passing it as the initial 1885 stack requires the entire expression to be aware where on the stack it is. 1886 If this were done, ``DW_AT_use_location`` would require a 1887 ``DW_OP_push_object2_address`` operation for the second object. 1888 1889 Or a more general way to pass an arbitrary number of arguments in and an 1890 operation to get the Nth one such as ``DW_OP_arg N``. A vector of 1891 arguments would then be passed in the expression context rather than an 1892 initial stack. This could also resolve the issues with ``DW_OP_call*`` by 1893 allowing a specific number of arguments passed in and returned to be 1894 specified. The ``DW_OP_call*`` operation could then always execute on a 1895 separate stack: the number of arguments would be specified in a new call 1896 operation and taken from the callers stack, and similarly the number of 1897 return results specified and copied from the called stack back to the 1898 callee stack when the called expression was complete. 1899 1900 The only attribute that specifies a current object is 1901 ``DW_AT_data_location`` so the non-normative text seems to overstate how 1902 this is being used. Or are there other attributes that need to state they 1903 pass an object? 1904 19055. ``DW_OP_LLVM_call_frame_entry_reg`` *New* 1906 1907 ``DW_OP_LLVM_call_frame_entry_reg`` has a single unsigned LEB128 integer 1908 operand that represents a target architecture register number R. 1909 1910 It pushes a location description L that holds the value of register R on 1911 entry to the current subprogram as defined by the call frame information 1912 (see :ref:`amdgpu-dwarf-call-frame-information`). 1913 1914 *If there is no call frame information defined, then the default rules for 1915 the target architecture are used. If the register rule is* undefined\ *, then 1916 the undefined location description is pushed. If the register rule is* same 1917 value\ *, then a register location description for R is pushed.* 1918 1919.. _amdgpu-dwarf-undefined-location-description-operations: 1920 1921A.2.5.4.4.2 Undefined Location Description Operations 1922^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1923 1924.. note:: 1925 1926 This section replaces DWARF Version 5 section 2.6.1.1.1. 1927 1928*The undefined location storage represents a piece or all of an object that is 1929present in the source but not in the object code (perhaps due to optimization). 1930Neither reading nor writing to the undefined location storage is meaningful.* 1931 1932An undefined location description specifies the undefined location storage. 1933There is no concept of the size of the undefined location storage, nor of a bit 1934offset for an undefined location description. The ``DW_OP_LLVM_*offset`` 1935operations leave an undefined location description unchanged. The 1936``DW_OP_*piece`` operations can explicitly or implicitly specify an undefined 1937location description, allowing any size and offset to be specified, and results 1938in a part with all undefined bits. 1939 19401. ``DW_OP_LLVM_undefined`` *New* 1941 1942 ``DW_OP_LLVM_undefined`` pushes a location description L that comprises one 1943 undefined location description SL. 1944 1945.. _amdgpu-dwarf-memory-location-description-operations: 1946 1947A.2.5.4.4.3 Memory Location Description Operations 1948^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1949 1950.. note:: 1951 1952 This section replaces parts of DWARF Version 5 section 2.5.1.1, 2.5.1.2, 1953 2.5.1.3, and 2.6.1.1.2. 1954 1955Each of the target architecture specific address spaces has a corresponding 1956memory location storage that denotes the linear addressable memory of that 1957address space. The size of each memory location storage corresponds to the range 1958of the addresses in the corresponding address space. 1959 1960*It is target architecture defined how address space location storage maps to 1961target architecture physical memory. For example, they may be independent 1962memory, or more than one location storage may alias the same physical memory 1963possibly at different offsets and with different interleaving. The mapping may 1964also be dictated by the source language address classes.* 1965 1966A memory location description specifies a memory location storage. The bit 1967offset corresponds to a bit position within a byte of the memory. Bits accessed 1968using a memory location description, access the corresponding target 1969architecture memory starting at the bit position within the byte specified by 1970the bit offset. 1971 1972A memory location description that has a bit offset that is a multiple of 8 (the 1973byte size) is defined to be a byte address memory location description. It has a 1974memory byte address A that is equal to the bit offset divided by 8. 1975 1976A memory location description that does not have a bit offset that is a multiple 1977of 8 (the byte size) is defined to be a bit field memory location description. 1978It has a bit position B equal to the bit offset modulo 8, and a memory byte 1979address A equal to the bit offset minus B that is then divided by 8. 1980 1981The address space AS of a memory location description is defined to be the 1982address space that corresponds to the memory location storage associated with 1983the memory location description. 1984 1985A location description that is comprised of one byte address memory location 1986description SL is defined to be a memory byte address location description. It 1987has a byte address equal to A and an address space equal to AS of the 1988corresponding SL. 1989 1990``DW_ASPACE_none`` is defined as the target architecture default address space. 1991 1992If a stack entry is required to be a location description, but it is a value V 1993with the generic type, then it is implicitly converted to a location description 1994L with one memory location description SL. SL specifies the memory location 1995storage that corresponds to the target architecture default address space with a 1996bit offset equal to V scaled by 8 (the byte size). 1997 1998.. note:: 1999 2000 If it is wanted to allow any integral type value to be implicitly converted to 2001 a memory location description in the target architecture default address 2002 space: 2003 2004 If a stack entry is required to be a location description, but is a value V 2005 with an integral type, then it is implicitly converted to a location 2006 description L with a one memory location description SL. If the type size of 2007 V is less than the generic type size, then the value V is zero extended to 2008 the size of the generic type. The least significant generic type size bits 2009 are treated as an unsigned value to be used as an address A. SL specifies 2010 memory location storage corresponding to the target architecture default 2011 address space with a bit offset equal to A scaled by 8 (the byte size). 2012 2013 The implicit conversion could also be defined as target architecture specific. 2014 For example, GDB checks if V is an integral type. If it is not it gives an 2015 error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a 2016 hook function, then it is called. The target specific hook function can modify 2017 the 64-bit value, possibly sign extending based on the original value type. 2018 Finally, GDB treats the 64-bit value V as a memory location address. 2019 2020If a stack entry is required to be a location description, but it is an implicit 2021pointer value IPV with the target architecture default address space, then it is 2022implicitly converted to a location description with one single location 2023description specified by IPV. See 2024:ref:`amdgpu-dwarf-implicit-location-description-operations`. 2025 2026.. note:: 2027 2028 Is this rule required for DWARF Version 5 backwards compatibility? If not, it 2029 can be eliminated, and the producer can use 2030 ``DW_OP_LLVM_form_aspace_address``. 2031 2032If a stack entry is required to be a value, but it is a location description L 2033with one memory location description SL in the target architecture default 2034address space with a bit offset B that is a multiple of 8, then it is implicitly 2035converted to a value equal to B divided by 8 (the byte size) with the generic 2036type. 2037 20381. ``DW_OP_addr`` 2039 2040 ``DW_OP_addr`` has a single byte constant value operand, which has the size 2041 of the generic type, that represents an address A. 2042 2043 It pushes a location description L with one memory location description SL 2044 on the stack. SL specifies the memory location storage corresponding to the 2045 target architecture default address space with a bit offset equal to A 2046 scaled by 8 (the byte size). 2047 2048 *If the DWARF is part of a code object, then A may need to be relocated. For 2049 example, in the ELF code object format, A must be adjusted by the difference 2050 between the ELF segment virtual address and the virtual address at which the 2051 segment is loaded.* 2052 20532. ``DW_OP_addrx`` 2054 2055 ``DW_OP_addrx`` has a single unsigned LEB128 integer operand that represents 2056 a zero-based index into the ``.debug_addr`` section relative to the value of 2057 the ``DW_AT_addr_base`` attribute of the associated compilation unit. The 2058 address value A in the ``.debug_addr`` section has the size of the generic 2059 type. 2060 2061 It pushes a location description L with one memory location description SL 2062 on the stack. SL specifies the memory location storage corresponding to the 2063 target architecture default address space with a bit offset equal to A 2064 scaled by 8 (the byte size). 2065 2066 *If the DWARF is part of a code object, then A may need to be relocated. For 2067 example, in the ELF code object format, A must be adjusted by the difference 2068 between the ELF segment virtual address and the virtual address at which the 2069 segment is loaded.* 2070 20713. ``DW_OP_LLVM_form_aspace_address`` *New* 2072 2073 ``DW_OP_LLVM_form_aspace_address`` pops top two stack entries. The first 2074 must be an integral type value that represents a target architecture 2075 specific address space identifier AS. The second must be an integral type 2076 value that represents an address A. 2077 2078 The address size S is defined as the address bit size of the target 2079 architecture specific address space that corresponds to AS. 2080 2081 A is adjusted to S bits by zero extending if necessary, and then treating 2082 the least significant S bits as an unsigned value A'. 2083 2084 It pushes a location description L with one memory location description SL 2085 on the stack. SL specifies the memory location storage LS that corresponds 2086 to AS with a bit offset equal to A' scaled by 8 (the byte size). 2087 2088 If AS is an address space that is specific to context elements, then LS 2089 corresponds to the location storage associated with the current context. 2090 2091 *For example, if AS is for per thread storage then LS is the location 2092 storage for the current thread. For languages that are implemented using a 2093 SIMD or SIMT execution model, then if AS is for per lane storage then LS is 2094 the location storage for the current lane of the current thread. Therefore, 2095 if L is accessed by an operation, the location storage selected when the 2096 location description was created is accessed, and not the location storage 2097 associated with the current context of the access operation.* 2098 2099 The DWARF expression is ill-formed if AS is not one of the values defined by 2100 the target architecture specific ``DW_ASPACE_*`` values. 2101 2102 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special 2103 rules concerning implicit pointer values produced by dereferencing implicit 2104 location descriptions created by the ``DW_OP_implicit_pointer`` and 2105 ``DW_OP_LLVM_implicit_aspace_pointer`` operations. 2106 21074. ``DW_OP_form_tls_address`` 2108 2109 ``DW_OP_form_tls_address`` pops one stack entry that must be an integral 2110 type value and treats it as a thread-local storage address TA. 2111 2112 It pushes a location description L with one memory location description SL 2113 on the stack. SL is the target architecture specific memory location 2114 description that corresponds to the thread-local storage address TA. 2115 2116 The meaning of the thread-local storage address TA is defined by the 2117 run-time environment. If the run-time environment supports multiple 2118 thread-local storage blocks for a single thread, then the block 2119 corresponding to the executable or shared library containing this DWARF 2120 expression is used. 2121 2122 *Some implementations of C, C++, Fortran, and other languages support a 2123 thread-local storage class. Variables with this storage class have distinct 2124 values and addresses in distinct threads, much as automatic variables have 2125 distinct values and addresses in each subprogram invocation. Typically, 2126 there is a single block of storage containing all thread-local variables 2127 declared in the main executable, and a separate block for the variables 2128 declared in each shared library. Each thread-local variable can then be 2129 accessed in its block using an identifier. This identifier is typically a 2130 byte offset into the block and pushed onto the DWARF stack by one of the* 2131 ``DW_OP_const*`` *operations prior to the* ``DW_OP_form_tls_address`` 2132 *operation. Computing the address of the appropriate block can be complex 2133 (in some cases, the compiler emits a function call to do it), and difficult 2134 to describe using ordinary DWARF location descriptions. Instead of forcing 2135 complex thread-local storage calculations into the DWARF expressions, the* 2136 ``DW_OP_form_tls_address`` *allows the consumer to perform the computation 2137 based on the target architecture specific run-time environment.* 2138 21395. ``DW_OP_call_frame_cfa`` 2140 2141 ``DW_OP_call_frame_cfa`` pushes the location description L of the Canonical 2142 Frame Address (CFA) of the current subprogram, obtained from the call frame 2143 information on the stack. See :ref:`amdgpu-dwarf-call-frame-information`. 2144 2145 *Although the value of the* ``DW_AT_frame_base`` *attribute of the debugger 2146 information entry corresponding to the current subprogram can be computed 2147 using a location list expression, in some cases this would require an 2148 extensive location list because the values of the registers used in 2149 computing the CFA change during a subprogram execution. If the call frame 2150 information is present, then it already encodes such changes, and it is 2151 space efficient to reference that using the* ``DW_OP_call_frame_cfa`` 2152 *operation.* 2153 21546. ``DW_OP_fbreg`` 2155 2156 ``DW_OP_fbreg`` has a single signed LEB128 integer operand that represents a 2157 byte displacement B. 2158 2159 The location description L for the *frame base* of the current subprogram is 2160 obtained from the ``DW_AT_frame_base`` attribute of the debugger information 2161 entry corresponding to the current subprogram as described in 2162 :ref:`amdgpu-dwarf-low-level-information`. 2163 2164 The location description L is updated as if the ``DW_OP_LLVM_offset_uconst 2165 B`` operation was applied. The updated L is pushed on the stack. 2166 21677. ``DW_OP_breg0``, ``DW_OP_breg1``, ..., ``DW_OP_breg31`` 2168 2169 The ``DW_OP_breg<N>`` operations encode the numbers of up to 32 registers, 2170 numbered from 0 through 31, inclusive. The register number R corresponds to 2171 the N in the operation name. 2172 2173 They have a single signed LEB128 integer operand that represents a byte 2174 displacement B. 2175 2176 The address space identifier AS is defined as the one corresponding to the 2177 target architecture specific default address space. 2178 2179 The address size S is defined as the address bit size of the target 2180 architecture specific address space corresponding to AS. 2181 2182 The contents of the register specified by R are retrieved as if a 2183 ``DW_OP_regval_type R, DR`` operation was performed where DR is the offset 2184 of a hypothetical debug information entry in the current compilation unit 2185 for an unsigned integral base type of size S bits. B is added and the least 2186 significant S bits are treated as an unsigned value to be used as an address 2187 A. 2188 2189 They push a location description L comprising one memory location 2190 description LS on the stack. LS specifies the memory location storage that 2191 corresponds to AS with a bit offset equal to A scaled by 8 (the byte size). 2192 21938. ``DW_OP_bregx`` 2194 2195 ``DW_OP_bregx`` has two operands. The first is an unsigned LEB128 integer 2196 that represents a register number R. The second is a signed LEB128 2197 integer that represents a byte displacement B. 2198 2199 The action is the same as for ``DW_OP_breg<N>``, except that R is used as 2200 the register number and B is used as the byte displacement. 2201 22029. ``DW_OP_LLVM_aspace_bregx`` *New* 2203 2204 ``DW_OP_LLVM_aspace_bregx`` has two operands. The first is an unsigned 2205 LEB128 integer that represents a register number R. The second is a signed 2206 LEB128 integer that represents a byte displacement B. It pops one stack 2207 entry that is required to be an integral type value that represents a target 2208 architecture specific address space identifier AS. 2209 2210 The action is the same as for ``DW_OP_breg<N>``, except that R is used as 2211 the register number, B is used as the byte displacement, and AS is used as 2212 the address space identifier. 2213 2214 The DWARF expression is ill-formed if AS is not one of the values defined by 2215 the target architecture specific ``DW_ASPACE_*`` values. 2216 2217 .. note:: 2218 2219 Could also consider adding ``DW_OP_aspace_breg0, DW_OP_aspace_breg1, ..., 2220 DW_OP_aspace_bref31`` which would save encoding size. 2221 2222.. _amdgpu-dwarf-register-location-description-operations: 2223 2224A.2.5.4.4.4 Register Location Description Operations 2225^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2226 2227.. note:: 2228 2229 This section replaces DWARF Version 5 section 2.6.1.1.3. 2230 2231There is a register location storage that corresponds to each of the target 2232architecture registers. The size of each register location storage corresponds 2233to the size of the corresponding target architecture register. 2234 2235A register location description specifies a register location storage. The bit 2236offset corresponds to a bit position within the register. Bits accessed using a 2237register location description access the corresponding target architecture 2238register starting at the specified bit offset. 2239 22401. ``DW_OP_reg0``, ``DW_OP_reg1``, ..., ``DW_OP_reg31`` 2241 2242 ``DW_OP_reg<N>`` operations encode the numbers of up to 32 registers, 2243 numbered from 0 through 31, inclusive. The target architecture register 2244 number R corresponds to the N in the operation name. 2245 2246 The operation is equivalent to performing ``DW_OP_regx R``. 2247 22482. ``DW_OP_regx`` 2249 2250 ``DW_OP_regx`` has a single unsigned LEB128 integer operand that represents 2251 a target architecture register number R. 2252 2253 If the current call frame is the top call frame, it pushes a location 2254 description L that specifies one register location description SL on the 2255 stack. SL specifies the register location storage that corresponds to R with 2256 a bit offset of 0 for the current thread. 2257 2258 If the current call frame is not the top call frame, call frame information 2259 (see :ref:`amdgpu-dwarf-call-frame-information`) is used to determine the 2260 location description that holds the register for the current call frame and 2261 current program location of the current thread. The resulting location 2262 description L is pushed. 2263 2264 *Note that if call frame information is used, the resulting location 2265 description may be register, memory, or undefined.* 2266 2267 *An implementation may evaluate the call frame information immediately, or 2268 may defer evaluation until L is accessed by an operation. If evaluation is 2269 deferred, R and the current context can be recorded in L. When accessed, the 2270 recorded context is used to evaluate the call frame information, not the 2271 current context of the access operation.* 2272 2273*These operations obtain a register location. To fetch the contents of a 2274register, it is necessary to use* ``DW_OP_regval_type``\ *, use one of the* 2275``DW_OP_breg*`` *register-based addressing operations, or use* ``DW_OP_deref*`` 2276*on a register location description.* 2277 2278.. _amdgpu-dwarf-implicit-location-description-operations: 2279 2280A.2.5.4.4.5 Implicit Location Description Operations 2281^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2282 2283.. note:: 2284 2285 This section replaces DWARF Version 5 section 2.6.1.1.4. 2286 2287Implicit location storage represents a piece or all of an object which has no 2288actual location in the program but whose contents are nonetheless known, either 2289as a constant or can be computed from other locations and values in the program. 2290 2291An implicit location description specifies an implicit location storage. The bit 2292offset corresponds to a bit position within the implicit location storage. Bits 2293accessed using an implicit location description, access the corresponding 2294implicit storage value starting at the bit offset. 2295 22961. ``DW_OP_implicit_value`` 2297 2298 ``DW_OP_implicit_value`` has two operands. The first is an unsigned LEB128 2299 integer that represents a byte size S. The second is a block of bytes with a 2300 length equal to S treated as a literal value V. 2301 2302 An implicit location storage LS is created with the literal value V and a 2303 size of S. 2304 2305 It pushes location description L with one implicit location description SL 2306 on the stack. SL specifies LS with a bit offset of 0. 2307 23082. ``DW_OP_stack_value`` 2309 2310 ``DW_OP_stack_value`` pops one stack entry that must be a value V. 2311 2312 An implicit location storage LS is created with the literal value V using 2313 the size, encoding, and enianity specified by V's base type. 2314 2315 It pushes a location description L with one implicit location description SL 2316 on the stack. SL specifies LS with a bit offset of 0. 2317 2318 *The* ``DW_OP_stack_value`` *operation specifies that the object does not 2319 exist in memory, but its value is nonetheless known. In this form, the 2320 location description specifies the actual value of the object, rather than 2321 specifying the memory or register storage that holds the value.* 2322 2323 See :ref:`amdgpu-dwarf-implicit-location-description-operations` for special 2324 rules concerning implicit pointer values produced by dereferencing implicit 2325 location descriptions created by the ``DW_OP_implicit_pointer`` and 2326 ``DW_OP_LLVM_implicit_aspace_pointer`` operations. 2327 2328 .. note:: 2329 2330 Since location descriptions are allowed on the stack, the 2331 ``DW_OP_stack_value`` operation no longer terminates the DWARF operation 2332 expression execution as in DWARF Version 5. 2333 23343. ``DW_OP_implicit_pointer`` 2335 2336 *An optimizing compiler may eliminate a pointer, while still retaining the 2337 value that the pointer addressed.* ``DW_OP_implicit_pointer`` *allows a 2338 producer to describe this value.* 2339 2340 ``DW_OP_implicit_pointer`` *specifies an object is a pointer to the target 2341 architecture default address space that cannot be represented as a real 2342 pointer, even though the value it would point to can be described. In this 2343 form, the location description specifies a debugging information entry that 2344 represents the actual location description of the object to which the 2345 pointer would point. Thus, a consumer of the debug information would be able 2346 to access the dereferenced pointer, even when it cannot access the pointer 2347 itself.* 2348 2349 ``DW_OP_implicit_pointer`` has two operands. The first operand is a 4-byte 2350 unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in 2351 the 64-bit DWARF format, that represents the byte offset DR of a debugging 2352 information entry D relative to the beginning of the ``.debug_info`` section 2353 that contains the current compilation unit. The second operand is a signed 2354 LEB128 integer that represents a byte displacement B. 2355 2356 *Note that D may not be in the current compilation unit.* 2357 2358 *The first operand interpretation is exactly like that for* 2359 ``DW_FORM_ref_addr``\ *.* 2360 2361 The address space identifier AS is defined as the one corresponding to the 2362 target architecture specific default address space. 2363 2364 The address size S is defined as the address bit size of the target 2365 architecture specific address space corresponding to AS. 2366 2367 An implicit location storage LS is created with the debugging information 2368 entry D, address space AS, and size of S. 2369 2370 It pushes a location description L that comprises one implicit location 2371 description SL on the stack. SL specifies LS with a bit offset of 0. 2372 2373 It is an evaluation error if a ``DW_OP_deref*`` operation pops a location 2374 description L', and retrieves S bits, such that any retrieved bits come from 2375 an implicit location storage that is the same as LS, unless both the 2376 following conditions are met: 2377 2378 1. All retrieved bits come from an implicit location description that 2379 refers to an implicit location storage that is the same as LS. 2380 2381 *Note that all bits do not have to come from the same implicit location 2382 description, as L' may involve composite location descriptors.* 2383 2384 2. The bits come from consecutive ascending offsets within their respective 2385 implicit location storage. 2386 2387 *These rules are equivalent to retrieving the complete contents of LS.* 2388 2389 If both the above conditions are met, then the value V pushed by the 2390 ``DW_OP_deref*`` operation is an implicit pointer value IPV with a target 2391 architecture specific address space of AS, a debugging information entry of 2392 D, and a base type of T. If AS is the target architecture default address 2393 space, then T is the generic type. Otherwise, T is a target architecture 2394 specific integral type with a bit size equal to S. 2395 2396 If IPV is either implicitly converted to a location description (only done 2397 if AS is the target architecture default address space) or used by 2398 ``DW_OP_LLVM_form_aspace_address`` (only done if the address space popped by 2399 ``DW_OP_LLVM_form_aspace_address`` is AS), then the resulting location 2400 description RL is: 2401 2402 * If D has a ``DW_AT_location`` attribute, the DWARF expression E from the 2403 ``DW_AT_location`` attribute is evaluated with the current context, except 2404 that the result kind is a location description, the compilation unit is 2405 the one that contains D, the object is unspecified, and the initial stack 2406 is empty. RL is the expression result. 2407 2408 *Note that E is evaluated with the context of the expression accessing 2409 IPV, and not the context of the expression that contained the* 2410 ``DW_OP_implicit_pointer`` *or* ``DW_OP_LLVM_aspace_implicit_pointer`` 2411 *operation that created L.* 2412 2413 * If D has a ``DW_AT_const_value`` attribute, then an implicit location 2414 storage RLS is created from the ``DW_AT_const_value`` attribute's value 2415 with a size matching the size of the ``DW_AT_const_value`` attribute's 2416 value. RL comprises one implicit location description SRL. SRL specifies 2417 RLS with a bit offset of 0. 2418 2419 .. note:: 2420 2421 If using ``DW_AT_const_value`` for variables and formal parameters is 2422 deprecated and instead ``DW_AT_location`` is used with an implicit 2423 location description, then this rule would not be required. 2424 2425 * Otherwise, it is an evaluation error. 2426 2427 The bit offset of RL is updated as if the ``DW_OP_LLVM_offset_uconst B`` 2428 operation was applied. 2429 2430 If a ``DW_OP_stack_value`` operation pops a value that is the same as IPV, 2431 then it pushes a location description that is the same as L. 2432 2433 It is an evaluation error if LS or IPV is accessed in any other manner. 2434 2435 *The restrictions on how an implicit pointer location description created 2436 by* ``DW_OP_implicit_pointer`` *and* ``DW_OP_LLVM_aspace_implicit_pointer`` 2437 *can be used are to simplify the DWARF consumer. Similarly, for an implicit 2438 pointer value created by* ``DW_OP_deref*`` *and* ``DW_OP_stack_value``\ *.* 2439 24404. ``DW_OP_LLVM_aspace_implicit_pointer`` *New* 2441 2442 ``DW_OP_LLVM_aspace_implicit_pointer`` has two operands that are the same as 2443 for ``DW_OP_implicit_pointer``. 2444 2445 It pops one stack entry that must be an integral type value that represents 2446 a target architecture specific address space identifier AS. 2447 2448 The location description L that is pushed on the stack is the same as for 2449 ``DW_OP_implicit_pointer``, except that the address space identifier used is 2450 AS. 2451 2452 The DWARF expression is ill-formed if AS is not one of the values defined by 2453 the target architecture specific ``DW_ASPACE_*`` values. 2454 2455 .. note:: 2456 2457 This definition of ``DW_OP_LLVM_aspace_implicit_pointer`` may change when 2458 full support for address classes is added as required for languages such 2459 as OpenCL/SyCL. 2460 2461*Typically a* ``DW_OP_implicit_pointer`` *or* 2462``DW_OP_LLVM_aspace_implicit_pointer`` *operation is used in a DWARF expression 2463E*\ :sub:`1` *of a* ``DW_TAG_variable`` *or* ``DW_TAG_formal_parameter`` 2464*debugging information entry D*\ :sub:`1`\ *'s* ``DW_AT_location`` *attribute. 2465The debugging information entry referenced by the* ``DW_OP_implicit_pointer`` 2466*or* ``DW_OP_LLVM_aspace_implicit_pointer`` *operations is typically itself a* 2467``DW_TAG_variable`` *or* ``DW_TAG_formal_parameter`` *debugging information 2468entry D*\ :sub:`2` *whose* ``DW_AT_location`` *attribute gives a second DWARF 2469expression E*\ :sub:`2`\ *.* 2470 2471*D*\ :sub:`1` *and E*\ :sub:`1` *are describing the location of a pointer type 2472object. D*\ :sub:`2` *and E*\ :sub:`2` *are describing the location of the 2473object pointed to by that pointer object.* 2474 2475*However, D*\ :sub:`2` *may be any debugging information entry that contains a* 2476``DW_AT_location`` *or* ``DW_AT_const_value`` *attribute (for example,* 2477``DW_TAG_dwarf_procedure``\ *). By using E*\ :sub:`2`\ *, a consumer can 2478reconstruct the value of the object when asked to dereference the pointer 2479described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` *or* 2480``DW_OP_LLVM_aspace_implicit_pointer`` *operation.* 2481 2482.. _amdgpu-dwarf-composite-location-description-operations: 2483 2484A.2.5.4.4.6 Composite Location Description Operations 2485^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2486 2487.. note:: 2488 2489 This section replaces DWARF Version 5 section 2.6.1.2. 2490 2491A composite location storage represents an object or value which may be 2492contained in part of another location storage or contained in parts of more 2493than one location storage. 2494 2495Each part has a part location description L and a part bit size S. L can have 2496one or more single location descriptions SL. If there are more than one SL then 2497that indicates that part is located in more than one place. The bits of each 2498place of the part comprise S contiguous bits from the location storage LS 2499specified by SL starting at the bit offset specified by SL. All the bits must 2500be within the size of LS or the DWARF expression is ill-formed. 2501 2502A composite location storage can have zero or more parts. The parts are 2503contiguous such that the zero-based location storage bit index will range over 2504each part with no gaps between them. Therefore, the size of a composite location 2505storage is the sum of the size of its parts. The DWARF expression is ill-formed 2506if the size of the contiguous location storage is larger than the size of the 2507memory location storage corresponding to the largest target architecture 2508specific address space. 2509 2510A composite location description specifies a composite location storage. The bit 2511offset corresponds to a bit position within the composite location storage. 2512 2513There are operations that create a composite location storage. 2514 2515There are other operations that allow a composite location storage to be 2516incrementally created. Each part is created by a separate operation. There may 2517be one or more operations to create the final composite location storage. A 2518series of such operations describes the parts of the composite location storage 2519that are in the order that the associated part operations are executed. 2520 2521To support incremental creation, a composite location storage can be in an 2522incomplete state. When an incremental operation operates on an incomplete 2523composite location storage, it adds a new part, otherwise it creates a new 2524composite location storage. The ``DW_OP_LLVM_piece_end`` operation explicitly 2525makes an incomplete composite location storage complete. 2526 2527A composite location description that specifies a composite location storage 2528that is incomplete is termed an incomplete composite location description. A 2529composite location description that specifies a composite location storage that 2530is complete is termed a complete composite location description. 2531 2532If the top stack entry is a location description that has one incomplete 2533composite location description SL after the execution of an operation expression 2534has completed, SL is converted to a complete composite location description. 2535 2536*Note that this conversion does not happen after the completion of an operation 2537expression that is evaluated on the same stack by the* ``DW_OP_call*`` 2538*operations. Such executions are not a separate evaluation of an operation 2539expression, but rather the continued evaluation of the same operation expression 2540that contains the* ``DW_OP_call*`` *operation.* 2541 2542If a stack entry is required to be a location description L, but L has an 2543incomplete composite location description, then the DWARF expression is 2544ill-formed. The exception is for the operations involved in incrementally 2545creating a composite location description as described below. 2546 2547*Note that a DWARF operation expression may arbitrarily compose composite 2548location descriptions from any other location description, including those that 2549have multiple single location descriptions, and those that have composite 2550location descriptions.* 2551 2552*The incremental composite location description operations are defined to be 2553compatible with the definitions in DWARF Version 5.* 2554 25551. ``DW_OP_piece`` 2556 2557 ``DW_OP_piece`` has a single unsigned LEB128 integer that represents a byte 2558 size S. 2559 2560 The action is based on the context: 2561 2562 * If the stack is empty, then a location description L comprised of one 2563 incomplete composite location description SL is pushed on the stack. 2564 2565 An incomplete composite location storage LS is created with a single part 2566 P. P specifies a location description PL and has a bit size of S scaled by 2567 8 (the byte size). PL is comprised of one undefined location description 2568 PSL. 2569 2570 SL specifies LS with a bit offset of 0. 2571 2572 * Otherwise, if the top stack entry is a location description L comprised of 2573 one incomplete composite location description SL, then the incomplete 2574 composite location storage LS that SL specifies is updated to append a new 2575 part P. P specifies a location description PL and has a bit size of S 2576 scaled by 8 (the byte size). PL is comprised of one undefined location 2577 description PSL. L is left on the stack. 2578 2579 * Otherwise, if the top stack entry is a location description or can be 2580 converted to one, then it is popped and treated as a part location 2581 description PL. Then: 2582 2583 * If the top stack entry (after popping PL) is a location description L 2584 comprised of one incomplete composite location description SL, then the 2585 incomplete composite location storage LS that SL specifies is updated to 2586 append a new part P. P specifies the location description PL and has a 2587 bit size of S scaled by 8 (the byte size). L is left on the stack. 2588 2589 * Otherwise, a location description L comprised of one incomplete 2590 composite location description SL is pushed on the stack. 2591 2592 An incomplete composite location storage LS is created with a single 2593 part P. P specifies the location description PL and has a bit size of S 2594 scaled by 8 (the byte size). 2595 2596 SL specifies LS with a bit offset of 0. 2597 2598 * Otherwise, the DWARF expression is ill-formed 2599 2600 *Many compilers store a single variable in sets of registers or store a 2601 variable partially in memory and partially in registers.* ``DW_OP_piece`` 2602 *provides a way of describing where a part of a variable is located.* 2603 2604 *If a non-0 byte displacement is required, the* ``DW_OP_LLVM_offset`` 2605 *operation can be used to update the location description before using it as 2606 the part location description of a* ``DW_OP_piece`` *operation.* 2607 2608 *The evaluation rules for the* ``DW_OP_piece`` *operation allow it to be 2609 compatible with the DWARF Version 5 definition.* 2610 2611 .. note:: 2612 2613 Since these extensions allow location descriptions to be entries on the 2614 stack, a simpler operation to create composite location descriptions could 2615 be defined. For example, just one operation that specifies how many parts, 2616 and pops pairs of stack entries for the part size and location 2617 description. Not only would this be a simpler operation and avoid the 2618 complexities of incomplete composite location descriptions, but it may 2619 also have a smaller encoding in practice. However, the desire for 2620 compatibility with DWARF Version 5 is likely a stronger consideration. 2621 26222. ``DW_OP_bit_piece`` 2623 2624 ``DW_OP_bit_piece`` has two operands. The first is an unsigned LEB128 2625 integer that represents the part bit size S. The second is an unsigned 2626 LEB128 integer that represents a bit displacement B. 2627 2628 The action is the same as for ``DW_OP_piece``, except that any part created 2629 has the bit size S, and the location description PL of any created part is 2630 updated as if the ``DW_OP_constu B; DW_OP_LLVM_bit_offset`` operations were 2631 applied. 2632 2633 ``DW_OP_bit_piece`` *is used instead of* ``DW_OP_piece`` *when the piece to 2634 be assembled is not byte-sized or is not at the start of the part location 2635 description.* 2636 2637 *If a computed bit displacement is required, the* ``DW_OP_LLVM_bit_offset`` 2638 *operation can be used to update the location description before using it as 2639 the part location description of a* ``DW_OP_bit_piece`` *operation.* 2640 2641 .. note:: 2642 2643 The bit offset operand is not needed as ``DW_OP_LLVM_bit_offset`` can be 2644 used on the part's location description. 2645 26463. ``DW_OP_LLVM_piece_end`` *New* 2647 2648 If the top stack entry is not a location description L comprised of one 2649 incomplete composite location description SL, then the DWARF expression is 2650 ill-formed. 2651 2652 Otherwise, the incomplete composite location storage LS specified by SL is 2653 updated to be a complete composite location description with the same parts. 2654 26554. ``DW_OP_LLVM_extend`` *New* 2656 2657 ``DW_OP_LLVM_extend`` has two operands. The first is an unsigned LEB128 2658 integer that represents the element bit size S. The second is an unsigned 2659 LEB128 integer that represents a count C. 2660 2661 It pops one stack entry that must be a location description and is treated 2662 as the part location description PL. 2663 2664 A location description L comprised of one complete composite location 2665 description SL is pushed on the stack. 2666 2667 A complete composite location storage LS is created with C identical parts 2668 P. Each P specifies PL and has a bit size of S. 2669 2670 SL specifies LS with a bit offset of 0. 2671 2672 The DWARF expression is ill-formed if the element bit size or count are 0. 2673 26745. ``DW_OP_LLVM_select_bit_piece`` *New* 2675 2676 ``DW_OP_LLVM_select_bit_piece`` has two operands. The first is an unsigned 2677 LEB128 integer that represents the element bit size S. The second is an 2678 unsigned LEB128 integer that represents a count C. 2679 2680 It pops three stack entries. The first must be an integral type value that 2681 represents a bit mask value M. The second must be a location description 2682 that represents the one-location description L1. The third must be a 2683 location description that represents the zero-location description L0. 2684 2685 A complete composite location storage LS is created with C parts P\ :sub:`N` 2686 ordered in ascending N from 0 to C-1 inclusive. Each P\ :sub:`N` specifies 2687 location description PL\ :sub:`N` and has a bit size of S. 2688 2689 PL\ :sub:`N` is as if the ``DW_OP_LLVM_bit_offset N*S`` operation was 2690 applied to PLX\ :sub:`N`\ . 2691 2692 PLX\ :sub:`N` is the same as L0 if the N\ :sup:`th` least significant bit of 2693 M is a zero, otherwise it is the same as L1. 2694 2695 A location description L comprised of one complete composite location 2696 description SL is pushed on the stack. SL specifies LS with a bit offset of 2697 0. 2698 2699 The DWARF expression is ill-formed if S or C are 0, or if the bit size of M 2700 is less than C. 2701 2702.. _amdgpu-dwarf-location-list-expressions: 2703 2704A.2.5.5 DWARF Location List Expressions 2705+++++++++++++++++++++++++++++++++++++++ 2706 2707.. note:: 2708 2709 This section replaces DWARF Version 5 section 2.6.2. 2710 2711*To meet the needs of recent computer architectures and optimization techniques, 2712debugging information must be able to describe the location of an object whose 2713location changes over the object’s lifetime, and may reside at multiple 2714locations during parts of an object's lifetime. Location list expressions are 2715used in place of operation expressions whenever the object whose location is 2716being described has these requirements.* 2717 2718A location list expression consists of a series of location list entries. Each 2719location list entry is one of the following kinds: 2720 2721*Bounded location description* 2722 2723 This kind of location list entry provides an operation expression that 2724 evaluates to the location description of an object that is valid over a 2725 lifetime bounded by a starting and ending address. The starting address is the 2726 lowest address of the address range over which the location is valid. The 2727 ending address is the address of the first location past the highest address 2728 of the address range. 2729 2730 The location list entry matches when the current program location is within 2731 the given range. 2732 2733 There are several kinds of bounded location description entries which differ 2734 in the way that they specify the starting and ending addresses. 2735 2736*Default location description* 2737 2738 This kind of location list entry provides an operation expression that 2739 evaluates to the location description of an object that is valid when no 2740 bounded location description entry applies. 2741 2742 The location list entry matches when the current program location is not 2743 within the range of any bounded location description entry. 2744 2745*Base address* 2746 2747 This kind of location list entry provides an address to be used as the base 2748 address for beginning and ending address offsets given in certain kinds of 2749 bounded location description entries. The applicable base address of a bounded 2750 location description entry is the address specified by the closest preceding 2751 base address entry in the same location list. If there is no preceding base 2752 address entry, then the applicable base address defaults to the base address 2753 of the compilation unit (see DWARF Version 5 section 3.1.1). 2754 2755 In the case of a compilation unit where all of the machine code is contained 2756 in a single contiguous section, no base address entry is needed. 2757 2758*End-of-list* 2759 2760 This kind of location list entry marks the end of the location list 2761 expression. 2762 2763The address ranges defined by the bounded location description entries of a 2764location list expression may overlap. When they do, they describe a situation in 2765which an object exists simultaneously in more than one place. 2766 2767If all of the address ranges in a given location list expression do not 2768collectively cover the entire range over which the object in question is 2769defined, and there is no following default location description entry, it is 2770assumed that the object is not available for the portion of the range that is 2771not covered. 2772 2773The result of the evaluation of a DWARF location list expression is: 2774 2775* If the current program location is not specified, then it is an evaluation 2776 error. 2777 2778 .. note:: 2779 2780 If the location list only has a single default entry, should that be 2781 considered a match if there is no program location? If there are non-default 2782 entries then it seems it has to be an evaluation error when there is no 2783 program location as that indicates the location depends on the program 2784 location which is not known. 2785 2786* If there are no matching location list entries, then the result is a location 2787 description that comprises one undefined location description. 2788 2789* Otherwise, the operation expression E of each matching location list entry is 2790 evaluated with the current context, except that the result kind is a location 2791 description, the object is unspecified, and the initial stack is empty. The 2792 location list entry result is the location description returned by the 2793 evaluation of E. 2794 2795 The result is a location description that is comprised of the union of the 2796 single location descriptions of the location description result of each 2797 matching location list entry. 2798 2799A location list expression can only be used as the value of a debugger 2800information entry attribute that is encoded using class ``loclist`` or 2801``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the 2802attribute provides an index into a separate object file section called 2803``.debug_loclists`` or ``.debug_loclists.dwo`` (for split DWARF object files) 2804that contains the location list entries. 2805 2806A ``DW_OP_call*`` and ``DW_OP_implicit_pointer`` operation can be used to 2807specify a debugger information entry attribute that has a location list 2808expression. Several debugger information entry attributes allow DWARF 2809expressions that are evaluated with an initial stack that includes a location 2810description that may originate from the evaluation of a location list 2811expression. 2812 2813*This location list representation, the* ``loclist`` *and* ``loclistsptr`` 2814*class, and the related* ``DW_AT_loclists_base`` *attribute are new in DWARF 2815Version 5. Together they eliminate most, or all of the code object relocations 2816previously needed for location list expressions.* 2817 2818.. note:: 2819 2820 The rest of this section is the same as DWARF Version 5 section 2.6.2. 2821 2822.. _amdgpu-dwarf-segment_addresses: 2823 2824A.2.12 Segmented Addresses 2825~~~~~~~~~~~~~~~~~~~~~~~~~~ 2826 2827.. note:: 2828 2829 This augments DWARF Version 5 section 2.12. 2830 2831DWARF address classes are used for source languages that have the concept of 2832memory spaces. They are used in the ``DW_AT_address_class`` attribute for 2833pointer type, reference type, subprogram, and subprogram type debugger 2834information entries. 2835 2836Each DWARF address class is conceptually a separate source language memory space 2837with its own lifetime and aliasing rules. DWARF address classes are used to 2838specify the source language memory spaces that pointer type and reference type 2839values refer, and to specify the source language memory space in which variables 2840are allocated. 2841 2842The set of currently defined source language DWARF address classes, together 2843with source language mappings, is given in 2844:ref:`amdgpu-dwarf-address-class-table`. 2845 2846Vendor defined source language address classes may be defined using codes in the 2847range ``DW_ADDR_LLVM_lo_user`` to ``DW_ADDR_LLVM_hi_user``. 2848 2849.. table:: Address class 2850 :name: amdgpu-dwarf-address-class-table 2851 2852 ========================= ============ ========= ========= ========= 2853 Address Class Name Meaning C/C++ OpenCL CUDA/HIP 2854 ========================= ============ ========= ========= ========= 2855 ``DW_ADDR_none`` generic *default* generic *default* 2856 ``DW_ADDR_LLVM_global`` global global 2857 ``DW_ADDR_LLVM_constant`` constant constant constant 2858 ``DW_ADDR_LLVM_group`` thread-group local shared 2859 ``DW_ADDR_LLVM_private`` thread private 2860 ``DW_ADDR_LLVM_lo_user`` 2861 ``DW_ADDR_LLVM_hi_user`` 2862 ========================= ============ ========= ========= ========= 2863 2864DWARF address spaces correspond to target architecture specific linear 2865addressable memory areas. They are used in DWARF expression location 2866descriptions to describe in which target architecture specific memory area data 2867resides. 2868 2869*Target architecture specific DWARF address spaces may correspond to hardware 2870supported facilities such as memory utilizing base address registers, scratchpad 2871memory, and memory with special interleaving. The size of addresses in these 2872address spaces may vary. Their access and allocation may be hardware managed 2873with each thread or group of threads having access to independent storage. For 2874these reasons they may have properties that do not allow them to be viewed as 2875part of the unified global virtual address space accessible by all threads.* 2876 2877*It is target architecture specific whether multiple DWARF address spaces are 2878supported and how source language DWARF address classes map to target 2879architecture specific DWARF address spaces. A target architecture may map 2880multiple source language DWARF address classes to the same target architecture 2881specific DWARF address class. Optimization may determine that variable lifetime 2882and access pattern allows them to be allocated in faster scratchpad memory 2883represented by a different DWARF address space.* 2884 2885Although DWARF address space identifiers are target architecture specific, 2886``DW_ASPACE_none`` is a common address space supported by all target 2887architectures. 2888 2889DWARF address space identifiers are used by: 2890 2891* The DWARF expression operations: ``DW_OP_LLVM_aspace_bregx``, 2892 ``DW_OP_LLVM_form_aspace_address``, ``DW_OP_LLVM_implicit_aspace_pointer``, 2893 and ``DW_OP_xderef*``. 2894 2895* The CFI instructions: ``DW_CFA_LLVM_def_aspace_cfa`` and 2896 ``DW_CFA_LLVM_def_aspace_cfa_sf``. 2897 2898.. note:: 2899 2900 With the definition of DWARF address classes and DWARF address spaces in these 2901 extensions, DWARF Version 5 table 2.7 needs to be updated. It seems it is an 2902 example of DWARF address spaces and not DWARF address classes. 2903 2904.. note:: 2905 2906 With the expanded support for DWARF address spaces in these extensions, it may 2907 be worth examining if DWARF segments can be eliminated and DWARF address 2908 spaces used instead. 2909 2910 That may involve extending DWARF address spaces to also be used to specify 2911 code locations. In target architectures that use different memory areas for 2912 code and data this would seem a natural use for DWARF address spaces. This 2913 would allow DWARF expression location descriptions to be used to describe the 2914 location of subprograms and entry points that are used in expressions 2915 involving subprogram pointer type values. 2916 2917 Currently, DWARF expressions assume data and code resides in the same default 2918 DWARF address space, and only the address ranges in DWARF location list 2919 entries and in the ``.debug_aranges`` section for accelerated access for 2920 addresses allow DWARF segments to be used to distinguish. 2921 2922.. note:: 2923 2924 Currently, DWARF defines address class values as being target architecture 2925 specific. It is unclear how language specific memory spaces are intended to be 2926 represented in DWARF using these. 2927 2928 For example, OpenCL defines memory spaces (called address spaces in OpenCL) 2929 for ``global``, ``local``, ``constant``, and ``private``. These are part of 2930 the type system and are modifiers to pointer types. In addition, OpenCL 2931 defines ``generic`` pointers that can reference either the ``global``, 2932 ``local``, or ``private`` memory spaces. To support the OpenCL language the 2933 debugger would want to support casting pointers between the ``generic`` and 2934 other memory spaces, querying what memory space a ``generic`` pointer value is 2935 currently referencing, and possibly using pointer casting to form an address 2936 for a specific memory space out of an integral value. 2937 2938 The method to use to dereference a pointer type or reference type value is 2939 defined in DWARF expressions using ``DW_OP_xderef*`` which uses a target 2940 architecture specific address space. 2941 2942 DWARF defines the ``DW_AT_address_class`` attribute on pointer type and 2943 reference type debugger information entries. It specifies the method to use to 2944 dereference them. Why is the value of this not the same as the address space 2945 value used in ``DW_OP_xderef*``? In both cases it is target architecture 2946 specific and the architecture presumably will use the same set of methods to 2947 dereference pointers in both cases. 2948 2949 Since ``DW_AT_address_class`` uses a target architecture specific value, it 2950 cannot in general capture the source language memory space type modifier 2951 concept. On some architectures all source language memory space modifiers may 2952 actually use the same method for dereferencing pointers. 2953 2954 One possibility is for DWARF to add an ``DW_TAG_LLVM_address_class_type`` 2955 debugger information entry type modifier that can be applied to a pointer type 2956 and reference type. The ``DW_AT_address_class`` attribute could be re-defined 2957 to not be target architecture specific and instead define generalized language 2958 values (as presented above for DWARF address classes in the table 2959 :ref:`amdgpu-dwarf-address-class-table`) that will support OpenCL and other 2960 languages using memory spaces. The ``DW_AT_address_class`` attribute could be 2961 defined to not be applied to pointer types or reference types, but instead 2962 only to the new ``DW_TAG_LLVM_address_class_type`` type modifier debugger 2963 information entry. 2964 2965 If a pointer type or reference type is not modified by 2966 ``DW_TAG_LLVM_address_class_type`` or if ``DW_TAG_LLVM_address_class_type`` 2967 has no ``DW_AT_address_class`` attribute, then the pointer type or reference 2968 type would be defined to use the ``DW_ADDR_none`` address class as currently. 2969 Since modifiers can be chained, it would need to be defined if multiple 2970 ``DW_TAG_LLVM_address_class_type`` modifiers were legal, and if so if the 2971 outermost one is the one that takes precedence. 2972 2973 A target architecture implementation that supports multiple address spaces 2974 would need to map ``DW_ADDR_none`` appropriately to support CUDA-like 2975 languages that have no address classes in the type system but do support 2976 variable allocation in address classes. Such variable allocation would result 2977 in the variable's location description needing an address space. 2978 2979 The approach presented in :ref:`amdgpu-dwarf-address-class-table` is to define 2980 the default ``DW_ADDR_none`` to be the generic address class and not the 2981 global address class. This matches how CLANG and LLVM have added support for 2982 CUDA-like languages on top of existing C++ language support. This allows all 2983 addresses to be generic by default which matches CUDA-like languages. 2984 2985 An alternative approach is to define ``DW_ADDR_none`` as being the global 2986 address class and then change ``DW_ADDR_LLVM_global`` to 2987 ``DW_ADDR_LLVM_generic``. This would match the reality that languages that do 2988 not support multiple memory spaces only have one default global memory space. 2989 Generally, in these languages if they expose that the target architecture 2990 supports multiple address spaces, the default one is still the global memory 2991 space. Then a language that does support multiple memory spaces has to 2992 explicitly indicate which pointers have the added ability to reference more 2993 than the global memory space. However, compilers generating DWARF for 2994 CUDA-like languages would then have to define every CUDA-like language pointer 2995 type or reference type using ``DW_TAG_LLVM_address_class_type`` with a 2996 ``DW_AT_address_class`` attribute of ``DW_ADDR_LLVM_generic`` to match the 2997 language semantics. 2998 2999 A new ``DW_AT_LLVM_address_space`` attribute could be defined that can be 3000 applied to pointer type, reference type, subprogram, and subprogram type to 3001 describe how objects having the given type are dereferenced or called (the 3002 role that ``DW_AT_address_class`` currently provides). The values of 3003 ``DW_AT_address_space`` would be target architecture specific and the same as 3004 used in ``DW_OP_xderef*``. 3005 3006.. note:: 3007 3008 Some additional changes will be made to support languages such as OpenCL/SyCL 3009 that allow address class pointer casting and queries. 3010 3011 This requires the compiler to provide the mapping from address space to 3012 address class which may be runtime and not target architecture dependent. Some 3013 implementations may have a one-to-one mapping from source language address 3014 class to target architecture address space, and some may have a many-to-one 3015 mapping which requires knowledge of the address class when determining if 3016 pointer address class casts are allowed. 3017 3018 The changes will likely add an attribute that has an expression provided by 3019 the compiler to map from address class to address space. The 3020 ``DW_OP_implicit_pointer`` and ``DW_OP_LLVM_aspace_implicit_pointer`` 3021 operations may be changed as the current IPV definition may not provide enough 3022 information when used to cast between address classes. Other attributes and 3023 operations may be needed. The legal casts between address classes may need to 3024 be defined on a per language address class basis. 3025 3026A.3 Program Scope Entries 3027------------------------- 3028 3029.. note:: 3030 3031 This section provides changes to existing debugger information entry 3032 attributes. These would be incorporated into the corresponding DWARF Version 5 3033 chapter 3 sections. 3034 3035A.3.1 Unit Entries 3036~~~~~~~~~~~~~~~~~~ 3037 3038.. _amdgpu-dwarf-full-and-partial-compilation-unit-entries: 3039 3040A.3.1.1 Full and Partial Compilation Unit Entries 3041+++++++++++++++++++++++++++++++++++++++++++++++++ 3042 3043.. note:: 3044 3045 This augments DWARF Version 5 section 3.1.1 and Table 3.1. 3046 3047Additional language codes defined for use with the ``DW_AT_language`` attribute 3048are defined in :ref:`amdgpu-dwarf-language-names-table`. 3049 3050.. table:: Language Names 3051 :name: amdgpu-dwarf-language-names-table 3052 3053 ==================== ============================= 3054 Language Name Meaning 3055 ==================== ============================= 3056 ``DW_LANG_LLVM_HIP`` HIP Language. 3057 ==================== ============================= 3058 3059The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending 3060the C++ language. 3061 3062.. note:: 3063 3064 The following new attribute is added. 3065 30661. A ``DW_TAG_compile_unit`` debugger information entry for a compilation unit 3067 may have a ``DW_AT_LLVM_augmentation`` attribute, whose value is an 3068 augmentation string. 3069 3070 *The augmentation string allows producers to indicate that there is 3071 additional vendor or target specific information in the debugging 3072 information entries. For example, this might be information about the 3073 version of vendor specific extensions that are being used.* 3074 3075 If not present, or if the string is empty, then the compilation unit has no 3076 augmentation string. 3077 3078 The format for the augmentation string is: 3079 3080 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * 3081 3082 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y 3083 version number of the extensions used, and *options* is an optional string 3084 providing additional information about the extensions. The version number 3085 must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`]. 3086 The *options* string must not contain the "\ ``]``\ " character. 3087 3088 For example: 3089 3090 :: 3091 3092 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] 3093 3094A.3.3 Subroutine and Entry Point Entries 3095~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3096 3097.. _amdgpu-dwarf-low-level-information: 3098 3099A.3.3.5 Low-Level Information 3100+++++++++++++++++++++++++++++ 3101 31021. A ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3103 ``DW_TAG_entry_point`` debugger information entry may have a 3104 ``DW_AT_return_addr`` attribute, whose value is a DWARF expression E. 3105 3106 The result of the attribute is obtained by evaluating E with a context that 3107 has a result kind of a location description, an unspecified object, the 3108 compilation unit that contains E, an empty initial stack, and other context 3109 elements corresponding to the source language thread of execution upon which 3110 the user is focused, if any. The result of the evaluation is the location 3111 description L of the place where the return address for the current call 3112 frame's subprogram or entry point is stored. 3113 3114 The DWARF is ill-formed if L is not comprised of one memory location 3115 description for one of the target architecture specific address spaces. 3116 3117 .. note:: 3118 3119 It is unclear why ``DW_TAG_inlined_subroutine`` has a 3120 ``DW_AT_return_addr`` attribute but not a ``DW_AT_frame_base`` or 3121 ``DW_AT_static_link`` attribute. Seems it would either have all of them or 3122 none. Since inlined subprograms do not have a call frame it seems they 3123 would have none of these attributes. 3124 31252. A ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information entry 3126 may have a ``DW_AT_frame_base`` attribute, whose value is a DWARF expression 3127 E. 3128 3129 The result of the attribute is obtained by evaluating E with a context that 3130 has a result kind of a location description, an unspecified object, the 3131 compilation unit that contains E, an empty initial stack, and other context 3132 elements corresponding to the source language thread of execution upon which 3133 the user is focused, if any. 3134 3135 The DWARF is ill-formed if E contains an ``DW_OP_fbreg`` operation, or the 3136 resulting location description L is not comprised of one single location 3137 description SL. 3138 3139 If SL is a register location description for register R, then L is replaced 3140 with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This 3141 computes the frame base memory location description in the target 3142 architecture default address space. 3143 3144 *This allows the more compact* ``DW_OP_reg*`` *to be used instead of* 3145 ``DW_OP_breg* 0``\ *.* 3146 3147 .. note:: 3148 3149 This rule could be removed and require the producer to create the required 3150 location description directly using ``DW_OP_call_frame_cfa``, 3151 ``DW_OP_breg*``, or ``DW_OP_LLVM_aspace_bregx``. This would also then 3152 allow a target to implement the call frames within a large register. 3153 3154 Otherwise, the DWARF is ill-formed if SL is not a memory location 3155 description in any of the target architecture specific address spaces. 3156 3157 The resulting L is the *frame base* for the subprogram or entry point. 3158 3159 *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a 3160 stack pointer register plus or minus some offset.* 3161 31623. If a ``DW_TAG_subprogram`` or ``DW_TAG_entry_point`` debugger information 3163 entry is lexically nested, it may have a ``DW_AT_static_link`` attribute, 3164 whose value is a DWARF expression E. 3165 3166 The result of the attribute is obtained by evaluating E with a context that 3167 has a result kind of a location description, an unspecified object, the 3168 compilation unit that contains E, an empty initial stack, and other context 3169 elements corresponding to the source language thread of execution upon which 3170 the user is focused, if any. The result of the evaluation is the location 3171 description L of the *canonical frame address* (see 3172 :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of 3173 the subprogram instance that immediately lexically encloses the current call 3174 frame's subprogram or entry point. 3175 3176 The DWARF is ill-formed if L is is not comprised of one memory location 3177 description for one of the target architecture specific address spaces. 3178 3179 .. note:: 3180 3181 The following new attributes are added. 3182 31834. For languages that are implemented using a SIMD or SIMT execution model, a 3184 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3185 ``DW_TAG_entry_point`` debugger information entry may have a 3186 ``DW_AT_LLVM_lanes`` attribute whose value is an integer constant that is 3187 the number of lanes per thread. This is the static number of lanes per 3188 thread. It is not the dynamic number of lanes with which the thread was 3189 initiated, for example, due to smaller or partial work-groups. 3190 3191 If not present, the default value of 1 is used. 3192 3193 The DWARF is ill-formed if the value is 0. 3194 31955. For languages that are implemented using a SIMD or SIMT execution model, a 3196 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3197 ``DW_TAG_entry_point`` debugging information entry may have a 3198 ``DW_AT_LLVM_lane_pc`` attribute whose value is a DWARF expression E. 3199 3200 The result of the attribute is obtained by evaluating E with a context that 3201 has a result kind of a location description, an unspecified object, the 3202 compilation unit that contains E, an empty initial stack, and other context 3203 elements corresponding to the source language thread of execution upon which 3204 the user is focused, if any. 3205 3206 The resulting location description L is for a thread lane count sized vector 3207 of generic type elements. The thread lane count is the value of the 3208 ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program 3209 location of the corresponding lane, where the least significant element 3210 corresponds to the first target architecture specific lane identifier and so 3211 forth. If the lane was not active when the current subprogram was called, 3212 its element is an undefined location description. 3213 3214 ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where 3215 each lane of a SIMT thread is positioned even when it is in divergent 3216 control flow that is not active.* 3217 3218 *Typically, the result is a location description with one composite location 3219 description with each part being a location description with either one 3220 undefined location description or one memory location description.* 3221 3222 If not present, the thread is not being used in a SIMT manner, and the 3223 thread's current program location is used. 3224 32256. For languages that are implemented using a SIMD or SIMT execution model, a 3226 ``DW_TAG_subprogram``, ``DW_TAG_inlined_subroutine``, or 3227 ``DW_TAG_entry_point`` debugger information entry may have a 3228 ``DW_AT_LLVM_active_lane`` attribute whose value is a DWARF expression E. 3229 3230 The result of the attribute is obtained by evaluating E with a context that 3231 has a result kind of a value, an unspecified object, the compilation unit 3232 that contains E, an empty initial stack, and other context elements 3233 corresponding to the source language thread of execution upon which the user 3234 is focused, if any. 3235 3236 The DWARF is ill-formed if the resulting value V is not an integral value. 3237 3238 The resulting V is a bit mask of active lanes for the current program 3239 location. The N\ :sup:`th` least significant bit of the mask corresponds to 3240 the N\ :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is 3241 inactive. 3242 3243 *Some targets may update the target architecture execution mask for regions 3244 of code that must execute with different sets of lanes than the current 3245 active lanes. For example, some code must execute with all lanes made 3246 temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to 3247 provide the means to determine the source language active lanes.* 3248 3249 If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target 3250 architecture execution mask is used. 3251 3252A.3.4 Call Site Entries and Parameters 3253~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3254 3255A.3.4.2 Call Site Parameters 3256++++++++++++++++++++++++++++ 3257 32581. A ``DW_TAG_call_site_parameter`` debugger information entry may have a 3259 ``DW_AT_call_value`` attribute, whose value is a DWARF operation expression 3260 E\ :sub:`1`\ . 3261 3262 The result of the ``DW_AT_call_value`` attribute is obtained by evaluating 3263 E\ :sub:`1` with a context that has a result kind of a value, an unspecified 3264 object, the compilation unit that contains E, an empty initial stack, and 3265 other context elements corresponding to the source language thread of 3266 execution upon which the user is focused, if any. The resulting value V\ 3267 :sub:`1` is the value of the parameter at the time of the call made by the 3268 call site. 3269 3270 For parameters passed by reference, where the code passes a pointer to a 3271 location which contains the parameter, or for reference type parameters, the 3272 ``DW_TAG_call_site_parameter`` debugger information entry may also have a 3273 ``DW_AT_call_data_location`` attribute whose value is a DWARF operation 3274 expression E\ :sub:`2`\ , and a ``DW_AT_call_data_value`` attribute whose 3275 value is a DWARF operation expression E\ :sub:`3`\ . 3276 3277 The value of the ``DW_AT_call_data_location`` attribute is obtained by 3278 evaluating E\ :sub:`2` with a context that has a result kind of a location 3279 description, an unspecified object, the compilation unit that contains E, an 3280 empty initial stack, and other context elements corresponding to the source 3281 language thread of execution upon which the user is focused, if any. The 3282 resulting location description L\ :sub:`2` is the location where the 3283 referenced parameter lives during the call made by the call site. If E\ 3284 :sub:`2` would just be a ``DW_OP_push_object_address``, then the 3285 ``DW_AT_call_data_location`` attribute may be omitted. 3286 3287 .. note:: 3288 3289 The DWARF Version 5 implies that `DW_OP_push_object_address` may be used 3290 but does not state what object must be specified in the context. Either 3291 `DW_OP_push_object_address` cannot be used, or the object to be passed in 3292 the context must be defined. 3293 3294 The value of the ``DW_AT_call_data_value`` attribute is obtained by 3295 evaluating E\ :sub:`3` with a context that has a result kind of a value, an 3296 unspecified object, the compilation unit that contains E, an empty initial 3297 stack, and other context elements corresponding to the source language 3298 thread of execution upon which the user is focused, if any. The resulting 3299 value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made 3300 by the call site. 3301 3302 The result of these attributes is undefined if the current call frame is not 3303 for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger 3304 information entry or the current program location is not for the call site 3305 containing the ``DW_TAG_call_site_parameter`` debugger information entry in 3306 the current call frame. 3307 3308 *The consumer may have to virtually unwind to the call site (see* 3309 :ref:`amdgpu-dwarf-call-frame-information`\ *) in order to evaluate these 3310 attributes. This will ensure the source language thread of execution upon 3311 which the user is focused corresponds to the call site needed to evaluate 3312 the expression.* 3313 3314 If it is not possible to avoid the expressions of these attributes from 3315 accessing registers or memory locations that might be clobbered by the 3316 subprogram being called by the call site, then the associated attribute 3317 should not be provided. 3318 3319 *The reason for the restriction is that the parameter may need to be 3320 accessed during the execution of the callee. The consumer may virtually 3321 unwind from the called subprogram back to the caller and then evaluate the 3322 attribute expressions. The call frame information (see* 3323 :ref:`amdgpu-dwarf-call-frame-information`\ *) will not be able to restore 3324 registers that have been clobbered, and clobbered memory will no longer have 3325 the value at the time of the call.* 3326 3327.. _amdgpu-dwarf-lexical-block-entries: 3328 3329A.3.5 Lexical Block Entries 3330~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3331 3332.. note:: 3333 3334 This section is the same as DWARF Version 5 section 3.5. 3335 3336A.4 Data Object and Object List Entries 3337--------------------------------------- 3338 3339.. note:: 3340 3341 This section provides changes to existing debugger information entry 3342 attributes. These would be incorporated into the corresponding DWARF Version 5 3343 chapter 4 sections. 3344 3345A.4.1 Data Object Entries 3346~~~~~~~~~~~~~~~~~~~~~~~~~ 3347 33481. Any debugging information entry describing a data object (which includes 3349 variables and parameters) or common blocks may have a ``DW_AT_location`` 3350 attribute, whose value is a DWARF expression E. 3351 3352 The result of the attribute is obtained by evaluating E with a context that 3353 has a result kind of a location description, an unspecified object, the 3354 compilation unit that contains E, an empty initial stack, and other context 3355 elements corresponding to the source language thread of execution upon which 3356 the user is focused, if any. The result of the evaluation is the location 3357 description of the base of the data object. 3358 3359 See :ref:`amdgpu-dwarf-control-flow-operations` for special evaluation rules 3360 used by the ``DW_OP_call*`` operations. 3361 3362 .. note:: 3363 3364 Delete the description of how the ``DW_OP_call*`` operations evaluate a 3365 ``DW_AT_location`` attribute as that is now described in the operations. 3366 3367 .. note:: 3368 3369 See the discussion about the ``DW_AT_location`` attribute in the 3370 ``DW_OP_call*`` operation. Having each attribute only have a single 3371 purpose and single execution semantics seems desirable. It makes it easier 3372 for the consumer that no longer have to track the context. It makes it 3373 easier for the producer as it can rely on a single semantics for each 3374 attribute. 3375 3376 For that reason, limiting the ``DW_AT_location`` attribute to only 3377 supporting evaluating the location description of an object, and using a 3378 different attribute and encoding class for the evaluation of DWARF 3379 expression *procedures* on the same operation expression stack seems 3380 desirable. 3381 33822. ``DW_AT_const_value`` 3383 3384 .. note:: 3385 3386 Could deprecate using the ``DW_AT_const_value`` attribute for 3387 ``DW_TAG_variable`` or ``DW_TAG_formal_parameter`` debugger information 3388 entries that have been optimized to a constant. Instead, 3389 ``DW_AT_location`` could be used with a DWARF expression that produces an 3390 implicit location description now that any location description can be 3391 used within a DWARF expression. This allows the ``DW_OP_call*`` operations 3392 to be used to push the location description of any variable regardless of 3393 how it is optimized. 3394 3395A.5 Type Entries 3396---------------- 3397 3398.. note:: 3399 3400 This section provides changes to existing debugger information entry 3401 attributes. These would be incorporated into the corresponding DWARF Version 5 3402 chapter 5 sections. 3403 3404.. _amdgpu-dwarf-base-type-entries: 3405 3406A.5.1 Base Type Entries 3407~~~~~~~~~~~~~~~~~~~~~~~ 3408 3409.. note:: 3410 3411 The following new attribute is added. 3412 34131. A ``DW_TAG_base_type`` debugger information entry for a base type T may have 3414 a ``DW_AT_LLVM_vector_size`` attribute whose value is an integer constant 3415 that is the vector type size N. 3416 3417 The representation of a vector base type is as N contiguous elements, each 3418 one having the representation of a base type T' that is the same as T 3419 without the ``DW_AT_LLVM_vector_size`` attribute. 3420 3421 If a ``DW_TAG_base_type`` debugger information entry does not have a 3422 ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector 3423 type. 3424 3425 The DWARF is ill-formed if N is not greater than 0. 3426 3427 .. note:: 3428 3429 LLVM has mention of a non-upstreamed debugger information entry that is 3430 intended to support vector types. However, that was not for a base type so 3431 would not be suitable as the type of a stack value entry. But perhaps that 3432 could be replaced by using this attribute. 3433 3434A.5.7 Structure, Union, Class and Interface Type Entries 3435~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3436 3437A.5.7.3 Derived or Extended Structures, Classes and Interfaces 3438++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3439 34401. For a ``DW_AT_data_member_location`` attribute there are two cases: 3441 3442 1. If the attribute is an integer constant B, it provides the offset in 3443 bytes from the beginning of the containing entity. 3444 3445 The result of the attribute is obtained by evaluating a 3446 ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the 3447 location description of the beginning of the containing entity. The 3448 result of the evaluation is the location description of the base of the 3449 member entry. 3450 3451 *If the beginning of the containing entity is not byte aligned, then the 3452 beginning of the member entry has the same bit displacement within a 3453 byte.* 3454 3455 2. Otherwise, the attribute must be a DWARF expression E which is evaluated 3456 with a context that has a result kind of a location description, an 3457 unspecified object, the compilation unit that contains E, an initial 3458 stack comprising the location description of the beginning of the 3459 containing entity, and other context elements corresponding to the 3460 source language thread of execution upon which the user is focused, if 3461 any. The result of the evaluation is the location description of the 3462 base of the member entry. 3463 3464 .. note:: 3465 3466 The beginning of the containing entity can now be any location 3467 description, including those with more than one single location 3468 description, and those with single location descriptions that are of any 3469 kind and have any bit offset. 3470 3471A.5.7.8 Member Function Entries 3472+++++++++++++++++++++++++++++++ 3473 34741. An entry for a virtual function also has a ``DW_AT_vtable_elem_location`` 3475 attribute whose value is a DWARF expression E. 3476 3477 The result of the attribute is obtained by evaluating E with a context that 3478 has a result kind of a location description, an unspecified object, the 3479 compilation unit that contains E, an initial stack comprising the location 3480 description of the object of the enclosing type, and other context elements 3481 corresponding to the source language thread of execution upon which the user 3482 is focused, if any. The result of the evaluation is the location description 3483 of the slot for the function within the virtual function table for the 3484 enclosing class. 3485 3486A.5.14 Pointer to Member Type Entries 3487~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3488 34891. The ``DW_TAG_ptr_to_member_type`` debugging information entry has a 3490 ``DW_AT_use_location`` attribute whose value is a DWARF expression E. It is 3491 used to compute the location description of the member of the class to which 3492 the pointer to member entry points. 3493 3494 *The method used to find the location description of a given member of a 3495 class, structure, or union is common to any instance of that class, 3496 structure, or union and to any instance of the pointer to member type. The 3497 method is thus associated with the pointer to member type, rather than with 3498 each object that has a pointer to member type.* 3499 3500 The ``DW_AT_use_location`` DWARF expression is used in conjunction with the 3501 location description for a particular object of the given pointer to member 3502 type and for a particular structure or class instance. 3503 3504 The result of the attribute is obtained by evaluating E with a context that 3505 has a result kind of a location description, an unspecified object, the 3506 compilation unit that contains E, an initial stack comprising two entries, 3507 and other context elements corresponding to the source language thread of 3508 execution upon which the user is focused, if any. The first stack entry is 3509 the value of the pointer to member object itself. The second stack entry is 3510 the location description of the base of the entire class, structure, or 3511 union instance containing the member whose location is being calculated. The 3512 result of the evaluation is the location description of the member of the 3513 class to which the pointer to member entry points. 3514 3515A.5.16 Dynamic Type Entries 3516~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3517 35181. The ``DW_AT_data_location`` attribute may be used with any type that 3519 provides one or more levels of hidden indirection and/or run-time parameters 3520 in its representation. Its value is a DWARF operation expression E which 3521 computes the location description of the data for an object. When this 3522 attribute is omitted, the location description of the data is the same as 3523 the location description of the object. 3524 3525 The result of the attribute is obtained by evaluating E with a context that 3526 has a result kind of a location description, an object that is the location 3527 description of the data descriptor, the compilation unit that contains E, an 3528 empty initial stack, and other context elements corresponding to the source 3529 language thread of execution upon which the user is focused, if any. The 3530 result of the evaluation is the location description of the base of the 3531 member entry. 3532 3533 *E will typically involve an operation expression that begins with a* 3534 ``DW_OP_push_object_address`` *operation which loads the location 3535 description of the object which can then serve as a descriptor in subsequent 3536 calculation.* 3537 3538 .. note:: 3539 3540 Since ``DW_AT_data_member_location``, ``DW_AT_use_location``, and 3541 ``DW_AT_vtable_elem_location`` allow both operation expressions and 3542 location list expressions, why does ``DW_AT_data_location`` not allow 3543 both? In all cases they apply to data objects so less likely that 3544 optimization would cause different operation expressions for different 3545 program location ranges. But if supporting for some then should be for 3546 all. 3547 3548 It seems odd this attribute is not the same as 3549 ``DW_AT_data_member_location`` in having an initial stack with the 3550 location description of the object since the expression has to need it. 3551 3552A.6 Other Debugging Information 3553------------------------------- 3554 3555.. note:: 3556 3557 This section provides changes to existing debugger information entry 3558 attributes. These would be incorporated into the corresponding DWARF Version 5 3559 chapter 6 sections. 3560 3561A.6.1 Accelerated Access 3562~~~~~~~~~~~~~~~~~~~~~~~~ 3563 3564.. _amdgpu-dwarf-lookup-by-name: 3565 3566A.6.1.1 Lookup By Name 3567++++++++++++++++++++++ 3568 3569A.6.1.1.1 Contents of the Name Index 3570#################################### 3571 3572.. note:: 3573 3574 The following provides changes to DWARF Version 5 section 6.1.1.1. 3575 3576 The rule for debugger information entries included in the name index in the 3577 optional ``.debug_names`` section is extended to also include named 3578 ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location`` 3579 attribute that includes a ``DW_OP_LLVM_form_aspace_address`` operation. 3580 3581The name index must contain an entry for each debugging information entry that 3582defines a named subprogram, label, variable, type, or namespace, subject to the 3583following rules: 3584 3585* ``DW_TAG_variable`` debugging information entries with a ``DW_AT_location`` 3586 attribute that includes a ``DW_OP_addr``, ``DW_OP_LLVM_form_aspace_address``, 3587 or ``DW_OP_form_tls_address`` operation are included; otherwise, they are 3588 excluded. 3589 3590A.6.1.1.4 Data Representation of the Name Index 3591############################################### 3592 3593.. _amdgpu-dwarf-name-index-section-header: 3594 3595 3596A.6.1.1.4.1 Section Header 3597^^^^^^^^^^^^^^^^^^^^^^^^^^ 3598 3599.. note:: 3600 3601 The following provides an addition to DWARF Version 5 section 6.1.1.4.1 item 3602 14 ``augmentation_string``. 3603 3604A null-terminated UTF-8 vendor specific augmentation string, which provides 3605additional information about the contents of this index. If provided, the 3606recommended format for augmentation string is: 3607 3608 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * 3609 3610Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y 3611version number of the extensions used in the DWARF of the compilation unit, and 3612*options* is an optional string providing additional information about the 3613extensions. The version number must conform to semantic versioning [:ref:`SEMVER 3614<amdgpu-dwarf-SEMVER>`]. The *options* string must not contain the "\ ``]``\ " 3615character. 3616 3617For example: 3618 3619 :: 3620 3621 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] 3622 3623.. note:: 3624 3625 This is different to the definition in DWARF Version 5 but is consistent with 3626 the other augmentation strings and allows multiple vendor extensions to be 3627 supported. 3628 3629.. _amdgpu-dwarf-line-number-information: 3630 3631A.6.2 Line Number Information 3632~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3633 3634A.6.2.4 The Line Number Program Header 3635++++++++++++++++++++++++++++++++++++++ 3636 3637A.6.2.4.1 Standard Content Descriptions 3638####################################### 3639 3640.. note:: 3641 3642 This augments DWARF Version 5 section 6.2.4.1. 3643 3644.. _amdgpu-dwarf-line-number-information-dw-lnct-llvm-source: 3645 36461. ``DW_LNCT_LLVM_source`` 3647 3648 The component is a null-terminated UTF-8 source text string with "\ ``\n``\ 3649 " line endings. This content code is paired with the same forms as 3650 ``DW_LNCT_path``. It can be used for file name entries. 3651 3652 The value is an empty null-terminated string if no source is available. If 3653 the source is available but is an empty file then the value is a 3654 null-terminated single "\ ``\n``\ ". 3655 3656 *When the source field is present, consumers can use the embedded source 3657 instead of attempting to discover the source on disk using the file path 3658 provided by the* ``DW_LNCT_path`` *field. When the source field is absent, 3659 consumers can access the file to get the source text.* 3660 3661 *This is particularly useful for programming languages that support runtime 3662 compilation and runtime generation of source text. In these cases, the 3663 source text does not reside in any permanent file. For example, the OpenCL 3664 language [:ref:`OpenCL <amdgpu-dwarf-OpenCL>`] supports online compilation.* 3665 36662. ``DW_LNCT_LLVM_is_MD5`` 3667 3668 ``DW_LNCT_LLVM_is_MD5`` indicates if the ``DW_LNCT_MD5`` content kind, if 3669 present, is valid: when 0 it is not valid and when 1 it is valid. If 3670 ``DW_LNCT_LLVM_is_MD5`` content kind is not present, and ``DW_LNCT_MD5`` 3671 content kind is present, then the MD5 checksum is valid. 3672 3673 ``DW_LNCT_LLVM_is_MD5`` is always paired with the ``DW_FORM_udata`` form. 3674 3675 *This allows a compilation unit to have a mixture of files with and without 3676 MD5 checksums. This can happen when multiple relocatable files are linked 3677 together.* 3678 3679.. _amdgpu-dwarf-call-frame-information: 3680 3681A.6.4 Call Frame Information 3682~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3683 3684.. note:: 3685 3686 This section provides changes to existing call frame information and defines 3687 instructions added by these extensions. Additional support is added for 3688 address spaces. Register unwind DWARF expressions are generalized to allow any 3689 location description, including those with composite and implicit location 3690 descriptions. 3691 3692 These changes would be incorporated into the DWARF Version 5 section 6.4. 3693 3694.. _amdgpu-dwarf-structure_of-call-frame-information: 3695 3696A.6.4.1 Structure of Call Frame Information 3697+++++++++++++++++++++++++++++++++++++++++++ 3698 3699The register rules are: 3700 3701*undefined* 3702 A register that has this rule has no recoverable value in the previous frame. 3703 The previous value of this register is the undefined location description (see 3704 :ref:`amdgpu-dwarf-undefined-location-description-operations`). 3705 3706 *By convention, the register is not preserved by a callee.* 3707 3708*same value* 3709 This register has not been modified from the previous caller frame. 3710 3711 If the current frame is the top frame, then the previous value of this 3712 register is the location description L that specifies one register location 3713 description SL. SL specifies the register location storage that corresponds to 3714 the register with a bit offset of 0 for the current thread. 3715 3716 If the current frame is not the top frame, then the previous value of this 3717 register is the location description obtained using the call frame information 3718 for the callee frame and callee program location invoked by the current caller 3719 frame for the same register. 3720 3721 *By convention, the register is preserved by the callee, but the callee has 3722 not modified it.* 3723 3724*offset(N)* 3725 N is a signed byte offset. The previous value of this register is saved at the 3726 location description computed as if the DWARF operation expression 3727 ``DW_OP_LLVM_offset N`` is evaluated with the current context, except the 3728 result kind is a location description, the compilation unit is unspecified, 3729 the object is unspecified, and an initial stack comprising the location 3730 description of the current CFA (see 3731 :ref:`amdgpu-dwarf-operation-expressions`). 3732 3733*val_offset(N)* 3734 N is a signed byte offset. The previous value of this register is the memory 3735 byte address of the location description computed as if the DWARF operation 3736 expression ``DW_OP_LLVM_offset N`` is evaluated with the current context, 3737 except the result kind is a location description, the compilation unit is 3738 unspecified, the object is unspecified, and an initial stack comprising the 3739 location description of the current CFA (see 3740 :ref:`amdgpu-dwarf-operation-expressions`). 3741 3742 The DWARF is ill-formed if the CFA location description is not a memory byte 3743 address location description, or if the register size does not match the size 3744 of an address in the address space of the current CFA location description. 3745 3746 *Since the CFA location description is required to be a memory byte address 3747 location description, the value of val_offset(N) will also be a memory byte 3748 address location description since it is offsetting the CFA location 3749 description by N bytes. Furthermore, the value of val_offset(N) will be a 3750 memory byte address in the same address space as the CFA location 3751 description.* 3752 3753 .. note:: 3754 3755 Should DWARF allow the address size to be a different size to the size of 3756 the register? Requiring them to be the same bit size avoids any issue of 3757 conversion as the bit contents of the register is simply interpreted as a 3758 value of the address. 3759 3760 GDB has a per register hook that allows a target specific conversion on a 3761 register by register basis. It defaults to truncation of bigger registers, 3762 and to actually reading bytes from the next register (or reads out of bounds 3763 for the last register) for smaller registers. There are no GDB tests that 3764 read a register out of bounds (except an illegal hand written assembly 3765 test). 3766 3767*register(R)* 3768 This register has been stored in another register numbered R. 3769 3770 The previous value of this register is the location description obtained using 3771 the call frame information for the current frame and current program location 3772 for register R. 3773 3774 The DWARF is ill-formed if the size of this register does not match the size 3775 of register R or if there is a cyclic dependency in the call frame 3776 information. 3777 3778 .. note:: 3779 3780 Should this also allow R to be larger than this register? If so is the value 3781 stored in the low order bits and it is undefined what is stored in the 3782 extra upper bits? 3783 3784*expression(E)* 3785 The previous value of this register is located at the location description 3786 produced by evaluating the DWARF operation expression E (see 3787 :ref:`amdgpu-dwarf-operation-expressions`). 3788 3789 E is evaluated with the current context, except the result kind is a location 3790 description, the compilation unit is unspecified, the object is unspecified, 3791 and an initial stack comprising the location description of the current CFA 3792 (see :ref:`amdgpu-dwarf-operation-expressions`). 3793 3794*val_expression(E)* 3795 The previous value of this register is the value produced by evaluating the 3796 DWARF operation expression E (see :ref:`amdgpu-dwarf-operation-expressions`). 3797 3798 E is evaluated with the current context, except the result kind is a value, 3799 the compilation unit is unspecified, the object is unspecified, and an initial 3800 stack comprising the location description of the current CFA (see 3801 :ref:`amdgpu-dwarf-operation-expressions`). 3802 3803 The DWARF is ill-formed if the resulting value type size does not match the 3804 register size. 3805 3806 .. note:: 3807 3808 This has limited usefulness as the DWARF expression E can only produce 3809 values up to the size of the generic type. This is due to not allowing any 3810 operations that specify a type in a CFI operation expression. This makes it 3811 unusable for registers that are larger than the generic type. However, 3812 *expression(E)* can be used to create an implicit location description of 3813 any size. 3814 3815*architectural* 3816 The rule is defined externally to this specification by the augmenter. 3817 3818A Common Information Entry (CIE) holds information that is shared among many 3819Frame Description Entries (FDE). There is at least one CIE in every non-empty 3820``.debug_frame`` section. A CIE contains the following fields, in order: 3821 38221. ``length`` (initial length) 3823 3824 A constant that gives the number of bytes of the CIE structure, not 3825 including the length field itself. The size of the length field plus the 3826 value of length must be an integral multiple of the address size specified 3827 in the ``address_size`` field. 3828 38292. ``CIE_id`` (4 or 8 bytes, see 3830 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`) 3831 3832 A constant that is used to distinguish CIEs from FDEs. 3833 3834 In the 32-bit DWARF format, the value of the CIE id in the CIE header is 3835 0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff. 3836 38373. ``version`` (ubyte) 3838 3839 A version number. This number is specific to the call frame information and 3840 is independent of the DWARF version number. 3841 3842 The value of the CIE version number is 4. 3843 3844 .. note:: 3845 3846 Would this be increased to 5 to reflect the changes in these extensions? 3847 38484. ``augmentation`` (sequence of UTF-8 characters) 3849 3850 A null-terminated UTF-8 string that identifies the augmentation to this CIE 3851 or to the FDEs that use it. If a reader encounters an augmentation string 3852 that is unexpected, then only the following fields can be read: 3853 3854 * CIE: length, CIE_id, version, augmentation 3855 * FDE: length, CIE_pointer, initial_location, address_range 3856 3857 If there is no augmentation, this value is a zero byte. 3858 3859 *The augmentation string allows users to indicate that there is additional 3860 vendor and target architecture specific information in the CIE or FDE which 3861 is needed to virtually unwind a stack frame. For example, this might be 3862 information about dynamically allocated data which needs to be freed on exit 3863 from the routine.* 3864 3865 *Because the* ``.debug_frame`` *section is useful independently of any* 3866 ``.debug_info`` *section, the augmentation string always uses UTF-8 3867 encoding.* 3868 3869 The recommended format for the augmentation string is: 3870 3871 | ``[``\ *vendor*\ ``:v``\ *X*\ ``.``\ *Y*\ [\ ``:``\ *options*\ ]\ ``]``\ * 3872 3873 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y 3874 version number of the extensions used, and *options* is an optional string 3875 providing additional information about the extensions. The version number 3876 must conform to semantic versioning [:ref:`SEMVER <amdgpu-dwarf-SEMVER>`]. 3877 The *options* string must not contain the "\ ``]``\ " character. 3878 3879 For example: 3880 3881 :: 3882 3883 [abc:v0.0][def:v1.2:feature-a=on,feature-b=3] 3884 38855. ``address_size`` (ubyte) 3886 3887 The size of a target address in this CIE and any FDEs that use it, in bytes. 3888 If a compilation unit exists for this frame, its address size must match the 3889 address size here. 3890 38916. ``segment_selector_size`` (ubyte) 3892 3893 The size of a segment selector in this CIE and any FDEs that use it, in 3894 bytes. 3895 38967. ``code_alignment_factor`` (unsigned LEB128) 3897 3898 A constant that is factored out of all advance location instructions (see 3899 :ref:`amdgpu-dwarf-row-creation-instructions`). The resulting value is 3900 ``(operand * code_alignment_factor)``. 3901 39028. ``data_alignment_factor`` (signed LEB128) 3903 3904 A constant that is factored out of certain offset instructions (see 3905 :ref:`amdgpu-dwarf-cfa-definition-instructions` and 3906 :ref:`amdgpu-dwarf-register-rule-instructions`). The resulting value is 3907 ``(operand * data_alignment_factor)``. 3908 39099. ``return_address_register`` (unsigned LEB128) 3910 3911 An unsigned LEB128 constant that indicates which column in the rule table 3912 represents the return address of the subprogram. Note that this column might 3913 not correspond to an actual machine register. 3914 3915 The value of the return address register is used to determine the program 3916 location of the caller frame. The program location of the top frame is the 3917 target architecture program counter value of the current thread. 3918 391910. ``initial_instructions`` (array of ubyte) 3920 3921 A sequence of rules that are interpreted to create the initial setting of 3922 each column in the table. 3923 3924 The default rule for all columns before interpretation of the initial 3925 instructions is the undefined rule. However, an ABI authoring body or a 3926 compilation system authoring body may specify an alternate default value for 3927 any or all columns. 3928 392911. ``padding`` (array of ubyte) 3930 3931 Enough ``DW_CFA_nop`` instructions to make the size of this entry match the 3932 length value above. 3933 3934An FDE contains the following fields, in order: 3935 39361. ``length`` (initial length) 3937 3938 A constant that gives the number of bytes of the header and instruction 3939 stream for this subprogram, not including the length field itself. The size 3940 of the length field plus the value of length must be an integral multiple of 3941 the address size. 3942 39432. ``CIE_pointer`` (4 or 8 bytes, see 3944 :ref:`amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats`) 3945 3946 A constant offset into the ``.debug_frame`` section that denotes the CIE 3947 that is associated with this FDE. 3948 39493. ``initial_location`` (segment selector and target address) 3950 3951 The address of the first location associated with this table entry. If the 3952 segment_selector_size field of this FDE’s CIE is non-zero, the initial 3953 location is preceded by a segment selector of the given length. 3954 39554. ``address_range`` (target address) 3956 3957 The number of bytes of program instructions described by this entry. 3958 39595. ``instructions`` (array of ubyte) 3960 3961 A sequence of table defining instructions that are described in 3962 :ref:`amdgpu-dwarf-call-frame-instructions`. 3963 39646. ``padding`` (array of ubyte) 3965 3966 Enough ``DW_CFA_nop`` instructions to make the size of this entry match the 3967 length value above. 3968 3969.. _amdgpu-dwarf-call-frame-instructions: 3970 3971A.6.4.2 Call Frame Instructions 3972+++++++++++++++++++++++++++++++ 3973 3974Some call frame instructions have operands that are encoded as DWARF operation 3975expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF 3976operations that can be used in E have the following restrictions: 3977 3978* ``DW_OP_addrx``, ``DW_OP_call2``, ``DW_OP_call4``, ``DW_OP_call_ref``, 3979 ``DW_OP_const_type``, ``DW_OP_constx``, ``DW_OP_convert``, 3980 ``DW_OP_deref_type``, ``DW_OP_fbreg``, ``DW_OP_implicit_pointer``, 3981 ``DW_OP_regval_type``, ``DW_OP_reinterpret``, and ``DW_OP_xderef_type`` 3982 operations are not allowed because the call frame information must not depend 3983 on other debug sections. 3984 3985* ``DW_OP_push_object_address`` is not allowed because there is no object 3986 context to provide a value to push. 3987 3988* ``DW_OP_LLVM_push_lane`` is not allowed because the call frame instructions 3989 describe the actions for the whole thread, not the lanes independently. 3990 3991* ``DW_OP_call_frame_cfa`` and ``DW_OP_entry_value`` are not allowed because 3992 their use would be circular. 3993 3994* ``DW_OP_LLVM_call_frame_entry_reg`` is not allowed if evaluating E causes a 3995 circular dependency between ``DW_OP_LLVM_call_frame_entry_reg`` operations. 3996 3997 *For example, if a register R1 has a* ``DW_CFA_def_cfa_expression`` 3998 *instruction that evaluates a* ``DW_OP_LLVM_call_frame_entry_reg`` *operation 3999 that specifies register R2, and register R2 has a* 4000 ``DW_CFA_def_cfa_expression`` *instruction that that evaluates a* 4001 ``DW_OP_LLVM_call_frame_entry_reg`` *operation that specifies register R1.* 4002 4003*Call frame instructions to which these restrictions apply include* 4004``DW_CFA_def_cfa_expression``\ *,* ``DW_CFA_expression``\ *, and* 4005``DW_CFA_val_expression``\ *.* 4006 4007.. _amdgpu-dwarf-row-creation-instructions: 4008 4009A.6.4.2.1 Row Creation Instructions 4010################################### 4011 4012.. note:: 4013 4014 These instructions are the same as in DWARF Version 5 section 6.4.2.1. 4015 4016.. _amdgpu-dwarf-cfa-definition-instructions: 4017 4018A.6.4.2.2 CFA Definition Instructions 4019##################################### 4020 40211. ``DW_CFA_def_cfa`` 4022 4023 The ``DW_CFA_def_cfa`` instruction takes two unsigned LEB128 operands 4024 representing a register number R and a (non-factored) byte displacement B. 4025 AS is set to the target architecture default address space identifier. The 4026 required action is to define the current CFA rule to be the result of 4027 evaluating the DWARF operation expression ``DW_OP_constu AS; 4028 DW_OP_aspace_bregx R, B`` as a location description. 4029 40302. ``DW_CFA_def_cfa_sf`` 4031 4032 The ``DW_CFA_def_cfa_sf`` instruction takes two operands: an unsigned LEB128 4033 value representing a register number R and a signed LEB128 factored byte 4034 displacement B. AS is set to the target architecture default address space 4035 identifier. The required action is to define the current CFA rule to be the 4036 result of evaluating the DWARF operation expression ``DW_OP_constu AS; 4037 DW_OP_aspace_bregx R, B * data_alignment_factor`` as a location description. 4038 4039 *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second 4040 operand is signed and factored.* 4041 40423. ``DW_CFA_LLVM_def_aspace_cfa`` *New* 4043 4044 The ``DW_CFA_LLVM_def_aspace_cfa`` instruction takes three unsigned LEB128 4045 operands representing a register number R, a (non-factored) byte 4046 displacement B, and a target architecture specific address space identifier 4047 AS. The required action is to define the current CFA rule to be the result 4048 of evaluating the DWARF operation expression ``DW_OP_constu AS; 4049 DW_OP_aspace_bregx R, B`` as a location description. 4050 4051 If AS is not one of the values defined by the target architecture specific 4052 ``DW_ASPACE_*`` values then the DWARF expression is ill-formed. 4053 40544. ``DW_CFA_LLVM_def_aspace_cfa_sf`` *New* 4055 4056 The ``DW_CFA_def_cfa_sf`` instruction takes three operands: an unsigned 4057 LEB128 value representing a register number R, a signed LEB128 factored byte 4058 displacement B, and an unsigned LEB128 value representing a target 4059 architecture specific address space identifier AS. The required action is to 4060 define the current CFA rule to be the result of evaluating the DWARF 4061 operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, 4062 B * data_alignment_factor`` as a location description. 4063 4064 If AS is not one of the values defined by the target architecture specific 4065 ``DW_ASPACE_*`` values, then the DWARF expression is ill-formed. 4066 4067 *The action is the same as* ``DW_CFA_aspace_def_cfa``\ *, except that the 4068 second operand is signed and factored.* 4069 40705. ``DW_CFA_def_cfa_register`` 4071 4072 The ``DW_CFA_def_cfa_register`` instruction takes a single unsigned LEB128 4073 operand representing a register number R. The required action is to define 4074 the current CFA rule to be the result of evaluating the DWARF operation 4075 expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, B`` as a location 4076 description. B and AS are the old CFA byte displacement and address space 4077 respectively. 4078 4079 If the subprogram has no current CFA rule, or the rule was defined by a 4080 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed. 4081 40826. ``DW_CFA_def_cfa_offset`` 4083 4084 The ``DW_CFA_def_cfa_offset`` instruction takes a single unsigned LEB128 4085 operand representing a (non-factored) byte displacement B. The required 4086 action is to define the current CFA rule to be the result of evaluating the 4087 DWARF operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, B`` as a 4088 location description. R and AS are the old CFA register number and address 4089 space respectively. 4090 4091 If the subprogram has no current CFA rule, or the rule was defined by a 4092 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed. 4093 40947. ``DW_CFA_def_cfa_offset_sf`` 4095 4096 The ``DW_CFA_def_cfa_offset_sf`` instruction takes a signed LEB128 operand 4097 representing a factored byte displacement B. The required action is to 4098 define the current CFA rule to be the result of evaluating the DWARF 4099 operation expression ``DW_OP_constu AS; DW_OP_aspace_bregx R, B * 4100 data_alignment_factor`` as a location description. R and AS are the old CFA 4101 register number and address space respectively. 4102 4103 If the subprogram has no current CFA rule, or the rule was defined by a 4104 ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed. 4105 4106 *The action is the same as* ``DW_CFA_def_cfa_offset``\ *, except that the 4107 operand is signed and factored.* 4108 41098. ``DW_CFA_def_cfa_expression`` 4110 4111 The ``DW_CFA_def_cfa_expression`` instruction takes a single operand encoded 4112 as a ``DW_FORM_exprloc`` value representing a DWARF operation expression E. 4113 The required action is to define the current CFA rule to be the result of 4114 evaluating E with the current context, except the result kind is a location 4115 description, the compilation unit is unspecified, the object is unspecified, 4116 and an empty initial stack. 4117 4118 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on 4119 the DWARF expression operations that can be used in E.* 4120 4121 The DWARF is ill-formed if the result of evaluating E is not a memory byte 4122 address location description. 4123 4124.. _amdgpu-dwarf-register-rule-instructions: 4125 4126A.6.4.2.3 Register Rule Instructions 4127#################################### 4128 41291. ``DW_CFA_undefined`` 4130 4131 The ``DW_CFA_undefined`` instruction takes a single unsigned LEB128 operand 4132 that represents a register number R. The required action is to set the rule 4133 for the register specified by R to ``undefined``. 4134 41352. ``DW_CFA_same_value`` 4136 4137 The ``DW_CFA_same_value`` instruction takes a single unsigned LEB128 operand 4138 that represents a register number R. The required action is to set the rule 4139 for the register specified by R to ``same value``. 4140 41413. ``DW_CFA_offset`` 4142 4143 The ``DW_CFA_offset`` instruction takes two operands: a register number R 4144 (encoded with the opcode) and an unsigned LEB128 constant representing a 4145 factored displacement B. The required action is to change the rule for the 4146 register specified by R to be an *offset(B \* data_alignment_factor)* rule. 4147 4148 .. note:: 4149 4150 Seems this should be named ``DW_CFA_offset_uf`` since the offset is 4151 unsigned factored. 4152 41534. ``DW_CFA_offset_extended`` 4154 4155 The ``DW_CFA_offset_extended`` instruction takes two unsigned LEB128 4156 operands representing a register number R and a factored displacement B. 4157 This instruction is identical to ``DW_CFA_offset``, except for the encoding 4158 and size of the register operand. 4159 4160 .. note:: 4161 4162 Seems this should be named ``DW_CFA_offset_extended_uf`` since the 4163 displacement is unsigned factored. 4164 41655. ``DW_CFA_offset_extended_sf`` 4166 4167 The ``DW_CFA_offset_extended_sf`` instruction takes two operands: an 4168 unsigned LEB128 value representing a register number R and a signed LEB128 4169 factored displacement B. This instruction is identical to 4170 ``DW_CFA_offset_extended``, except that B is signed. 4171 41726. ``DW_CFA_val_offset`` 4173 4174 The ``DW_CFA_val_offset`` instruction takes two unsigned LEB128 operands 4175 representing a register number R and a factored displacement B. The required 4176 action is to change the rule for the register indicated by R to be a 4177 *val_offset(B \* data_alignment_factor)* rule. 4178 4179 .. note:: 4180 4181 Seems this should be named ``DW_CFA_val_offset_uf`` since the displacement 4182 is unsigned factored. 4183 4184 .. note:: 4185 4186 An alternative is to define ``DW_CFA_val_offset`` to implicitly use the 4187 target architecture default address space, and add another operation that 4188 specifies the address space. 4189 41907. ``DW_CFA_val_offset_sf`` 4191 4192 The ``DW_CFA_val_offset_sf`` instruction takes two operands: an unsigned 4193 LEB128 value representing a register number R and a signed LEB128 factored 4194 displacement B. This instruction is identical to ``DW_CFA_val_offset``, 4195 except that B is signed. 4196 41978. ``DW_CFA_register`` 4198 4199 The ``DW_CFA_register`` instruction takes two unsigned LEB128 operands 4200 representing register numbers R1 and R2 respectively. The required action is 4201 to set the rule for the register specified by R1 to be a *register(R2)* rule. 4202 42039. ``DW_CFA_expression`` 4204 4205 The ``DW_CFA_expression`` instruction takes two operands: an unsigned LEB128 4206 value representing a register number R, and a ``DW_FORM_block`` value 4207 representing a DWARF operation expression E. The required action is to 4208 change the rule for the register specified by R to be an *expression(E)* 4209 rule. 4210 4211 *That is, E computes the location description where the register value can 4212 be retrieved.* 4213 4214 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on 4215 the DWARF expression operations that can be used in E.* 4216 421710. ``DW_CFA_val_expression`` 4218 4219 The ``DW_CFA_val_expression`` instruction takes two operands: an unsigned 4220 LEB128 value representing a register number R, and a ``DW_FORM_block`` value 4221 representing a DWARF operation expression E. The required action is to 4222 change the rule for the register specified by R to be a *val_expression(E)* 4223 rule. 4224 4225 *That is, E computes the value of register R.* 4226 4227 *See* :ref:`amdgpu-dwarf-call-frame-instructions` *regarding restrictions on 4228 the DWARF expression operations that can be used in E.* 4229 4230 If the result of evaluating E is not a value with a base type size that 4231 matches the register size, then the DWARF is ill-formed. 4232 423311. ``DW_CFA_restore`` 4234 4235 The ``DW_CFA_restore`` instruction takes a single operand (encoded with the 4236 opcode) that represents a register number R. The required action is to 4237 change the rule for the register specified by R to the rule assigned it by 4238 the ``initial_instructions`` in the CIE. 4239 424012. ``DW_CFA_restore_extended`` 4241 4242 The ``DW_CFA_restore_extended`` instruction takes a single unsigned LEB128 4243 operand that represents a register number R. This instruction is identical 4244 to ``DW_CFA_restore``, except for the encoding and size of the register 4245 operand. 4246 4247A.6.4.2.4 Row State Instructions 4248################################ 4249 4250.. note:: 4251 4252 These instructions are the same as in DWARF Version 5 section 6.4.2.4. 4253 4254A.6.4.2.5 Padding Instruction 4255############################# 4256 4257.. note:: 4258 4259 These instructions are the same as in DWARF Version 5 section 6.4.2.5. 4260 4261A.6.4.3 Call Frame Instruction Usage 4262++++++++++++++++++++++++++++++++++++ 4263 4264.. note:: 4265 4266 The same as in DWARF Version 5 section 6.4.3. 4267 4268.. _amdgpu-dwarf-call-frame-calling-address: 4269 4270A.6.4.4 Call Frame Calling Address 4271++++++++++++++++++++++++++++++++++ 4272 4273.. note:: 4274 4275 The same as in DWARF Version 5 section 6.4.4. 4276 4277A.7 Data Representation 4278----------------------- 4279 4280.. note:: 4281 4282 This section provides changes to existing debugger information entry 4283 attributes. These would be incorporated into the corresponding DWARF Version 5 4284 chapter 7 sections. 4285 4286.. _amdgpu-dwarf-32-bit-and-64-bit-dwarf-formats: 4287 4288A.7.4 32-Bit and 64-Bit DWARF Formats 4289~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4290 4291.. note:: 4292 4293 This augments DWARF Version 5 section 7.4 list item 3's table. 4294 4295.. table:: ``.debug_info`` section attribute form roles 4296 :name: amdgpu-dwarf-debug-info-section-attribute-form-roles-table 4297 4298 ================================== =================================== 4299 Form Role 4300 ================================== =================================== 4301 DW_OP_LLVM_aspace_implicit_pointer offset in ``.debug_info`` 4302 ================================== =================================== 4303 4304A.7.5 Format of Debugging Information 4305~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4306 4307A.7.5.4 Attribute Encodings 4308+++++++++++++++++++++++++++ 4309 4310.. note:: 4311 4312 This augments DWARF Version 5 section 7.5.4 and Table 7.5. 4313 4314The following table gives the encoding of the additional debugging information 4315entry attributes. 4316 4317.. table:: Attribute encodings 4318 :name: amdgpu-dwarf-attribute-encodings-table 4319 4320 ================================== ====== =================================== 4321 Attribute Name Value Classes 4322 ================================== ====== =================================== 4323 DW_AT_LLVM_active_lane 0x3e08 exprloc, loclist 4324 DW_AT_LLVM_augmentation 0x3e09 string 4325 DW_AT_LLVM_lanes 0x3e0a constant 4326 DW_AT_LLVM_lane_pc 0x3e0b exprloc, loclist 4327 DW_AT_LLVM_vector_size 0x3e0c constant 4328 ================================== ====== =================================== 4329 4330.. _amdgpu-dwarf-classes-and-forms: 4331 4332A.7.5.5 Classes and Forms 4333+++++++++++++++++++++++++ 4334 4335.. note:: 4336 4337 The same as in DWARF Version 5 section 7.5.5. 4338 4339A.7.7 DWARF Expressions 4340~~~~~~~~~~~~~~~~~~~~~~~ 4341 4342.. note:: 4343 4344 Rename DWARF Version 5 section 7.7 to reflect the unification of location 4345 descriptions into DWARF expressions. 4346 4347A.7.7.1 Operation Expressions 4348+++++++++++++++++++++++++++++ 4349 4350.. note:: 4351 4352 Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect the 4353 unification of location descriptions into DWARF expressions. 4354 4355 This augments DWARF Version 5 section 7.7.1 and Table 7.9. 4356 4357The following table gives the encoding of the additional DWARF expression 4358operations. 4359 4360.. table:: DWARF Operation Encodings 4361 :name: amdgpu-dwarf-operation-encodings-table 4362 4363 ================================== ===== ======== =============================== 4364 Operation Code Number Notes 4365 of 4366 Operands 4367 ================================== ===== ======== =============================== 4368 DW_OP_LLVM_form_aspace_address 0xe1 0 4369 DW_OP_LLVM_push_lane 0xe2 0 4370 DW_OP_LLVM_offset 0xe3 0 4371 DW_OP_LLVM_offset_uconst 0xe4 1 ULEB128 byte displacement 4372 DW_OP_LLVM_bit_offset 0xe5 0 4373 DW_OP_LLVM_call_frame_entry_reg 0xe6 1 ULEB128 register number 4374 DW_OP_LLVM_undefined 0xe7 0 4375 DW_OP_LLVM_aspace_bregx 0xe8 2 ULEB128 register number, 4376 ULEB128 byte displacement 4377 DW_OP_LLVM_aspace_implicit_pointer 0xe9 2 4-byte or 8-byte offset of DIE, 4378 SLEB128 byte displacement 4379 DW_OP_LLVM_piece_end 0xea 0 4380 DW_OP_LLVM_extend 0xeb 2 ULEB128 bit size, 4381 ULEB128 count 4382 DW_OP_LLVM_select_bit_piece 0xec 2 ULEB128 bit size, 4383 ULEB128 count 4384 ================================== ===== ======== =============================== 4385 4386A.7.7.3 Location List Expressions 4387+++++++++++++++++++++++++++++++++ 4388 4389.. note:: 4390 4391 Rename DWARF Version 5 section 7.7.3 to reflect that location lists are a kind 4392 of DWARF expression. 4393 4394A.7.12 Source Languages 4395~~~~~~~~~~~~~~~~~~~~~~~ 4396 4397.. note:: 4398 4399 This augments DWARF Version 5 section 7.12 and Table 7.17. 4400 4401The following table gives the encoding of the additional DWARF languages. 4402 4403.. table:: Language encodings 4404 :name: amdgpu-dwarf-language-encodings-table 4405 4406 ==================== ====== =================== 4407 Language Name Value Default Lower Bound 4408 ==================== ====== =================== 4409 ``DW_LANG_LLVM_HIP`` 0x8100 0 4410 ==================== ====== =================== 4411 4412A.7.13 Address Class and Address Space Encodings 4413~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4414 4415.. note:: 4416 4417 This replaces DWARF Version 5 section 7.13. 4418 4419The encodings of the constants used for the currently defined address classes 4420are given in :ref:`amdgpu-dwarf-address-class-encodings-table`. 4421 4422.. table:: Address class encodings 4423 :name: amdgpu-dwarf-address-class-encodings-table 4424 4425 ========================== ====== 4426 Address Class Name Value 4427 ========================== ====== 4428 ``DW_ADDR_none`` 0x0000 4429 ``DW_ADDR_LLVM_global`` 0x0001 4430 ``DW_ADDR_LLVM_constant`` 0x0002 4431 ``DW_ADDR_LLVM_group`` 0x0003 4432 ``DW_ADDR_LLVM_private`` 0x0004 4433 ``DW_ADDR_LLVM_lo_user`` 0x8000 4434 ``DW_ADDR_LLVM_hi_user`` 0xffff 4435 ========================== ====== 4436 4437A.7.22 Line Number Information 4438~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4439 4440.. note:: 4441 4442 This augments DWARF Version 5 section 7.22 and Table 7.27. 4443 4444The following table gives the encoding of the additional line number header 4445entry formats. 4446 4447.. table:: Line number header entry format encodings 4448 :name: amdgpu-dwarf-line-number-header-entry-format-encodings-table 4449 4450 ==================================== ==================== 4451 Line number header entry format name Value 4452 ==================================== ==================== 4453 ``DW_LNCT_LLVM_source`` 0x2001 4454 ``DW_LNCT_LLVM_is_MD5`` 0x2002 4455 ==================================== ==================== 4456 4457A.7.24 Call Frame Information 4458~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4459 4460.. note:: 4461 4462 This augments DWARF Version 5 section 7.24 and Table 7.29. 4463 4464The following table gives the encoding of the additional call frame information 4465instructions. 4466 4467.. table:: Call frame instruction encodings 4468 :name: amdgpu-dwarf-call-frame-instruction-encodings-table 4469 4470 ============================= ====== ====== ================ ================ ===================== 4471 Instruction High 2 Low 6 Operand 1 Operand 2 Operand 3 4472 Bits Bits 4473 ============================= ====== ====== ================ ================ ===================== 4474 DW_CFA_LLVM_def_aspace_cfa 0 0x30 ULEB128 register ULEB128 offset ULEB128 address space 4475 DW_CFA_LLVM_def_aspace_cfa_sf 0 0x31 ULEB128 register SLEB128 offset ULEB128 address space 4476 ============================= ====== ====== ================ ================ ===================== 4477 4478A. Attributes by Tag Value (Informative) 4479---------------------------------------- 4480 4481.. note:: 4482 4483 This augments DWARF Version 5 Appendix A and Table A.1. 4484 4485The following table provides the additional attributes that are applicable to 4486debugger information entries. 4487 4488.. table:: Attributes by tag value 4489 :name: amdgpu-dwarf-attributes-by-tag-value-table 4490 4491 ============================= ============================= 4492 Tag Name Applicable Attributes 4493 ============================= ============================= 4494 ``DW_TAG_base_type`` * ``DW_AT_LLVM_vector_size`` 4495 ``DW_TAG_compile_unit`` * ``DW_AT_LLVM_augmentation`` 4496 ``DW_TAG_entry_point`` * ``DW_AT_LLVM_active_lane`` 4497 * ``DW_AT_LLVM_lane_pc`` 4498 * ``DW_AT_LLVM_lanes`` 4499 ``DW_TAG_inlined_subroutine`` * ``DW_AT_LLVM_active_lane`` 4500 * ``DW_AT_LLVM_lane_pc`` 4501 * ``DW_AT_LLVM_lanes`` 4502 ``DW_TAG_subprogram`` * ``DW_AT_LLVM_active_lane`` 4503 * ``DW_AT_LLVM_lane_pc`` 4504 * ``DW_AT_LLVM_lanes`` 4505 ============================= ============================= 4506 4507.. _amdgpu-dwarf-examples: 4508 4509B. Examples 4510=========== 4511 4512The AMD GPU specific usage of the features in these extensions, including 4513examples, is available at *User Guide for AMDGPU Backend* section 4514:ref:`amdgpu-dwarf-debug-information`. 4515 4516.. note:: 4517 4518 Change examples to use ``DW_OP_LLVM_offset`` instead of ``DW_OP_add`` when 4519 acting on a location description. 4520 4521 Need to provide examples of new features. 4522 4523.. _amdgpu-dwarf-references: 4524 4525C. References 4526============= 4527 4528 .. _amdgpu-dwarf-AMD: 4529 45301. [AMD] `Advanced Micro Devices <https://www.amd.com/>`__ 4531 4532 .. _amdgpu-dwarf-AMD-ROCgdb: 4533 45342. [AMD-ROCgdb] `AMD ROCm Debugger (ROCgdb) <https://github.com/ROCm-Developer-Tools/ROCgdb>`__ 4535 4536 .. _amdgpu-dwarf-AMD-ROCm: 4537 45383. [AMD-ROCm] `AMD ROCm Platform <https://rocm-documentation.readthedocs.io>`__ 4539 4540 .. _amdgpu-dwarf-AMDGPU-DWARF-LOC: 4541 45424. [AMDGPU-DWARF-LOC] `Allow Location Descriptions on the DWARF Expression Stack <https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html>`__ 4543 4544 .. _amdgpu-dwarf-AMDGPU-LLVM: 4545 45465. [AMDGPU-LLVM] `User Guide for AMDGPU LLVM Backend <https://llvm.org/docs/AMDGPUUsage.html>`__ 4547 4548 .. _amdgpu-dwarf-CUDA: 4549 45506. [CUDA] `Nvidia CUDA Language <https://docs.nvidia.com/cuda/cuda-c-programming-guide/>`__ 4551 4552 .. _amdgpu-dwarf-DWARF: 4553 45547. [DWARF] `DWARF Debugging Information Format <http://dwarfstd.org/>`__ 4555 4556 .. _amdgpu-dwarf-ELF: 4557 45588. [ELF] `Executable and Linkable Format (ELF) <http://www.sco.com/developers/gabi/>`__ 4559 4560 .. _amdgpu-dwarf-GCC: 4561 45629. [GCC] `GCC: The GNU Compiler Collection <https://www.gnu.org/software/gcc/>`__ 4563 4564 .. _amdgpu-dwarf-GDB: 4565 456610. [GDB] `GDB: The GNU Project Debugger <https://www.gnu.org/software/gdb/>`__ 4567 4568 .. _amdgpu-dwarf-HIP: 4569 457011. [HIP] `HIP Programming Guide <https://rocm-documentation.readthedocs.io/en/latest/Programming_Guides/Programming-Guides.html#hip-programing-guide>`__ 4571 4572 .. _amdgpu-dwarf-HSA: 4573 457412. [HSA] `Heterogeneous System Architecture (HSA) Foundation <http://www.hsafoundation.com/>`__ 4575 4576 .. _amdgpu-dwarf-LLVM: 4577 457813. [LLVM] `The LLVM Compiler Infrastructure <https://llvm.org/>`__ 4579 4580 .. _amdgpu-dwarf-OpenCL: 4581 458214. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__ 4583 4584 .. _amdgpu-dwarf-Perforce-TotalView: 4585 458615. [Perforce-TotalView] `Perforce TotalView HPC Debugging Software <https://totalview.io/products/totalview>`__ 4587 4588 .. _amdgpu-dwarf-SEMVER: 4589 459016. [SEMVER] `Semantic Versioning <https://semver.org/>`__ 4591