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