Lines Matching full:the

26 execute on multiple devices within the same native process. Devices could
30 The AMD [:ref:`AMD <amdgpu-dwarf-AMD>`] ROCm platform [:ref:`AMD-ROCm
31 <amdgpu-dwarf-AMD-ROCm>`] is an implementation of the industry standard for
32 heterogeneous computing devices defined by the Heterogeneous System Architecture
38 The LLVM compiler has upstream support for commercially available AMD GPU
39 hardware (AMDGPU) [:ref:`AMDGPU-LLVM <amdgpu-dwarf-AMDGPU-LLVM>`]. The open
42 also being added by third parties to the GCC [:ref:`GCC <amdgpu-dwarf-GCC>`]
43 compiler and the Perforce TotalView HPC Debugger [:ref:`Perforce-TotalView
48 been identified. The :ref:`amdgpu-dwarf-extensions` section gives an overview of
49 the extensions devised to address the missing features. The extensions seek to
51 is to be applicable to meeting the needs of any heterogeneous system and not be
53 :ref:`amdgpu-dwarf-changes-relative-to-dwarf-version-5` which contains the
54 textual changes for the extensions relative to the DWARF Version 5 standard.
57 :ref:`amdgpu-dwarf-further-examples` links to the AMD GPU specific usage of the
66 The extensions continue to evolve through collaboration with many individuals and
67 active prototyping within the GDB debugger and LLVM compiler. Input has also
68 been very much appreciated from the developers working on the Perforce TotalView
71 The inputs provided and insights gained so far have been incorporated into this
72 current version. The plan is to participate in upstreaming the work and
76 The general principles in designing the extensions have been:
78 1.  Be backwards compatible with the DWARF Version 5 [:ref:`DWARF
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
93 4.  Fully define well-formed DWARF in a consistent style based on the DWARF
96 It is possible that some of the generalizations may also benefit other DWARF
99 The remainder of this section enumerates the extensions and provides motivation
102 .. _amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack:
104 2.1 Allow Location Description on the DWARF Expression Stack
107 DWARF Version 5 does not allow location descriptions to be entries on the DWARF
108 expression stack. They can only be the final result of the evaluation of a DWARF
110 entry on the DWARF expression stack it becomes possible to compose expressions
117 value that represents an address in the default address space to a memory
121 while enabling the ability to explicitly create memory location descriptions in
122 non-default address spaces and generalizing the power of composite location
125 For those familiar with the definition of location descriptions in DWARF Version
126 5, the definitions in these extensions are presented differently, but does in
127 fact define the same concept with the same fundamental semantics. However, it
128 does so in a way that allows the concept to extend to support address spaces,
129 bit addressing, the ability for composite location descriptions to be composed
130 of any kind of location description, and the ability to support objects located
131 at multiple places. Collectively these changes expand the set of architectures
134 Several approaches were considered, and the one presented, together with the
135 extensions it enables, appears to be the simplest and cleanest one that offers
136 the greatest improvement of DWARF's ability to support debugging optimized GPU
137 and non-GPU code. Examining the GDB debugger and LLVM compiler, it appears only
139 location descriptions. It is anticipated that will also be the case for other
145 rules. The code in GDB actually became simpler as all evaluation is done on a
147 the location description results. This gives confidence in backwards
152 This extension is separately described at *Allow Location Descriptions on the
176 :ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`,
177 the ``DW_OP_push_object_address`` and ``DW_OP_call*`` operations can put a
178 location description on the stack. Furthermore, debugger information entry
181 the expression stack before evaluating the expression.
183 DWARF Version 5 only allows the stack to contain values and so only a single
184 memory address can be on the stack. This makes these operations and attributes
189 :ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
190 allows the stack to contain location descriptions, the operations are
193 places to be supported. For example, the expression that describes how to access
194 the field of an object can be evaluated with a location description that has
197 With this change, the separate DWARF Version 5 sections that described DWARF
200 a necessity of, allowing location descriptions to be part of the evaluation
208 The ``DW_OP_plus`` and ``DW_OP_minus`` operations can be defined to operate on a
209 memory location description in the default target architecture specific address
215 composite of these, the ``DW_OP_LLVM_offset``, ``DW_OP_LLVM_offset_uconst``, and
218 The offset operations can operate on location storage of any size. For example,
220 define offsets that exceed the size of the location storage as being an
224 range. This is simple for the arithmetic operations as they are defined in terms
225 of two's complement arithmetic on a base type of a fixed size. Therefore, the
227 to the ``DW_OP_plus``, ``DW_OP_plus_uconst``, and ``DW_OP_minus`` arithmetic
230 Having the offset operations allows ``DW_OP_push_object_address`` to push a
231 location description that may be in a register, or be an implicit value. The
232 DWARF expression of ``DW_TAG_ptr_to_member_type`` can use the offset operations
236 :ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack` has
241 The ``DW_OP_*piece`` operations only allow literal indices. A way to use a
243 is required. The offset operations provide this ability since they can be used
244 to compute a location description on the stack.
249 proposed since currently the arithmetic operations are defined to require values
250 of the same base type and produces a result with the same base type. Allowing
251 these operations to act on location descriptions would permit the first operand
252 to be a location description and the second operand to be an integral value
253 type, or vice versa, and return a location description. This complicates the
255 descriptions and generic base type values. Currently the rules would convert
256 such a location description to the memory address value and then perform two's
257 compliment wrap around arithmetic. If the result was used as a location
259 memory location description. This is different to the overflow rules on location
274 :ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
275 allows location descriptions to be created on the stack, it is necessary to have
278 For example, the ``DW_OP_LLVM_select_bit_piece`` (see
280 operation takes more than one location description on the stack. Without this
281 ability, it is not possible to specify that a particular one of the input
284 See the ``DW_OP_LLVM_undefined`` operation in
291 that indicates the end of the definition of a composite location description is
292 required. This can be implied if the end of a DWARF expression is reached,
301 The number of registers and the cost of memory operations is much higher for
302 AMDGPU than a typical CPU. The compiler attempts to optimize whole variables and
322 DWARF has the concept of segment addresses. However, the segment cannot be
323 specified within a DWARF expression, which is only able to specify the offset
324 portion of a segment address. The segment index is only provided by the entity
325 that specifies the DWARF expression. Therefore, the segment index is a property
331 a register that is partially spilled to the call stack which is in the private
332 address space, and partially spilled to the local address space. DWARF mentions
333 address spaces, for example as an argument to the ``DW_OP_xderef*`` operations.
338 types (see :ref:`amdgpu-dwarf-type-modifier-entries`). This allows the compiler
339 to specify which address space is being used to represent the pointer or
342 DWARF uses the concept of an address in many expression operations but does not
344 ``DW_OP_push_object_address`` pushes the address of an object. Other contexts
345 implicitly push an address on the stack before evaluating an expression. For
346 example, the ``DW_AT_use_location`` attribute of the
347 ``DW_TAG_ptr_to_member_type``. The expression belongs to a source language type
349 it is desirable that the expression that uses the address can do so without
350 regard to what kind of storage it specifies, including the address space of a
354 The DWARF ``DW_OP_xderef*`` operations allow a value to be converted into an
356 way to create a memory location description for an address in the non-default
357 address space. For example, AMDGPU variables can be allocated in the local
360 The ``DW_OP_LLVM_form_aspace_address`` (see
363 can be used to specify the location of a variable that is allocated in a
364 specific address space. This allows the size of addresses in an address space to
365 be larger than the generic type. It also allows a consumer great implementation
366 freedom. It allows the implicit conversion back to a value to be limited only to
367 the default address space to maintain compatibility with DWARF Version 5. For
368 other address spaces the producer can use the new operations that explicitly
369 specify the address space.
371 In contrast, if the ``DW_OP_LLVM_form_aspace_address`` operation had been
373 description was defined, then it would be limited to the size of the generic
374 type (which matches the size of the default address space). An implementation
376 address spaces. Such a value would likely not match any address value in the
377 actual hardware. That would require the consumer to have special treatment for
380 ``DW_OP_breg*`` treats the register as containing an address in the default
383 to allow the address space of the address held in a register to be specified.
386 in the default address space. A ``DW_OP_LLVM_aspace_implicit_pointer``
388 added to allow the address space to be specified.
391 descriptions, or to be dereferenced to read memory. The exception is
392 ``DW_CFA_val_offset`` which uses the address to set the value of a register. In
393 order to support address spaces, the CFA DWARF expression is defined to be a
395 used to convert the offset address back to an address in that address space. See
399 spaces, allows all existing DWARF Version 5 expressions to have the identical
400 semantics. It allows the compiler to explicitly specify the address space it is
402 swizzled manner when mapping a source language thread to the lane of a wavefront
404 manner if mapping the same language with the wavefront being the thread.
406 It also allows the compiler to mix the address space it uses to access private
412 spaces to be combined using the regular ``DW_OP_*piece`` operations.
414 Location descriptions are an abstraction of storage. They give freedom to the
415 consumer on how to implement them. They allow the address space to encode lane
416 information so they can be used to read memory with only the memory location
417 description and no extra information. The same set of operations can operate on
418 locations independent of their kind of storage. The ``DW_OP_deref*`` therefore
420 different address spaces. Therefore, the ``DW_OP_xderef*`` operations are
428 The vector registers of the AMDGPU are represented as their full wavefront
429 size, meaning the wavefront size times the dword size. This reflects the
430 actual hardware and allows the compiler to generate DWARF for languages that
431 map a thread to the complete wavefront. It also allows more efficient DWARF to
432 be generated to describe the CFI as only a single expression is required for
433 the whole vector register, rather than a separate expression for each lane's
434 dword of the vector register. It also allows the compiler to produce DWARF
435 that indexes the vector register if it spills scalar registers into portions
439 vector of dwords, the ability to specify that a base type is a vector is
451 entry to the subprogram. To support this the CFI rule for the partially spilled
452 register needs to use an expression that uses the EXEC register as a bit mask to
453 select between the register (for inactive lanes) and the stack spill location
455 description, and not a value, as a debugger needs to change the value if the
456 user assigns to the variable.
459 logical PCs for active and inactive lanes in a SIMT execution model. Again the
464 It may be possible to use existing DWARF to incrementally build the composite
465 location description, possibly using the DWARF operations for control flow to
466 create a loop. However, for the AMDGPU that would require loop iteration of 64.
467 A concern is that the resulting DWARF would have a significant size and would be
469 function. AMDGPU can have up to 512 vector registers. Another concern is the
475 These operations generate the composite location description using a single
476 DWARF operation that combines all lanes of the vector in one step. The DWARF
480 An example that uses these operations is referenced in the
491 a DWARF expression involving the set of SIMT lanes active on entry to a
492 subprogram is required. The SIMT active lane mask may be held in a register that
493 is modified as the subprogram executes. However, its value may be saved on entry
494 to the subprogram.
496 The  Call Frame Information (CFI) already encodes such register saving, so it is
497 more efficient to provide an operation to return the location of a saved
498 register than have to generate a loclist to describe the same information. This
500 :ref:`amdgpu-dwarf-allow-location-description-on-the-dwarf-evaluation-stack`
501 allows location descriptions on the stack.
510 If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner,
511 then the variable DWARF location expressions must compute the location for a
512 single lane of the wavefront. Therefore, a DWARF operation is required to denote
513 the current lane, much like ``DW_OP_push_object_address`` denotes the current
516 In addition, a way is needed for the compiler to communicate how many source
525 If the source language is mapped onto the AMDGPU wavefronts in a SIMT manner the
526 compiler can use the AMDGPU execution mask register to control which lanes are
527 active. To describe the conceptual location of non-active lanes requires an
528 attribute that has an expression that computes the source location PC for each
531 For efficiency, the expression calculates the source location the wavefront as a
532 whole. This can be done using the ``DW_OP_LLVM_select_bit_piece`` (see
536 The AMDGPU may update the execution mask to perform whole wavefront operations.
537 Therefore, there is a need for an attribute that computes the current active
538 lane mask. This can have an expression that may evaluate to the SIMT active lane
541 An example that uses these attributes is referenced in the
564 specific information in the debugging information entries of that compilation
565 unit. This allows a consumer to know what extensions are present in the debugger
566 information entries as is possible with the augmentation string of other
569 The format that should be used for an augmentation string is also recommended.
570 This allows a consumer to parse the string when it contains information from
571 multiple vendors. Augmentation strings occur in the ``DW_AT_LLVM_augmentation``
572 attribute, in the lookup by name table, and in the CFI Common Information Entry
582 AMDGPU supports programming languages that include online compilation where the
583 source text may be created at runtime. For example, the OpenCL and HIP language
584 runtimes support online compilation. To support is, a way to embed the source
585 text in the debug information is provided.
592 In DWARF Version 5 the file timestamp and file size can be optional, but if the
596 optionally present in the line table is added.
600 2.18 Add the HIP Programing Language
603 The HIP programming language [:ref:`HIP <amdgpu-dwarf-HIP>`], which is supported
604 by the AMDGPU, is added.
611 A compiler can perform loop optimizations that result in the generated code
613 schedules multiple iterations in an interleaved fashion to allow the
614 instructions of one iteration to hide the latencies of the instructions of
619 Note that although this is similar to SIMT execution, the way a client debugger
620 uses the information is fundamentally different. In SIMT execution the debugger
621 needs to present the concurrent execution as distinct source language threads
622 that the user can list and switch focus between. With iteration concurrency
623 optimizations, such as software pipelining and vectorized SIMD, the debugger
624 must not present the concurrency as distinct source language threads. Instead,
625 it must inform the user that multiple loop iterations are executing in parallel
626 and allow the user to select between them.
628 In general, SIMT execution fixes the number of concurrent executions per target
630 may vary the number of concurrent iterations for different loops executed by a
633 It is possible for the compiler to use both SIMT concurrency and iteration
634 concurrency techniques in the code of a single source language thread.
636 Therefore, a DWARF operation is required to denote the current concurrent
637 iteration instance, much like ``DW_OP_push_object_address`` denotes the current
641 In addition, a way is needed for the compiler to communicate how many source
648 It is common in SIMD vectorization for the compiler to generate code that
649 promotes portions of an array into vector registers. For example, if the
650 hardware has vector registers with 8 elements, and 8 wide SIMD instructions, the
654 On the first iteration of the generated vectorized loop, iterations 0 to 7 of
655 the source language loop will be executed using SIMD instructions. Then on the
656 next iteration of the generated vectorized loop, iteration 8 to 15 will be
659 If the source language loop accesses an array element based on the loop
660 iteration index, the compiler may read the element into a register for the
661 duration of that iteration. Next iteration it will read the next element into
662 the register, and so on. With SIMD, this generalizes to the compiler reading
663 array elements 0 to 7 into a vector register on the first vectorized loop
664 iteration, then array elements 8 to 15 on the next iteration, and so on.
666 The DWARF location description for the array needs to express that all elements
667 are in memory, except the slice that has been promoted to the vector register.
668 The starting position of the slice is a runtime value based on the iteration
669 index modulo the vectorization size. This cannot be expressed by ``DW_OP_piece``
673 offset and a size, and creates a composite that effectively uses the second
674 location description as an overlay of the first, positioned according to the
678 Consider an array that has been partially registerized such that the currently
679 processed elements are held in registers, whereas the remainder of the array
680 remains in memory. Consider the loop in this C function, for example:
690 Inside the loop body, the machine code loads ``src[i]`` and ``dst[i]`` into
691 registers, adds them, and stores the result back into ``dst[i]``.
693 Considering the location of ``dst`` and ``src`` in the loop body, the elements
695 located in memory. Let register ``R0`` contain the base address of ``dst``,
696 register ``R1`` contain ``i``, and register ``R2`` contain the registerized
697 ``dst[i]`` element. We can describe the location of ``dst`` as a memory location
709   // 3. Offset of the register within the memory of dst:
714   // 4. The size of the register element:
717   // 5. Make a composite location description for dst that is the memory #1 with
718   //    the register #2 positioned as an overlay at offset #3 of size #4:
736 The vendor extension encoding space for DWARF expression operations
737 accommodates only 32 unique operations. In practice, the lack of a central
740 has produced a situation where the effective encoding space available for new
745 ULEB128 encoded vendor extension opcode, which is then followed by the operands
746 of the corresponding vendor extension operation.
762   Non-normative text is shown in *italics*. The section numbers generally
763   correspond to those in the DWARF Version 5 standard unless specified
764   otherwise. Definitions are given for the additional operations, as well as
769   The names for the new operations, attributes, and constants include "\
778     Notes are included to describe how the changes are to be applied to the
792 The following table provides the additional attributes.
819   and section 2.6. The new DWARF expression operation extensions are defined as
820   well as clarifying the extensions to already existing DWARF Version 5
821   operations. It is based on the text of the existing DWARF Version 5 standard.
825 *The evaluation of a DWARF expression can provide the location of an object, the
826 value of an array bound, the length of a dynamic string, the desired value
829 If the evaluation of a DWARF expression does not encounter an error, then it can
833 description is required as the result kind.
835 If a result kind is specified, and the result of the evaluation does not match
836 the specified result kind, then the implicit conversions described in
838 valid. Otherwise, the DWARF expression is ill-formed.
840 If the evaluation of a DWARF expression encounters an evaluation error, then the
845   Decided to define the concept of an evaluation error. An alternative is to
848   encounter an evaluation error can return the undefined location description or
852   undefined value. The expression would then always evaluate to completion, and
858 If a DWARF expression is ill-formed, then the result is undefined.
860 The following sections detail the rules for when a DWARF expression is
874 self consistent or the result of the evaluation is undefined. The context
879   The kind of result required by the DWARF expression evaluation. If specified
884   The target architecture thread identifier. For source languages that are not
885   implemented using a SIMT execution model, this corresponds to the source
888   execution model, this together with the current lane corresponds to the source
894   *For example, the* ``DW_OP_regval_type`` *operation, or the*
901   The 0 based SIMT lane identifier to be used in evaluating a user presented
904   language threads of execution to lanes of the target architecture threads.
908   *For example, the* ``DW_OP_LLVM_push_lane`` *operation and*
912   If specified, it must be consistent with the value of the ``DW_AT_LLVM_lanes``
913   attribute of the subprogram corresponding to context's frame and program
914   location. It is consistent if the value is greater than or equal to 0 and less
915   than the, possibly default, value of the ``DW_AT_LLVM_lanes`` attribute.
916   Otherwise the result is undefined.
920   The 0 based source language iteration instance to be used in evaluating a user
930   *For example, the* ``DW_OP_LLVM_push_iteration`` *operation.*
932   If specified, it must be consistent with the value of the
933   ``DW_AT_LLVM_iterations`` attribute of the subprogram corresponding to
934   context's frame and program location. It is consistent if the value is greater
935   than or equal to 0 and less than the, possibly default, value of the
936   ``DW_AT_LLVM_iterations`` attribute. Otherwise the result is undefined.
940   The target architecture call frame identifier. It identifies a call frame that
941   corresponds to an active invocation of a subprogram in the current thread. It
942   is identified by its address on the call stack. The address is referred to as
943   the Canonical Frame Address (CFA). The call frame information is used to
944   determine the CFA for the call frames of the current thread's call stack (see
948   support virtual unwinding of the call stack.
950   *For example, the* ``DW_OP_*reg*`` *operations.*
952   If specified, it must be an active call frame in the current thread. If the
954   the call frame (see the ``DW_AT_LLVM_lane_pc`` attribute). Otherwise the
957   If it is the currently executing call frame, then it is termed the top call
962   The target architecture program location corresponding to the current call
963   frame of the current thread.
965   The program location of the top call frame is the target architecture program
966   counter for the current thread. The call frame information is used to obtain
967   the value of the return address register to determine the program location of
968   the other call frames (see :ref:`amdgpu-dwarf-call-frame-information`).
970   It is required for the evaluation of location list expressions to select
972   specify target architecture registers to support virtual unwinding of the call
977   * If the current lane is not specified:
979     * If the current call frame is the top call frame, it must be the current
982     * If the current call frame F is not the top call frame, it must be the
983       program location associated with the call site in the current caller frame
984       F that invoked the callee frame.
986   * If the current lane is specified and the architecture program location LPC
987     computed by the ``DW_AT_LLVM_lane_pc`` attribute for the current lane is not
988     the undefined location description (indicating the lane was not active on
989     entry to the call frame), it must be LPC.
991   * Otherwise the result is undefined.
995   The compilation unit debug information entry that contains the DWARF expression
999   the same compilation unit, including indicating if such references use the
1000   32-bit or 64-bit DWARF format. It can also provide the default address space
1003   *For example, the* ``DW_OP_constx`` *and* ``DW_OP_addrx`` *operations.*
1005   *Note that this compilation unit may not be the same as the compilation unit
1006   determined from the loaded code object corresponding to the current program
1007   location. For example, the evaluation of the expression E associated with a*
1008   ``DW_AT_location`` *attribute of the debug information entry operand of the*
1009   ``DW_OP_call*`` *operations is evaluated with the compilation unit that
1010   contains E and not the one that contains the* ``DW_OP_call*`` *operation
1015   The target architecture.
1021   identifiers, DWARF lane identifiers, DWARF address space identifiers, the
1022   default address space, and the address space address sizes.*
1026   * If the current frame is specified, then the current target architecture must
1027     be the same as the target architecture of the current frame.
1029   * If the current frame is specified and is the top frame, and if the current
1030     thread is specified, then the current target architecture must be the same
1031     as the target architecture of the current thread.
1033   * If the current compilation unit is specified, then the current target
1034     architecture default address space address size must be the same as the
1035     ``address_size`` field in the header of the current compilation unit and any
1036     associated entry in the ``.debug_aranges`` section.
1038   * If the current program location is specified, then the current target
1039     architecture must be the same as the target architecture of any line number
1041     corresponding to the current program location.
1043   * If the current program location is specified, then the current target
1044     architecture default address space address size must be the same as the
1045     ``address_size`` field in the header of any entry corresponding to the
1046     current program location in the ``.debug_addr``, ``.debug_line``,
1050   * Otherwise the result is undefined.
1054   The location description of a program object.
1056   It is required for the ``DW_OP_push_object_address`` operation.
1058   *For example, the* ``DW_AT_data_location`` *attribute on type debug
1059   information entries specifies the program object corresponding to a runtime
1060   descriptor as the current object when it evaluates its associated expression.*
1062   The result is undefined if the location description is invalid (see
1067   This is a list of values or location descriptions that will be pushed on the
1068   operation expression evaluation stack in the order provided before evaluation
1072   expression value with initial stack entries. In all other cases the initial
1075   The result is undefined if any location descriptions are invalid (see
1078 If the evaluation requires a context element that is not specified, then the
1079 result of the evaluation is an error.
1083 For example, the location of a global variable may be able to be evaluated
1084 without such context. If the expression evaluates with an error then it may
1085 indicate the variable has been optimized and so requires more context.*
1087 *The DWARF expression for call frame information (see*
1089 those that do not require the compilation unit context to be specified.*
1091 The DWARF is ill-formed if all the ``address_size`` fields in the headers of all
1092 the entries in the ``.debug_info``, ``.debug_addr``, ``.debug_line``,
1103 supported base type of the target architecture. The base type specifies the
1104 size, encoding, and endianity of the literal value.
1109   used for the type of the value that is produced when the ``DW_OP_deref*``
1110   operation retrieves the full contents of an implicit pointer location storage
1111   created by the ``DW_OP_implicit_pointer`` or
1112   ``DW_OP_LLVM_aspace_implicit_pointer`` operations. The literal value would
1113   record the debugging information entry and byte displacement specified by the
1117 There is a distinguished base type termed the generic type, which is an integral
1118 type that has the size of an address in the target architecture default address
1121 *The generic type is the same as the unspecified type used for stack operations
1126 ``DW_ATE_boolean``, or any target architecture defined integral encoding in the
1139 *Debugging information must provide consumers a way to find the location of
1140 program variables, determine the bounds of dynamic arrays and strings, and
1141 possibly to find the base address of a subprogram’s call frame or the return
1142 address of a subprogram. Furthermore, to meet the needs of recent computer
1144 describe the location of an object whose location changes over the object’s
1148 Information about the location of program objects is provided by location
1153 A single location description specifies the location storage that holds a
1154 program object and a position within the location storage where the program
1155 object starts. The position within the location storage is expressed as a bit
1156 offset relative to the start of the location storage.
1160 offset. The ordering of bits within a location storage uses the bit numbering
1161 and direction conventions that are appropriate to the current language on the
1167   Corresponds to the target architecture memory address spaces.
1170   Corresponds to the target architecture registers.
1180   some from another location storage, or from disjoint parts of the same
1185   It may be better to add an implicit pointer location storage kind used by the
1187   operations. It would specify the debugger information entry and byte offset
1188   provided by the operations.
1193 * *They can be the result of evaluating a debugger information entry attribute
1195   they can describe the location of an object as long as its lifetime is either
1196   static or the same as the lexical block (see
1200 * *They can be the result of evaluating a debugger information entry attribute
1201   that specifies a location list expression. In this usage they can describe the
1205 If a location description has more than one single location description, the
1206 DWARF expression is ill-formed if the object value held in each single location
1207 description's position within the associated location storage is not the same
1208 value, except for the parts of the value that are uninitialized.
1218 used to describe objects that reside in more than one piece of storage at the
1221 to a register for some region of code, but later code may revert to reading the
1222 value from memory as the register may be used for other purposes. For the code
1223 region where the value is in a register, any change to the object value must be
1224 made in both the register and the memory so both regions of code will read the
1228 description can read the object's value from any of the single location
1229 descriptions (since they all refer to location storage that has the same value),
1230 but must write any changed value to all the single location descriptions.*
1232 The evaluation of an expression may require context elements to create a
1233 location description. If such a location description is accessed, the storage it
1234 denotes is that associated with the context element values specified when the
1235 location description was created, which may differ from the context at the time
1238 *For example, creating a register location description requires the thread
1239 context: the location storage is for the specified register of that thread.
1241 thread and a lane context: the location storage is the memory associated with
1244 If any of the context elements required to create a location description change,
1245 the location description becomes invalid and accessing it is undefined.
1249 * *The thread context is required and execution causes the thread to terminate.*
1250 * *The call frame context is required and further execution causes the call
1251   frame to return to the calling frame.*
1252 * *The program location is required and further execution of the thread occurs.
1253   That could change the location list entry or call frame information entry that
1257   * *Any of the frames used in the virtual call frame unwinding return.*
1258   * *The top call frame is used, the program location is used to select the call
1259     frame information entry, and further execution of the thread occurs.*
1262 A subsequent DWARF expression evaluation can be given the object location
1263 description as the object context or initial stack context to compute a
1264 component of the object. The final result is undefined if the object location
1265 description becomes invalid between the two expression evaluations.*
1269 location description, or using it as the object context or initial stack context
1273 the intended program object after a program location change. One way to avoid
1283 of an opcode followed by zero or more operands. The number of operands is
1284 implied by the opcode.
1288 entries on the stack, including adding entries and removing entries. If the kind
1289 of a stack entry does not match the kind required by the operation and is not
1290 implicitly convertible to the required kind (see
1291 :ref:`amdgpu-dwarf-memory-location-description-operations`), then the DWARF
1294 Evaluation of an operation expression starts with an empty stack on which the
1295 entries from the initial stack provided by the context are pushed in the order
1296 provided. Then the operations are evaluated, starting with the first operation
1297 of the stream. Evaluation continues until either an operation has an evaluation
1298 error, or until one past the last operation of the stream is reached.
1300 The result of the evaluation is:
1303   expression that has an evaluation error, then the result is an evaluation
1306 * If the current result kind specifies a location description, then:
1308   * If the stack is empty, the result is a location description with one
1315   * If the top stack entry is a location description, or can be converted
1317     then the result is that, possibly converted, location description. Any other
1318     entries on the stack are discarded.
1320   * Otherwise the DWARF expression is ill-formed.
1325       if the ``DW_OP_implicit`` operation is performed.
1327 * If the current result kind specifies a value, then:
1329   * If the top stack entry is a value, or can be converted to one (see
1330     :ref:`amdgpu-dwarf-memory-location-description-operations`), then the result
1331     is that, possibly converted, value. Any other entries on the stack are
1334   * Otherwise the DWARF expression is ill-formed.
1336 * If the current result kind is not specified, then:
1338   * If the stack is empty, the result is a location description with one
1347       This rule is consistent with the rule above for when a location
1351   * Otherwise, the top stack entry is returned. Any other entries on the stack
1355 specifies the byte count. It can be used:
1357 * as the value of a debugging information entry attribute that is encoded using
1360 * as the operand to certain operation expression operations,
1362 * as the operand to certain call frame information operations (see
1376   operand: a ULEB128 constant identifying a vendor extension operation. The
1377   remaining operands are defined by the vendor extension. The vendor extension
1380   *The DW_OP_user encoding space can be understood to supplement the space
1381   defined by DW_OP_lo_user and DW_OP_hi_user that is allocated by the standard
1382   for the same purpose.*
1393 The following operations manipulate the DWARF stack. Operations that index the
1394 stack assume that the top of the stack (most recently added entry) has index 0.
1395 They allow the stack entries to be either a value or location description.
1399 :ref:`amdgpu-dwarf-composite-location-description-operations`), then the DWARF
1410   descriptions, then would need to define that the composite location storage
1411   specified by the incomplete composite location description is also replicated
1412   when a copy is pushed. This ensures that each copy of the incomplete composite
1413   location description can update the composite location storage they specify
1418     ``DW_OP_dup`` duplicates the stack entry at the top of the stack.
1422     ``DW_OP_drop`` pops the stack entry at the top of the stack and discards it.
1427     I. A copy of the stack entry with index I is pushed onto the stack.
1431     ``DW_OP_over`` pushes a copy of the entry with index 1.
1437     ``DW_OP_swap`` swaps the top two stack entries. The entry at the top of the
1438     stack becomes the second stack entry, and the second stack entry becomes the
1439     top of the stack.
1443     ``DW_OP_rot`` rotates the first three stack entries. The entry at the top of
1444     the stack becomes the third stack entry, the second entry becomes the top of
1445     the stack, and the third entry becomes the second entry.
1459 The following operations provide simple control of the flow of a DWARF operation
1464     ``DW_OP_nop`` is a place holder. It has no effect on the DWARF stack
1472       The same as in DWARF Version 5 section 2.5.1.5.
1477     signed integer constant. The 2-byte constant is the number of bytes of the
1478     DWARF expression to skip forward or backward from the current operation,
1479     beginning after the 2-byte constant.
1481     If the updated position is at one past the end of the last operation, then
1482     the operation expression evaluation is complete.
1484     Otherwise, the DWARF expression is ill-formed if the updated operation
1485     position is not in the range of the first to last operation inclusive, or
1486     not at the start of an operation.
1491     integer constant. This operation pops the top of stack. If the value popped
1492     is not the constant 0, the 2-byte constant operand is the number of bytes of
1493     the DWARF operation expression to skip forward or backward from the current
1494     operation, beginning after the 2-byte constant.
1496     If the updated position is at one past the end of the last operation, then
1497     the operation expression evaluation is complete.
1499     Otherwise, the DWARF expression is ill-formed if the updated operation
1500     position is not in the range of the first to last operation inclusive, or
1501     not at the start of an operation.
1509     a 2-byte or 4-byte unsigned offset DR that represents the byte offset of a
1510     debugging information entry D relative to the beginning of the current
1513     ``DW_OP_call_ref`` has one operand that is a 4-byte unsigned value in the
1514     32-bit DWARF format, or an 8-byte unsigned value in the 64-bit DWARF format,
1515     that represents the byte offset DR of a debugging information entry D
1516     relative to the beginning of the ``.debug_info`` section that contains the
1517     current compilation unit. D may not be in the current compilation unit.
1522       section other than the one that contains the current compilation unit. It
1524       file to another must be performed by the consumer. But given that DR is
1526       If DR was defined as an implementation defined value, then the consumer
1527       could choose to interpret the value in an implementation defined manner to
1530       In ELF the ``.debug_info`` section is in a non-\ ``PT_LOAD`` segment so
1532       segments and dynamic relocations were used, DR would need to be the
1534       need DR to be the size of a global address. So it would not be possible to
1535       use the 32-bit DWARF format in a 64-bit global address space. In addition,
1536       the consumer would need to determine what executable or shared object the
1537       relocated address was in so it could determine the containing compilation
1540       GDB only interprets DR as an offset in the ``.debug_info`` section that
1541       contains the current compilation unit.
1550     The call operation is evaluated by:
1553       that specifies an operation expression E, then execution of the current
1554       operation expression continues from the first operation of E. Execution
1555       continues until one past the last operation of E is reached, at which
1556       point execution continues with the operation following the call operation.
1557       The operations of E are evaluated with the same current context, except
1558       current compilation unit is the one that contains D and the stack is the
1559       same as that being used by the call operation. After the call operation
1560       has been evaluated, the stack is therefore as it is left by the evaluation
1561       of the operations of E. Since E is evaluated on the same stack as the call
1562       operation, E can use, and/or remove entries already on the stack, and can
1563       add new entries to the stack.
1565       *Values on the stack at the time of the call may be used as parameters by
1566       the called expression and values left on the stack by the called expression
1567       may be used as return values by prior agreement between the calling and
1571       ``loclistsptr``, then the specified location list expression E is
1572       evaluated. The evaluation of E uses the current context, except the result
1573       kind is a location description, the compilation unit is the one that
1574       contains D, and the initial stack is empty. The location description
1575       result is pushed on the stack.
1580         entry operation expression on the same stack as the call when there are
1581         multiple matches. But it allows the call to obtain the location
1585         An alternative is to treat the case when D has a ``DW_AT_location``
1586         attribute that is encoded as a ``loclist`` or ``loclistsptr``, and the
1588         entry with operation expression E, the same as the ``exprloc`` case and
1589         evaluate on the same stack.
1591         But this is not attractive as if the attribute is for a variable that
1593         location description on the stack. Presumably the intent of using
1595         entry is to push just one location description on the stack. That
1598         The previous rule for ``exprloc`` also has the same problem, as normally
1600         entries on the stack and only return the top entry.
1602         GDB implements ``DW_OP_call*`` by always executing E on the same stack.
1603         If the location list has multiple matching entries, it simply picks the
1604         first one and ignores the rest. This seems fundamentally at odds with
1605         the desire to support multiple places for variables.
1608         description on the stack for a variable or formal parameter, and also
1609         support being able to execute an operation expression on the same stack.
1614         for the ``DW_TAG_dwarf_procedure`` debugging information entry. Then the
1617         location descriptions), and the ``DW_AT_LLVM_proc`` attribute expression
1618         is always executed on the same stack and can leave anything on the
1621         The ``DW_AT_LLVM_proc`` attribute could have the new classes
1623         the expression is executed on the same stack. ``exprproc`` is the same
1624         encoding as ``exprloc``. ``loclistproc`` and ``loclistsptrproc`` are the
1625         same encoding as their non-\ ``proc`` counterparts, except the DWARF is
1626         ill-formed if the location list does not match exactly one location list
1628         that the matched single operation expression must be executed on the
1631         return a location description. The producer then explicitly indicates
1632         the intent through the attribute classes.
1635         ``DW_OP_call*``. However, are the breaking cases actually occurring in
1636         practice? GDB could implement the current approach for DWARF Version 5,
1637         and the new semantics for DWARF Version 6 which has been done for some
1640         Another option is to limit the execution to be on the same stack only to
1641         the evaluation of an expression E that is the value of a
1643         information entry. The DWARF would be ill-formed if E is a location list
1645         other cases the evaluation of an expression E that is the value of a
1646         ``DW_AT_location`` attribute would evaluate E with the current context,
1647         except the result kind is a location description, the compilation unit
1648         is the one that contains D, and the initial stack is empty. The location
1649         description result is pushed on the stack.
1654       *This allows a call operation to be used to compute the location
1655       description for any variable or formal parameter regardless of whether the
1656       producer has optimized it to a constant. This is consistent with the*
1667     * Otherwise, there is no effect and no changes are made to the stack.
1673         the right definition as a producer should be able to rely on using
1675         ``DW_TAG_dwarf_procedure`` debugging information entries. Also, the
1681     *The* ``DW_TAG_dwarf_procedure`` *debugging information entry can be used to
1689 This section describes the operations that push values on the stack.
1692 literal value of any supported base type of the target architecture. The base
1693 type specifies the size, encoding, and endianity of the literal value.
1695 The base type of value stack entries can be the distinguished generic type.
1706 The following operations all push a literal value onto the DWARF stack.
1708 Operations other than ``DW_OP_const_type`` push a value V with the generic type.
1709 If V is larger than the generic type, then V is truncated to the generic type
1710 size and the low-order bits used.
1715     through 31, inclusive. They push the value N with the generic type.
1720     8-byte unsigned integer constant U, respectively. They push the value U with
1721     the generic type.
1726     8-byte signed integer constant S, respectively. They push the value S with
1727     the generic type.
1732     the value N with the generic type.
1736     ``DW_OP_consts`` has a single signed LEB128 integer operand N. It pushes the
1737     value N with the generic type.
1742     represents a zero-based index into the ``.debug_addr`` section relative to
1743     the value of the ``DW_AT_addr_base`` attribute of the associated compilation
1744     unit. The value N in the ``.debug_addr`` section has the size of the generic
1745     type. It pushes the value N with the generic type.
1747     *The* ``DW_OP_constx`` *operation is provided for constants that require
1748     link-time relocation but should not be interpreted by the consumer as a
1753     ``DW_OP_const_type`` has three operands. The first is an unsigned LEB128
1754     integer DR that represents the byte offset of a debugging information entry
1755     D relative to the beginning of the current compilation unit, that provides
1756     the type T of the constant value. The second is a 1-byte unsigned integral
1757     constant S. The third is a block of bytes B, with a length equal to S.
1759     TS is the bit size of the type T. The least significant TS bits of B are
1760     interpreted as a value V of the type D. It pushes the value V with the type
1763     The DWARF is ill-formed if D is not a ``DW_TAG_base_type`` debugging
1764     information entry in the current compilation unit, or if TS divided by 8
1765     (the byte size) and rounded up to a whole number is not equal to S.
1767     *While the size of the byte block B can be inferred from the type D
1768     definition, it is encoded explicitly into the operation so that the
1769     operation can be parsed easily without reference to the* ``.debug_info``
1774     ``DW_OP_LLVM_push_lane`` pushes the current lane as a value with the generic
1778     this is the zero-based lane number that corresponds to the source language
1779     thread of execution upon which the user is focused.*
1781     The value must be greater than or equal to 0 and less than the value of the
1782     ``DW_AT_LLVM_lanes`` attribute, otherwise the DWARF expression is
1787     ``DW_OP_LLVM_push_iteration`` pushes the current iteration as a value with
1788     the generic type.
1791     loop iterations to execute concurrently, this is the zero-based iteration
1792     number that corresponds to the source language concurrent loop iteration
1793     upon which the user is focused.*
1795     The value must be greater than or equal to 0 and less than the value of the
1796     ``DW_AT_LLVM_iterations`` attribute, otherwise the DWARF expression is
1806   This section is the same as DWARF Version 5 section 2.5.1.4.
1815   This section is the same as DWARF Version 5 section 2.5.1.6.
1831     ``DW_OP_regval_type`` has two operands. The first is an unsigned LEB128
1832     integer that represents a register number R. The second is an unsigned
1833     LEB128 integer DR that represents the byte offset of a debugging information
1834     entry D relative to the beginning of the current compilation unit, that
1835     provides the type T of the register value.
1837     The operation is equivalent to performing ``DW_OP_regx R; DW_OP_deref_type
1842       Should DWARF allow the type T to be a larger size than the size of the
1844       as the, possibly truncated, bit contents of the register is simply
1850       Removing use of the target hook does not cause any test failures in common
1851       architectures. If the compiler for a target architecture did want some
1853       explicitly use the ``DW_OP_convert`` operation.
1855       If T is a larger type than the register size, then the default GDB
1856       register hook reads bytes from the next register (or reads out of bounds
1857       for the last register!). Removing use of the target hook does not cause
1865     S is the bit size of the generic type divided by 8 (the byte size) and
1866     rounded up to a whole number. DR is the offset of a hypothetical debug
1867     information entry D in the current compilation unit for a base type of the
1870     The operation is equivalent to performing ``DW_OP_deref_type S, DR``.
1877     TS is the smaller of the generic type bit size and S scaled by 8 (the byte
1878     size). If TS is smaller than the generic type bit size then T is an unsigned
1879     integral type of bit size TS, otherwise T is the generic type. DR is the
1880     offset of a hypothetical debug information entry D in the current
1885       Truncating the value when S is larger than the generic type matches what
1886       GDB does. This allows the generic type size to not be an integral byte
1888       the size of the generic type rounded up to a multiple of 8?
1890     The operation is equivalent to performing ``DW_OP_deref_type S, DR``, except
1891     if T is not the generic type, the value V pushed is zero-extended to the
1892     generic type bit size and its type changed to the generic type.
1896     ``DW_OP_deref_type`` has two operands. The first is a 1-byte unsigned
1897     integral constant S. The second is an unsigned LEB128 integer DR that
1898     represents the byte offset of a debugging information entry D relative to
1899     the beginning of the current compilation unit, that provides the type T of
1900     the result value.
1902     TS is the bit size of the type T.
1904     *While the size of the pushed value V can be inferred from the type T, it is
1905     encoded explicitly as the operand S so that the operation can be parsed
1906     easily without reference to the* ``.debug_info`` *section.*
1910       It is unclear why the operand S is needed. Unlike ``DW_OP_const_type``,
1911       the size is not needed for parsing. Any evaluation needs to get the base
1912       type T to push with the value to know its encoding and bit size.
1916     A value V of TS bits is retrieved from the location storage LS specified by
1917     one of the single location descriptions SL of L.
1919     *If L, or the location description of any composite location description
1922     all have the same value. For any single location description SL, bits are
1923     retrieved from the associated storage location starting at the bit offset
1924     specified by SL. For a composite location description, the retrieved bits
1925     are the concatenation of the N bits from each composite location part PL,
1926     where N is limited to the size of PL.*
1928     V is pushed on the stack with the type T.
1933       description that has less than TS bits remaining in the register storage.
1936       based on the type, or be target architecture dependent, as the number of
1937       remaining bits could be any number. This matches the GDB implementation
1943       Therefore, it requires the register size to be greater or equal to the
1944       address size of the address space. This matches the GDB implementation for
1947     The DWARF is ill-formed if D is not in the current compilation unit, D is
1949     8 (the byte size) and rounded up to a whole number is not equal to S.
1953       This definition allows the base type to be a bit size since there seems no
1956     It is an evaluation error if any bit of the value is retrieved from the
1957     undefined location storage or the offset of any bit exceeds the size of the
1961     rules concerning implicit location descriptions created by the
1967     ``DW_OP_xderef`` pops two stack entries. The first must be an integral type
1968     value that represents an address A. The second must be an integral type
1972     The operation is equivalent to performing ``DW_OP_swap;
1973     DW_OP_LLVM_form_aspace_address; DW_OP_deref``. The value V retrieved is left
1974     on the stack with the generic type.
1976     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
1984     It pops two stack entries. The first must be an integral type value that
1985     represents an address A. The second must be an integral type value that
1988     The operation is equivalent to performing ``DW_OP_swap;
1989     DW_OP_LLVM_form_aspace_address; DW_OP_deref_size S``. The zero-extended
1990     value V retrieved is left on the stack with the generic type.
1992     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
1997     ``DW_OP_xderef_type`` has two operands. The first is a 1-byte unsigned
1998     integral constant S. The second operand is an unsigned LEB128 integer DR
1999     that represents the byte offset of a debugging information entry D relative
2000     to the beginning of the current compilation unit, that provides the type T
2001     of the result value.
2003     It pops two stack entries. The first must be an integral type value that
2004     represents an address A. The second must be an integral type value that
2007     The operation is equivalent to performing ``DW_OP_swap;
2008     DW_OP_LLVM_form_aspace_address; DW_OP_deref_type S DR``. The value V
2009     retrieved is left on the stack with the type T.
2011     *This operation is deprecated as the* ``DW_OP_LLVM_form_aspace_address``
2016     ``DW_OP_entry_value`` pushes the value of an expression that is evaluated in
2017     the context of the calling frame.
2019     *It may be used to determine the value of arguments on entry to the current
2022     It has two operands. The first is an unsigned LEB128 integer S. The second
2026     E is evaluated with the current context, except the result kind is
2027     unspecified, the call frame is the one that called the current frame, the
2028     program location is the call site in the calling frame, the object is
2029     unspecified, and the initial stack is empty. The calling frame information
2030     is obtained by virtually unwinding the current call frame using the call
2033     If the result of E is a location description L (see
2034     :ref:`amdgpu-dwarf-register-location-description-operations`), and the last
2036     architecture specific base type of T, then the contents of the register are
2038     is the offset of a hypothetical debug information entry in the current
2039     compilation unit for T. The resulting value V s pushed on the stack.
2041     *Using* ``DW_OP_reg*`` *provides a more compact form for the case where the
2042     value was in a register on entry to the subprogram.*
2049     If the result of E is a value V, then V is pushed on the stack.
2051     Otherwise, the DWARF expression is ill-formed.
2053     *The* ``DW_OP_entry_value`` *operation is deprecated as its main usage is
2054     provided by other means. DWARF Version 5 added the*
2058     compute actual parameter values at the time of the call, and requires the
2059     producer to ensure the expressions are valid to evaluate even when virtually
2060     unwound. The* ``DW_OP_LLVM_call_frame_entry_reg`` *operation provides access
2061     to registers in the virtually unwound calling frame.*
2073 This section describes the operations that push location descriptions on the
2087     ``DW_OP_LLVM_offset`` pops two stack entries. The first must be an integral
2088     type value that represents a byte displacement B. The second must be a
2091     It adds the value of B scaled by 8 (the byte size) to the bit offset of each
2092     single location description SL of L, and pushes the updated L.
2094     It is an evaluation error if the updated bit offset of any SL is less than 0
2095     or greater than or equal to the size of the location storage specified by
2103     The operation is equivalent to performing ``DW_OP_constu B;
2118     ``DW_OP_LLVM_bit_offset`` pops two stack entries. The first must be an
2119     integral type value that represents a bit displacement B. The second must be
2122     It adds the value of B to the bit offset of each single location description
2123     SL of L, and pushes the updated L.
2125     It is an evaluation error if the updated bit offset of any SL is less than 0
2126     or greater than or equal to the size of the location storage specified by
2131     ``DW_OP_push_object_address`` pushes the location description L of the
2135     user presented expression that is being evaluated. The object location
2136     description may be determined from the variable's own debugging information
2142     involving descriptors) that is analogous to the implicit push of the base
2148       This operation could be removed and the object location description
2149       specified as the initial stack as for ``DW_AT_data_member_location``.
2152       stack. The latter approach is more composable as access to the object may
2153       be needed at any point of the expression, and passing it as the initial
2154       stack requires the entire expression to be aware where on the stack it is.
2156       ``DW_OP_push_object2_address`` operation for the second object.
2159       operation to get the Nth one such as ``DW_OP_arg N``. A vector of
2160       arguments would then be passed in the expression context rather than an
2161       initial stack. This could also resolve the issues with ``DW_OP_call*`` by
2163       specified. The ``DW_OP_call*`` operation could then always execute on a
2164       separate stack: the number of arguments would be specified in a new call
2165       operation and taken from the callers stack, and similarly the number of
2166       return results specified and copied from the called stack back to the
2167       callee stack when the called expression was complete.
2169       The only attribute that specifies a current object is
2170       ``DW_AT_data_location`` so the non-normative text seems to overstate how
2179     It pushes a location description L that holds the value of register R on
2180     entry to the current subprogram as defined by the call frame information
2183     *If there is no call frame information defined, then the default rules for
2184     the target architecture are used. If the register rule is* undefined\ *, then
2185     the undefined location description is pushed. If the register rule is* same
2197 *The undefined location storage represents a piece or all of an object that is
2198 present in the source but not in the object code (perhaps due to optimization).
2199 Neither reading nor writing to the undefined location storage is meaningful.*
2201 An undefined location description specifies the undefined location storage.
2202 There is no concept of the size of the undefined location storage, nor of a bit
2203 offset for an undefined location description. The ``DW_OP_LLVM_*offset``
2204 operations leave an undefined location description unchanged. The
2224 Each of the target architecture specific address spaces has a corresponding
2225 memory location storage that denotes the linear addressable memory of that
2226 address space. The size of each memory location storage corresponds to the range
2227 of the addresses in the corresponding address space.
2231 memory, or more than one location storage may alias the same physical memory
2232 possibly at different offsets and with different interleaving. The mapping may
2233 also be dictated by the source language address classes.*
2235 A memory location description specifies a memory location storage. The bit
2236 offset corresponds to a bit position within a byte of the memory. Bits accessed
2237 using a memory location description, access the corresponding target
2238 architecture memory starting at the bit position within the byte specified by
2239 the bit offset.
2241 A memory location description that has a bit offset that is a multiple of 8 (the
2243 memory byte address A that is equal to the bit offset divided by 8.
2246 of 8 (the byte size) is defined to be a bit field memory location description.
2247 It has a bit position B equal to the bit offset modulo 8, and a memory byte
2248 address A equal to the bit offset minus B that is then divided by 8.
2250 The address space AS of a memory location description is defined to be the
2251 address space that corresponds to the memory location storage associated with
2252 the memory location description.
2256 has a byte address equal to A and an address space equal to AS of the
2259 ``DW_ASPACE_LLVM_none`` is defined as the target architecture default address
2263 with the generic type, then it is implicitly converted to a location description
2264 L with one memory location description SL. SL specifies the memory location
2265 storage that corresponds to the target architecture default address space with a
2266 bit offset equal to V scaled by 8 (the byte size).
2271   a memory location description in the target architecture default address
2276     description L with a one memory location description SL. If the type size of
2277     V is less than the generic type size, then the value V is zero extended to
2278     the size of the generic type. The least significant generic type size bits
2280     memory location storage corresponding to the target architecture default
2281     address space with a bit offset equal to A scaled by 8 (the byte size).
2283   The implicit conversion could also be defined as target architecture specific.
2285   error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a
2286   hook function, then it is called. The target specific hook function can modify
2287   the 64-bit value, possibly sign extending based on the original value type.
2288   Finally, GDB treats the 64-bit value V as a memory location address.
2291 pointer value IPV with the target architecture default address space, then it is
2299   can be eliminated, and the producer can use
2303 with one memory location description SL in the target architecture default
2305 converted to a value equal to B divided by 8 (the byte size) with the generic
2310     ``DW_OP_addr`` has a single byte constant value operand, which has the size
2311     of the generic type, that represents an address A.
2314     on the stack. SL specifies the memory location storage corresponding to the
2316     scaled by 8 (the byte size).
2318     *If the DWARF is part of a code object, then A may need to be relocated. For
2319     example, in the ELF code object format, A must be adjusted by the difference
2320     between the ELF segment virtual address and the virtual address at which the
2326     a zero-based index into the ``.debug_addr`` section relative to the value of
2327     the ``DW_AT_addr_base`` attribute of the associated compilation unit. The
2328     address value A in the ``.debug_addr`` section has the size of the generic
2332     on the stack. SL specifies the memory location storage corresponding to the
2334     scaled by 8 (the byte size).
2336     *If the DWARF is part of a code object, then A may need to be relocated. For
2337     example, in the ELF code object format, A must be adjusted by the difference
2338     between the ELF segment virtual address and the virtual address at which the
2343     ``DW_OP_LLVM_form_aspace_address`` pops top two stack entries. The first
2345     specific address space identifier AS. The second must be an integral type
2348     The address size S is defined as the address bit size of the target
2352     the least significant S bits as an unsigned value A'.
2355     on the stack. SL specifies the memory location storage LS that corresponds
2356     to AS with a bit offset equal to A' scaled by 8 (the byte size).
2359     corresponds to the location storage associated with the current context.
2361     *For example, if AS is for per thread storage then LS is the location
2362     storage for the current thread. For languages that are implemented using a
2363     SIMT execution model, then if AS is for per lane storage then LS is the
2364     location storage for the current lane of the current thread. Therefore, if L
2365     is accessed by an operation, the location storage selected when the location
2366     description was created is accessed, and not the location storage associated
2367     with the current context of the access operation.*
2369     The DWARF expression is ill-formed if AS is not one of the values defined by
2370     the target architecture specific ``DW_ASPACE_LLVM_*`` values.
2374     location descriptions created by the ``DW_OP_implicit_pointer`` and
2383     on the stack. SL is the target architecture specific memory location
2384     description that corresponds to the thread-local storage address TA.
2386     The meaning of the thread-local storage address TA is defined by the
2387     run-time environment. If the run-time environment supports multiple
2388     thread-local storage blocks for a single thread, then the block
2389     corresponding to the executable or shared library containing this DWARF
2397     declared in the main executable, and a separate block for the variables
2400     byte offset into the block and pushed onto the DWARF stack by one of the*
2401     ``DW_OP_const*`` *operations prior to the* ``DW_OP_form_tls_address``
2402     *operation. Computing the address of the appropriate block can be complex
2403     (in some cases, the compiler emits a function call to do it), and difficult
2405     complex thread-local storage calculations into the DWARF expressions, the*
2406     ``DW_OP_form_tls_address`` *allows the consumer to perform the computation
2407     based on the target architecture specific run-time environment.*
2411     ``DW_OP_call_frame_cfa`` pushes the location description L of the Canonical
2412     Frame Address (CFA) of the current subprogram, obtained from the call frame
2413     information on the stack. See :ref:`amdgpu-dwarf-call-frame-information`.
2415     *Although the value of the* ``DW_AT_frame_base`` *attribute of the debugger
2416     information entry corresponding to the current subprogram can be computed
2418     extensive location list because the values of the registers used in
2419     computing the CFA change during a subprogram execution. If the call frame
2421     space efficient to reference that using the* ``DW_OP_call_frame_cfa``
2429     The location description L for the *frame base* of the current subprogram is
2430     obtained from the ``DW_AT_frame_base`` attribute of the debugger information
2431     entry corresponding to the current subprogram as described in
2434     The location description L is updated as if the ``DW_OP_LLVM_offset_uconst
2435     B`` operation was applied. The updated L is pushed on the stack.
2439     The ``DW_OP_breg<N>`` operations encode the numbers of up to 32 registers,
2440     numbered from 0 through 31, inclusive. The register number R corresponds to
2441     the N in the operation name.
2446     The address space identifier AS is defined as the one corresponding to the
2449     The address size S is defined as the address bit size of the target
2452     The contents of the register specified by R are retrieved as if a
2453     ``DW_OP_regval_type R, DR`` operation was performed where DR is the offset
2454     of a hypothetical debug information entry in the current compilation unit
2455     for an unsigned integral base type of size S bits. B is added and the least
2460     description LS on the stack. LS specifies the memory location storage that
2461     corresponds to AS with a bit offset equal to A scaled by 8 (the byte size).
2465     ``DW_OP_bregx`` has two operands. The first is an unsigned LEB128 integer
2466     that represents a register number R. The second is a signed LEB128
2469     The action is the same as for ``DW_OP_breg<N>``, except that R is used as
2470     the register number and B is used as the byte displacement.
2474     ``DW_OP_LLVM_aspace_bregx`` has two operands. The first is an unsigned
2475     LEB128 integer that represents a register number R. The second is a signed
2480     The action is the same as for ``DW_OP_breg<N>``, except that R is used as
2481     the register number, B is used as the byte displacement, and AS is used as
2482     the address space identifier.
2484     The DWARF expression is ill-formed if AS is not one of the values defined by
2485     the target architecture specific ``DW_ASPACE_LLVM_*`` values.
2502 There is a register location storage that corresponds to each of the target
2503 architecture registers. The size of each register location storage corresponds
2504 to the size of the corresponding target architecture register.
2506 A register location description specifies a register location storage. The bit
2507 offset corresponds to a bit position within the register. Bits accessed using a
2508 register location description access the corresponding target architecture
2509 register starting at the specified bit offset.
2513     ``DW_OP_reg<N>`` operations encode the numbers of up to 32 registers,
2514     numbered from 0 through 31, inclusive. The target architecture register
2515     number R corresponds to the N in the operation name.
2517     The operation is equivalent to performing ``DW_OP_regx R``.
2524     If the current call frame is the top call frame, it pushes a location
2525     description L that specifies one register location description SL on the
2526     stack. SL specifies the register location storage that corresponds to R with
2527     a bit offset of 0 for the current thread.
2529     If the current call frame is not the top call frame, call frame information
2530     (see :ref:`amdgpu-dwarf-call-frame-information`) is used to determine the
2531     location description that holds the register for the current call frame and
2532     current program location of the current thread. The resulting location
2535     *Note that if call frame information is used, the resulting location
2538     *An implementation may evaluate the call frame information immediately, or
2540     deferred, R and the current context can be recorded in L. When accessed, the
2541     recorded context is used to evaluate the call frame information, not the
2542     current context of the access operation.*
2544 *These operations obtain a register location. To fetch the contents of a
2545 register, it is necessary to use* ``DW_OP_regval_type``\ *, use one of the*
2559 actual location in the program but whose contents are nonetheless known, either
2560 as a constant or can be computed from other locations and values in the program.
2562 An implicit location description specifies an implicit location storage. The bit
2563 offset corresponds to a bit position within the implicit location storage. Bits
2564 accessed using an implicit location description, access the corresponding
2565 implicit storage value starting at the bit offset.
2569     ``DW_OP_implicit_value`` has two operands. The first is an unsigned LEB128
2570     integer that represents a byte size S. The second is a block of bytes with a
2573     An implicit location storage LS is created with the literal value V and a
2577     on the stack. SL specifies LS with a bit offset of 0.
2583     An implicit location storage LS is created with the literal value V using
2584     the size, encoding, and endianity specified by V's base type.
2587     on the stack. SL specifies LS with a bit offset of 0.
2589     *The* ``DW_OP_stack_value`` *operation specifies that the object does not
2590     exist in memory, but its value is nonetheless known. In this form, the
2591     location description specifies the actual value of the object, rather than
2592     specifying the memory or register storage that holds the value.*
2596     descriptions created by the ``DW_OP_implicit_pointer`` and
2599     Note: Since location descriptions are allowed on the stack, the
2600     ``DW_OP_stack_value`` operation no longer terminates the DWARF operation
2605     *An optimizing compiler may eliminate a pointer, while still retaining the
2606     value that the pointer addressed.* ``DW_OP_implicit_pointer`` *allows a
2609     ``DW_OP_implicit_pointer`` *specifies an object is a pointer to the target
2611     pointer, even though the value it would point to can be described. In this
2612     form, the location description specifies a debugging information entry that
2613     represents the actual location description of the object to which the
2614     pointer would point. Thus, a consumer of the debug information would be able
2615     to access the dereferenced pointer, even when it cannot access the pointer
2618     ``DW_OP_implicit_pointer`` has two operands. The first operand is a 4-byte
2619     unsigned value in the 32-bit DWARF format, or an 8-byte unsigned value in
2620     the 64-bit DWARF format, that represents the byte offset DR of a debugging
2621     information entry D relative to the beginning of the ``.debug_info`` section
2622     that contains the current compilation unit. The second operand is a signed
2625     *Note that D might not be in the current compilation unit.*
2627     *The first operand interpretation is exactly like that for*
2630     The address space identifier AS is defined as the one corresponding to the
2633     The address size S is defined as the address bit size of the target
2636     An implicit location storage LS is created with the debugging information
2640     description SL on the stack. SL specifies LS with a bit offset of 0.
2644     an implicit location storage that is the same as LS, unless both the
2648         refers to an implicit location storage that is the same as LS.
2650         *Note that all bits do not have to come from the same implicit location
2653     2.  The bits come from consecutive ascending offsets within their respective
2656     *These rules are equivalent to retrieving the complete contents of LS.*
2658     If both the above conditions are met, then the value V pushed by the
2661     D, and a base type of T. If AS is the target architecture default address
2662     space, then T is the generic type. Otherwise, T is a target architecture
2666     if AS is the target architecture default address space) or used by
2667     ``DW_OP_LLVM_form_aspace_address`` (only done if the address space popped by
2668     ``DW_OP_LLVM_form_aspace_address`` is AS), then the resulting location
2671     * If D has a ``DW_AT_location`` attribute, the DWARF expression E from the
2672       ``DW_AT_location`` attribute is evaluated with the current context, except
2673       that the result kind is a location description, the compilation unit is
2674       the one that contains D, the object is unspecified, and the initial stack
2675       is empty. RL is the expression result.
2677       *Note that E is evaluated with the context of the expression accessing
2678       IPV, and not the context of the expression that contained the*
2683       storage RLS is created from the ``DW_AT_const_value`` attribute's value
2684       with a size matching the size of the ``DW_AT_const_value`` attribute's
2696     The bit offset of RL is updated as if the ``DW_OP_LLVM_offset_uconst B``
2699     If a ``DW_OP_stack_value`` operation pops a value that is the same as IPV,
2700     then it pushes a location description that is the same as L.
2704     *The restrictions on how an implicit pointer location description created
2706     *can be used are to simplify the DWARF consumer. Similarly, for an implicit
2711     ``DW_OP_LLVM_aspace_implicit_pointer`` has two operands that are the same as
2717     The location description L that is pushed on the stack is the same as for
2718     ``DW_OP_implicit_pointer``, except that the address space identifier used is
2721     The DWARF expression is ill-formed if AS is not one of the values defined by
2722     the target architecture specific ``DW_ASPACE_LLVM_*`` values.
2734 The debugging information entry referenced by the* ``DW_OP_implicit_pointer``
2740 *D*\ :sub:`1` *and E*\ :sub:`1` *are describing the location of a pointer type
2741 object. D*\ :sub:`2` *and E*\ :sub:`2` *are describing the location of the
2747 reconstruct the value of the object when asked to dereference the pointer
2748 described by E*\ :sub:`1` *which contains the* ``DW_OP_implicit_pointer`` *or*
2766 that indicates that part is located in more than one place. The bits of each
2767 place of the part comprise S contiguous bits from the location storage LS
2768 specified by SL starting at the bit offset specified by SL. All the bits must
2769 be within the size of LS or the DWARF expression is ill-formed.
2771 A composite location storage can have zero or more parts. The parts are
2772 contiguous such that the zero-based location storage bit index will range over
2773 each part with no gaps between them. Therefore, the size of a composite location
2774 storage is the sum of the size of its parts. The DWARF expression is ill-formed
2775 if the size of the contiguous location storage is larger than the size of the
2776 memory location storage corresponding to the largest target architecture
2779 A composite location description specifies a composite location storage. The bit
2780 offset corresponds to a bit position within the composite location storage.
2786 be one or more operations to create the final composite location storage. A
2787 series of such operations describes the parts of the composite location storage
2788 that are in the order that the associated part operations are executed.
2793 composite location storage. The ``DW_OP_LLVM_piece_end`` operation explicitly
2801 If the top stack entry is a location description that has one incomplete
2802 composite location description SL after the execution of an operation expression
2805 *Note that this conversion does not happen after the completion of an operation
2806 expression that is evaluated on the same stack by the* ``DW_OP_call*``
2808 expression, but rather the continued evaluation of the same operation expression
2809 that contains the* ``DW_OP_call*`` *operation.*
2812 incomplete composite location description, then the DWARF expression is
2813 ill-formed. The exception is for the operations involved in incrementally
2821 *The incremental composite location description operations are defined to be
2822 compatible with the definitions in DWARF Version 5.*
2829     The action is based on the context:
2831     * If the stack is empty, then a location description L comprised of one
2832       incomplete composite location description SL is pushed on the stack.
2836       8 (the byte size). PL is comprised of one undefined location description
2841     * Otherwise, if the top stack entry is a location description L comprised of
2842       one incomplete composite location description SL, then the incomplete
2845       scaled by 8 (the byte size). PL is comprised of one undefined location
2846       description PSL. L is left on the stack.
2848     * Otherwise, if the top stack entry is a location description or can be
2852       * If the top stack entry (after popping PL) is a location description L
2853         comprised of one incomplete composite location description SL, then the
2855         append a new part P. P specifies the location description PL and has a
2856         bit size of S scaled by 8 (the byte size). L is left on the stack.
2859         composite location description SL is pushed on the stack.
2862         part P. P specifies the location description PL and has a bit size of S
2863         scaled by 8 (the byte size).
2867     * Otherwise, the DWARF expression is ill-formed
2873     *If a non-0 byte displacement is required, the* ``DW_OP_LLVM_offset``
2874     *operation can be used to update the location description before using it as
2875     the part location description of a* ``DW_OP_piece`` *operation.*
2877     *The evaluation rules for the* ``DW_OP_piece`` *operation allow it to be
2878     compatible with the DWARF Version 5 definition.*
2882       Since these extensions allow location descriptions to be entries on the
2885       and pops pairs of stack entries for the part size and location
2886       description. Not only would this be a simpler operation and avoid the
2888       also have a smaller encoding in practice. However, the desire for
2893     ``DW_OP_bit_piece`` has two operands. The first is an unsigned LEB128
2894     integer that represents the part bit size S. The second is an unsigned
2897     The action is the same as for ``DW_OP_piece``, except that any part created
2898     has the bit size S, and the location description PL of any created part is
2899     updated as if the ``DW_OP_constu B; DW_OP_LLVM_bit_offset`` operations were
2902     ``DW_OP_bit_piece`` *is used instead of* ``DW_OP_piece`` *when the piece to
2903     be assembled is not byte-sized or is not at the start of the part location
2906     *If a computed bit displacement is required, the* ``DW_OP_LLVM_bit_offset``
2907     *operation can be used to update the location description before using it as
2908     the part location description of a* ``DW_OP_bit_piece`` *operation.*
2912       The bit offset operand is not needed as ``DW_OP_LLVM_bit_offset`` can be
2913       used on the part's location description.
2917     If the top stack entry is not a location description L comprised of one
2918     incomplete composite location description SL, then the DWARF expression is
2921     Otherwise, the incomplete composite location storage LS specified by SL is
2922     updated to be a complete composite location description with the same parts.
2926     ``DW_OP_LLVM_extend`` has two operands. The first is an unsigned LEB128
2927     integer that represents the element bit size S. The second is an unsigned
2931     as the part location description PL.
2934     description SL is pushed on the stack.
2941     The DWARF expression is ill-formed if the element bit size or count are 0.
2945     ``DW_OP_LLVM_select_bit_piece`` has two operands. The first is an unsigned
2946     LEB128 integer that represents the element bit size S. The second is an
2949     It pops three stack entries. The first must be an integral type value that
2950     represents a bit mask value M. The second must be a location description
2951     that represents the one-location description L1. The third must be a
2952     location description that represents the zero-location description L0.
2958     PL\ :sub:`N` is as if the ``DW_OP_LLVM_bit_offset N*S`` operation was
2961     PLX\ :sub:`N` is the same as L0 if the N\ :sup:`th` least significant bit of
2962     M is a zero, otherwise it is the same as L1.
2965     description SL is pushed on the stack. SL specifies LS with a bit offset of
2968     The DWARF expression is ill-formed if S or C are 0, or if the bit size of M
2973       Should the count operand for DW_OP_extend and DW_OP_select_bit_piece be
2974       changed to get the count value off the stack? This would allow support for
2980     ``DW_OP_LLVM_overlay`` pops four stack entries. The first must be an
2981     integral type value that represents the overlay byte size value S. The
2982     second must be an integral type value that represents the overlay byte
2983     offset value O. The third must be a location description that represents the
2984     overlay location description OL. The fourth must be a location description
2985     that represents the base location description BL.
2987     The action is the same as for ``DW_OP_LLVM_bit_overlay``, except that the
2989     scaled by 8 (the byte size).
2993     ``DW_OP_LLVM_bit_overlay`` pops four stack entries. The first must be an
2994     integral type value that represents the overlay bit size value BS. The
2995     second must be an integral type value that represents the overlay bit offset
2996     value BO. The third must be a location description that represents the
2997     overlay location description OL. The fourth must be a location description
2998     that represents the base location description BL.
3000     The DWARF expression is ill-formed if BS or BO are negative values.
3002     *rbss(L)* is the minimum remaining bit storage size of L which is defined as
3003     follows. LS is the location storage and LO is the location bit offset
3004     specified by a single location description SL of L. The remaining bit
3005     storage size RBSS of SL is the bit size of LS minus LO. *rbss(L)* is the
3008     The DWARF expression is ill-formed if *rbss(BL)* is less than BO plus BS.
3010     If BS is 0, then the operation pushes BL.
3012     If BO is 0 and BS equals *rbss(BL)*, then the operation pushes OL.
3014     Otherwise, the operation is equivalent to performing the following steps to
3017     *The composite location description is conceptually the base location
3018     description BL with the overlay location description OL positioned as an
3019     overlay starting at the overlay offset BO and covering overlay bit size BS.*
3021     1.  If BO is not 0 then push BL followed by performing the ``DW_OP_bit_piece
3023     2.  Push OL followed by performing the ``DW_OP_bit_piece BS, 0`` operation.
3025         the ``DW_OP_bit_piece (rbss(BL) - BO - BS), (BO + BS)`` operation.
3026     4.  Perform the ``DW_OP_LLVM_piece_end`` operation.
3037 *To meet the needs of recent computer architectures and optimization techniques,
3038 debugging information must be able to describe the location of an object whose
3039 location changes over the object’s lifetime, and may reside at multiple
3041 used in place of operation expressions whenever the object whose location is
3045 location list entry is one of the following kinds:
3050   evaluates to the location description of an object that is valid over a
3051   lifetime bounded by a starting and ending address. The starting address is the
3052   lowest address of the address range over which the location is valid. The
3053   ending address is the address of the first location past the highest address
3054   of the address range.
3056   The location list entry matches when the current program location is within
3057   the given range.
3060   in the way that they specify the starting and ending addresses.
3065   evaluates to the location description of an object that is valid when no
3068   The location list entry matches when the current program location is not
3069   within the range of any bounded location description entry.
3073   This kind of location list entry provides an address to be used as the base
3075   bounded location description entries. The applicable base address of a bounded
3076   location description entry is the address specified by the closest preceding
3077   base address entry in the same location list. If there is no preceding base
3078   address entry, then the applicable base address defaults to the base address
3079   of the compilation unit (see DWARF Version 5 section 3.1.1).
3081   In the case of a compilation unit where all of the machine code is contained
3086   This kind of location list entry marks the end of the location list
3089 The address ranges defined by the bounded location description entries of a
3093 If all of the address ranges in a given location list expression do not
3094 collectively cover the entire range over which the object in question is
3096 assumed that the object is not available for the portion of the range that is
3099 The result of the evaluation of a DWARF location list expression is:
3101 * If the current program location is not specified, then it is an evaluation
3106     If the location list only has a single default entry, should that be
3109     program location as that indicates the location depends on the program
3112 * If there are no matching location list entries, then the result is a location
3115 * Otherwise, the operation expression E of each matching location list entry is
3116   evaluated with the current context, except that the result kind is a location
3117   description, the object is unspecified, and the initial stack is empty. The
3118   location list entry result is the location description returned by the
3121   The result is a location description that is comprised of the union of the
3122   single location descriptions of the location description result of each
3125 A location list expression can only be used as the value of a debugger
3127 ``loclistsptr`` (see :ref:`amdgpu-dwarf-classes-and-forms`). The value of the
3130 that contains the location list entries.
3136 description that may originate from the evaluation of a location list
3139 *This location list representation, the* ``loclist`` *and* ``loclistsptr``
3140 *class, and the related* ``DW_AT_loclists_base`` *attribute are new in DWARF
3141 Version 5. Together they eliminate most, or all of the code object relocations
3146   The rest of this section is the same as DWARF Version 5 section 2.6.2.
3164 memory, and memory with special interleaving. The size of addresses in these
3168 part of the unified global virtual address space accessible by all threads.*
3173 language memory spaces to the same target architecture specific DWARF address
3176 different DWARF address space than the default for the source language memory
3181 architectures, and defined as the target architecture default address space.
3185 * The ``DW_AT_LLVM_address_space`` attribute.
3187 * The DWARF expression operations: ``DW_OP_aspace_bregx``,
3191 * The CFI instructions: ``DW_CFA_def_aspace_cfa`` and
3197   specific, and defines a DW_AT_address_class attribute. With the removal of
3198   DW_AT_segment in DWARF 6, it is unclear how the address class is intended to
3199   be used as the term is not used elsewhere. Should these be replaced by this
3212 DWARF memory spaces are used for source languages that have the concept of
3213 memory spaces. They are used in the ``DW_AT_LLVM_memory_space`` attribute for
3219 specify the source language memory spaces that pointer type and reference type
3220 values refer, and to specify the source language memory space in which variables
3225 languages, and defined as the source language default memory space.
3227 The set of currently defined DWARF memory spaces, together with source language
3230 Vendor defined source language memory spaces may be defined using codes in the
3250   The approach presented in
3251   :ref:`amdgpu-dwarf-source-language-memory-spaces-table` is to define the
3252   default ``DW_MSPACE_LLVM_none`` to be the generic address class and not the
3257   An alternative approach is to define ``DW_MSPACE_LLVM_none`` as being the
3259   ``DW_MSPACE_LLVM_generic``. This would match the reality that languages that
3261   space. Generally, in these languages if they expose that the target
3262   architecture supports multiple memory spaces, the default one is still the
3264   has to explicitly indicate which pointers have the added ability to reference
3265   more than the global memory space. However, compilers generating DWARF for
3268   ``DW_MSPACE_LLVM_generic`` to match the language semantics.
3276   attributes. These would be incorporated into the corresponding DWARF Version 5
3291 Additional language codes defined for use with the ``DW_AT_language`` attribute
3303 The HIP language [:ref:`HIP <amdgpu-dwarf-HIP>`] can be supported by extending
3304 the C++ language.
3308   The following new attribute is added.
3314     *The augmentation string allows producers to indicate that there is
3315     additional vendor or target specific information in the debugging
3316     information entries. For example, this might be information about the
3319     If not present, or if the string is empty, then the compilation unit has no
3322     The format for the augmentation string is:
3326     Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
3327     version number of the extensions used, and *options* is an optional string
3328     providing additional information about the extensions. The version number
3330     The *options* string must not contain the "\ ``]``\ " character.
3350     The result of the attribute is obtained by evaluating E with a context that
3351     has a result kind of a location description, an unspecified object, the
3353     elements corresponding to the source language thread of execution upon which
3354     the user is focused, if any. The result of the evaluation is the location
3355     description L of the place where the return address for the current call
3358     The DWARF is ill-formed if L is not comprised of one memory location
3359     description for one of the target architecture specific address spaces.
3373     The result of the attribute is obtained by evaluating E with a context that
3374     has a result kind of a location description, an unspecified object, the
3376     elements corresponding to the source language thread of execution upon which
3377     the user is focused, if any.
3379     The DWARF is ill-formed if E contains a ``DW_OP_fbreg`` operation, or the
3384     with the result of evaluating a ``DW_OP_bregx R, 0`` operation. This
3385     computes the frame base memory location description in the target
3388     *This allows the more compact* ``DW_OP_reg*`` *to be used instead of*
3393       This rule could be removed and require the producer to create the required
3396       allow a target to implement the call frames within a large register.
3398     Otherwise, the DWARF is ill-formed if SL is not a memory location
3399     description in any of the target architecture specific address spaces.
3401     The resulting L is the *frame base* for the subprogram or entry point.
3403     *Typically, E will use the* ``DW_OP_call_frame_cfa`` *operation or be a
3406     *The frame base for a subprogram is typically an address relative to the
3407     first unit of storage allocated for the subprogram's stack frame. The*
3410     1.  *In subprograms that need location lists to locate local variables, the*
3411         ``DW_AT_frame_base`` *can hold the needed location list, while all
3412         variables' location descriptions can be simpler ones involving the frame
3419     possible to reference the local variables of an outer subroutine from within
3420     an inner subroutine. The* ``DW_AT_static_link`` *and* ``DW_AT_frame_base``
3427     The result of the attribute is obtained by evaluating E with a context that
3428     has a result kind of a location description, an unspecified object, the
3430     elements corresponding to the source language thread of execution upon which
3431     the user is focused, if any. The result of the evaluation is the location
3432     description L of the *canonical frame address* (see
3433     :ref:`amdgpu-dwarf-call-frame-information`) of the relevant call frame of
3434     the subprogram instance that immediately lexically encloses the current call
3437     The DWARF is ill-formed if L is not comprised of one memory location
3438     description for one of the target architecture specific address spaces.
3440     In the context of supporting nested subroutines, the DW_AT_frame_base
3441     attribute value obeys the following constraints:
3443     1.  It computes a value that does not change during the life of the
3446     2.  The computed value is unique among instances of the same subroutine.
3452     it uses the nesting structure of DWARF to determine which subroutine is the
3453     lexical parent and the* ``DW_AT_static_link`` *value to identify the
3454     appropriate active frame of the parent. It can then attempt to find the
3455     reference within the context of the parent.*
3459       The following new attributes are added.
3465     the number of source language threads of execution per target architecture
3471     It is the static number of source language threads of execution per target
3472     architecture thread. It is not the dynamic number of source language threads
3473     of execution with which the target architecture thread was initiated, for
3476     If not present, the default value of 1 is used.
3478     The DWARF is ill-formed if the value is less than or equal to 0.
3485     The result of the attribute is obtained by evaluating E with a context that
3486     has a result kind of a location description, an unspecified object, the
3488     elements corresponding to the source language thread of execution upon which
3489     the user is focused, if any.
3491     The resulting location description L is for a lane count sized vector of
3492     generic type elements. The lane count is the value of the
3493     ``DW_AT_LLVM_lanes`` attribute. Each element holds the conceptual program
3494     location of the corresponding lane. If the lane was not active when the
3498     The DWARF is ill-formed if L does not have exactly one single location
3501     ``DW_AT_LLVM_lane_pc`` *allows the compiler to indicate conceptually where
3505     *Typically, the result is a location description with one composite location
3509     If not present, the target architecture thread is not being used in a SIMT
3510     manner, and the thread's current program location is used.
3518     description, an unspecified object, the compilation unit that contains E, an
3519     empty initial stack, and other context elements corresponding to the source
3520     language thread of execution upon which the user is focused, if any.
3522     The DWARF is ill-formed if L does not have exactly one single location
3525     The active lane bit mask V for the current program location is obtained by
3527     that has a bit size equal to the value of the ``DW_AT_LLVM_lanes`` attribute
3528     of the subprogram corresponding to context's frame and program location. The
3529     N\ :sup:`th` least significant bit of the mask corresponds to the N\
3530     :sup:`th` lane. If the bit is 1 the lane is active, otherwise it is
3531     inactive. The result of the attribute is the value V.
3533     *Some targets may update the target architecture execution mask for regions
3534     of code that must execute with different sets of lanes than the current
3536     temporarily active.* ``DW_AT_LLVM_active_lane`` *allows the compiler to
3537     provide the means to determine the source language active lanes at any
3539     different locations of the active lane mask at different program locations.*
3541     If not present and ``DW_AT_LLVM_lanes`` is greater than 1, then the target
3547     DWARF expression E. Its value is the number of source language loop
3548     iterations executing concurrently by the target architecture for a single
3553     software pipelining or SIMD vectorization. The number of concurrent
3554     iterations may vary for different loop nests in the same subprogram.
3558     If the attribute is an integer constant, then the value is the constant. The
3559     DWARF is ill-formed if the constant is less than or equal to 0.
3562     location description, an unspecified object, the compilation unit that
3564     to the source language thread of execution upon which the user is focused,
3565     if any. The DWARF is ill-formed if the result is not a location description
3566     comprised of one implicit location description, that when read as the
3567     generic type, results in a value V that is less than or equal to 0. The
3568     result of the attribute is the value V.
3570     If not present, the default value of 1 is used.
3578 1.  The call site entry may own ``DW_TAG_call_site_parameter`` debugging
3579     information entries representing the parameters passed to the call. Call
3580     site parameter entries occur in the same order as the corresponding
3581     parameters in the source. Each such entry has a ``DW_AT_location`` attribute
3583     the parameter is passed (usually either some register, or a memory location
3584     expressible as the contents of the stack register plus some offset).
3590     The result of the ``DW_AT_call_value`` attribute is obtained by evaluating
3592     object, the compilation unit that contains E, an empty initial stack, and
3593     other context elements corresponding to the source language thread of
3594     execution upon which the user is focused, if any. The resulting value V\
3595     :sub:`1` is the value of the parameter at the time of the call made by the
3598     For parameters passed by reference, where the code passes a pointer to a
3599     location which contains the parameter, or for reference type parameters, the
3605     The value of the ``DW_AT_call_data_location`` attribute is obtained by
3607     description, an unspecified object, the compilation unit that contains E, an
3608     empty initial stack, and other context elements corresponding to the source
3609     language thread of execution upon which the user is focused, if any. The
3610     resulting location description L\ :sub:`2` is the location where the
3611     referenced parameter lives during the call made by the call site. If E\
3612     :sub:`2` would just be a ``DW_OP_push_object_address``, then the
3617       The DWARF Version 5 implies that ``DW_OP_push_object_address`` may be used
3618       but does not state what object must be specified in the context. Either
3619       ``DW_OP_push_object_address`` cannot be used, or the object to be passed
3620       in the context must be defined.
3622     The value of the ``DW_AT_call_data_value`` attribute is obtained by
3624     unspecified object, the compilation unit that contains E, an empty initial
3625     stack, and other context elements corresponding to the source language
3626     thread of execution upon which the user is focused, if any. The resulting
3627     value V\ :sub:`3` is the value in L\ :sub:`2` at the time of the call made
3628     by the call site.
3630     The result of these attributes is undefined if the current call frame is not
3631     for the subprogram containing the ``DW_TAG_call_site_parameter`` debugger
3632     information entry or the current program location is not for the call site
3633     containing the ``DW_TAG_call_site_parameter`` debugger information entry in
3634     the current call frame.
3636     *The consumer may have to virtually unwind to the call site (see*
3638     attributes. This will ensure the source language thread of execution upon
3639     which the user is focused corresponds to the call site needed to evaluate
3640     the expression.*
3642     If it is not possible to avoid the expressions of these attributes from
3643     accessing registers or memory locations that might be clobbered by the
3644     subprogram being called by the call site, then the associated attribute
3647     *The reason for the restriction is that the parameter may need to be
3648     accessed during the execution of the callee. The consumer may virtually
3649     unwind from the called subprogram back to the caller and then evaluate the
3650     attribute expressions. The call frame information (see*
3653     the value at the time of the call.*
3657     ``DW_AT_type attribute`` referencing the type of the parameter or
3658     ``DW_AT_name`` attribute describing the parameter's name.
3670   This section is the same as DWARF Version 5 section 3.5.
3678   attributes. These would be incorporated into the corresponding DWARF Version 5
3687 information entries with the tags ``DW_TAG_variable``,
3690 *The tag DW_TAG_constant is used for languages that have true named constants.*
3692 The debugging information entry for a program variable, formal parameter or
3693 constant may have the following attributes:
3696     describes the location of a variable or parameter at run-time.
3698     The result of the attribute is obtained by evaluating E with a context that
3699     has a result kind of a location description, an unspecified object, the
3701     elements corresponding to the source language thread of execution upon which
3702     the user is focused, if any. The result of the evaluation is the location
3703     description of the base of the data object.
3706     used by the ``DW_OP_call*`` operations.
3710       Delete the description of how the ``DW_OP_call*`` operations evaluate a
3711       ``DW_AT_location`` attribute as that is now described in the operations.
3715       See the discussion about the ``DW_AT_location`` attribute in the
3718       for the consumer that no longer have to track the context. It makes it
3719       easier for the producer as it can rely on a single semantics for each
3722       For that reason, limiting the ``DW_AT_location`` attribute to only
3723       supporting evaluating the location description of an object, and using a
3724       different attribute and encoding class for the evaluation of DWARF
3725       expression *procedures* on the same operation expression stack seems
3732       Could deprecate using the ``DW_AT_const_value`` attribute for
3737       used within a DWARF expression. This allows the ``DW_OP_call*`` operations
3738       to be used to push the location description of any variable regardless of
3752 DWARF expression E that describes the location of the common block at run-time.
3753 The result of the attribute is obtained by evaluating E with a context that has
3754 a result kind of a location description, an unspecified object, the compilation
3756 corresponding to the source language thread of execution upon which the user is
3757 focused, if any. The result of the evaluation is the location description of the
3758 base of the common block. See :ref:`amdgpu-dwarf-control-flow-operations` for
3759 special evaluation rules used by the ``DW_OP_call*`` operations.
3767   attributes. These would be incorporated into the corresponding DWARF Version 5
3777   The following new attribute is added.
3781     that is the vector type size N.
3783     The representation of a vector base type is as N contiguous elements, each
3784     one having the representation of a base type T' that is the same as T
3785     without the ``DW_AT_LLVM_vector_size`` attribute.
3788     ``DW_AT_LLVM_vector_size`` attribute, then the base type is not a vector
3791     The DWARF is ill-formed if N is not greater than 0.
3797       would not be suitable as the type of a stack value entry. But perhaps that
3802       Compare this with the ``DW_AT_GNU_vector`` extension supported by GNU. Is
3803       it better to add an attribute to the existing ``DW_TAG_base_type`` debug
3804       entry, or allow some forms of ``DW_TAG_array_type`` (those that have the
3807 2. A ``DW_TAG_base_type`` debugger information entry with the encoding
3834 ``DW_ASPACE_LLVM_none``. DR is the offset of a hypothetical debug information
3835 entry D in the current compilation unit for an integral base type matching the
3836 address size of AS. An object P having the given pointer or reference type are
3837 dereferenced as if the ``DW_OP_push_object_address; DW_OP_deref_type DR;
3839 with the current context except: the result kind is location description; the
3840 initial stack is empty; and the object is the location description of P.
3844   What if the current context does not have a current target architecture
3849   With the expanded support for DWARF address spaces, it may be worth examining
3851   would include specifying the address space of all code addresses (compilation
3853   Either the code address attributes could be extended to allow a exprloc form
3854   (so that ``DW_OP_form_aspace_address`` can be used) or the
3866     1.  If the attribute is an integer constant B, it provides the offset in
3867         bytes from the beginning of the containing entity.
3869         The result of the attribute is obtained by evaluating a
3870         ``DW_OP_LLVM_offset B`` operation with an initial stack comprising the
3871         location description of the beginning of the containing entity. The
3872         result of the evaluation is the location description of the base of the
3875         *If the beginning of the containing entity is not byte aligned, then the
3876         beginning of the member entry has the same bit displacement within a
3879     2.  Otherwise, the attribute must be a DWARF expression E which is evaluated
3881         unspecified object, the compilation unit that contains E, an initial
3882         stack comprising the location description of the beginning of the
3883         containing entity, and other context elements corresponding to the
3884         source language thread of execution upon which the user is focused, if
3885         any. The result of the evaluation is the location description of the
3886         base of the member entry.
3890       The beginning of the containing entity can now be any location
3901     The result of the attribute is obtained by evaluating E with a context that
3902     has a result kind of a location description, an unspecified object, the
3903     compilation unit that contains E, an initial stack comprising the location
3904     description of the object of the enclosing type, and other context elements
3905     corresponding to the source language thread of execution upon which the user
3906     is focused, if any. The result of the evaluation is the location description
3907     of the slot for the function within the virtual function table for the
3913 1.  The ``DW_TAG_ptr_to_member_type`` debugging information entry has a
3915     used to compute the location description of the member of the class to which
3916     the pointer to member entry points.
3918     *The method used to find the location description of a given member of a
3920     structure, or union and to any instance of the pointer to member type. The
3921     method is thus associated with the pointer to member type, rather than with
3924     The ``DW_AT_use_location`` DWARF expression is used in conjunction with the
3925     location description for a particular object of the given pointer to member
3928     The result of the attribute is obtained by evaluating E with a context that
3929     has a result kind of a location description, an unspecified object, the
3931     and other context elements corresponding to the source language thread of
3932     execution upon which the user is focused, if any. The first stack entry is
3933     the value of the pointer to member object itself. The second stack entry is
3934     the location description of the base of the entire class, structure, or
3935     union instance containing the member whose location is being calculated. The
3936     result of the evaluation is the location description of the member of the
3937     class to which the pointer to member entry points.
3946 including a location and/or run-time parameters, about the data that represents
3947 the value for that object.*
3949 1.  The ``DW_AT_data_location`` attribute may be used with any type that
3952     computes the location description of the data for an object. When this
3953     attribute is omitted, the location description of the data is the same as
3954     the location description of the object.
3956     The result of the attribute is obtained by evaluating E with a context that
3957     has a result kind of a location description, an object that is the location
3958     description of the data descriptor, the compilation unit that contains E, an
3959     empty initial stack, and other context elements corresponding to the source
3960     language thread of execution upon which the user is focused, if any. The
3961     result of the evaluation is the location description of the base of the
3965     ``DW_OP_push_object_address`` *operation which loads the location
3966     description of the object which can then serve as a descriptor in subsequent
3979       It seems odd this attribute is not the same as
3980       ``DW_AT_data_member_location`` in having an initial stack with the
3981       location description of the object since the expression has to need it.
3989   attributes. These would be incorporated into the corresponding DWARF Version 5
4000 A.6.1.1.1 Contents of the Name Index
4005   The following provides changes to DWARF Version 5 section 6.1.1.1.
4007   The rule for debugger information entries included in the name index in the
4012 The name index must contain an entry for each debugging information entry that
4013 defines a named subprogram, label, variable, type, or namespace, subject to the
4021 A.6.1.1.4 Data Representation of the Name Index
4032   The following provides an addition to DWARF Version 5 section 6.1.1.4.1 item
4036 additional information about the contents of this index. If provided, the
4041 Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
4042 version number of the extensions used in the DWARF of the compilation unit, and
4043 *options* is an optional string providing additional information about the
4044 extensions. The version number must conform to semantic versioning [:ref:`SEMVER
4045 <amdgpu-dwarf-SEMVER>`]. The *options* string must not contain the "\ ``]``\ "
4056   This is different to the definition in DWARF Version 5 but is consistent with
4057   the other augmentation strings and allows multiple vendor extensions to be
4065 A.6.2.4 The Line Number Program Header
4079     The component is a null-terminated UTF-8 source text string with "\ ``\n``\
4080     " line endings. This content code is paired with the same forms as
4083     The value is an empty null-terminated string if no source is available. If
4084     the source is available but is an empty file then the value is a
4087     *When the source field is present, consumers can use the embedded source
4088     instead of attempting to discover the source on disk using the file path
4089     provided by the* ``DW_LNCT_path`` *field. When the source field is absent,
4090     consumers can access the file to get the source text.*
4093     compilation and runtime generation of source text. In these cases, the
4094     source text does not reside in any permanent file. For example, the OpenCL
4099     ``DW_LNCT_LLVM_is_MD5`` indicates if the ``DW_LNCT_MD5`` content kind, if
4102     content kind is present, then the MD5 checksum is valid.
4104     ``DW_LNCT_LLVM_is_MD5`` is always paired with the ``DW_FORM_udata`` form.
4123   These changes would be incorporated into the DWARF Version 5 section 6.4.
4130 The register rules are:
4133   A register that has this rule has no recoverable value in the previous frame.
4134   The previous value of this register is the undefined location description (see
4137   *By convention, the register is not preserved by a callee.*
4140   This register has not been modified from the previous caller frame.
4142   If the current frame is the top frame, then the previous value of this
4143   register is the location description L that specifies one register location
4144   description SL. SL specifies the register location storage that corresponds to
4145   the register with a bit offset of 0 for the current thread.
4147   If the current frame is not the top frame, then the previous value of this
4148   register is the location description obtained using the call frame information
4149   for the callee frame and callee program location invoked by the current caller
4150   frame for the same register.
4152   *By convention, the register is preserved by the callee, but the callee has
4156   N is a signed byte offset. The previous value of this register is saved at the
4157   location description computed as if the DWARF operation expression
4158   ``DW_OP_LLVM_offset N`` is evaluated with the current context, except the
4159   result kind is a location description, the compilation unit is unspecified,
4160   the object is unspecified, and an initial stack comprising the location
4161   description of the current CFA (see
4165   N is a signed byte offset. The previous value of this register is the memory
4166   byte address of the location description computed as if the DWARF operation
4167   expression ``DW_OP_LLVM_offset N`` is evaluated with the current context,
4168   except the result kind is a location description, the compilation unit is
4169   unspecified, the object is unspecified, and an initial stack comprising the
4170   location description of the current CFA (see
4173   The DWARF is ill-formed if the CFA location description is not a memory byte
4174   address location description, or if the register size does not match the size
4175   of an address in the address space of the current CFA location description.
4177   *Since the CFA location description is required to be a memory byte address
4178   location description, the value of val_offset(N) will also be a memory byte
4179   address location description since it is offsetting the CFA location
4180   description by N bytes. Furthermore, the value of val_offset(N) will be a
4181   memory byte address in the same address space as the CFA location
4186     Should DWARF allow the address size to be a different size to the size of
4187     the register? Requiring them to be the same bit size avoids any issue of
4188     conversion as the bit contents of the register is simply interpreted as a
4189     value of the address.
4193     and to actually reading bytes from the next register (or reads out of bounds
4194     for the last register) for smaller registers. There are no GDB tests that
4201   The previous value of this register is the location description obtained using
4202   the call frame information for the current frame and current program location
4205   The DWARF is ill-formed if the size of this register does not match the size
4206   of register R or if there is a cyclic dependency in the call frame
4211     Should this also allow R to be larger than this register? If so is the value
4212     stored in the low order bits and it is undefined what is stored in the
4216   The previous value of this register is located at the location description
4217   produced by evaluating the DWARF operation expression E (see
4220   E is evaluated with the current context, except the result kind is a location
4221   description, the compilation unit is unspecified, the object is unspecified,
4222   and an initial stack comprising the location description of the current CFA
4226   The previous value of this register is located at the implicit location
4227   description created from the value produced by evaluating the DWARF operation
4230   E is evaluated with the current context, except the result kind is a value,
4231   the compilation unit is unspecified, the object is unspecified, and an initial
4232   stack comprising the location description of the current CFA (see
4235   The DWARF is ill-formed if the resulting value type size does not match the
4240     This has limited usefulness as the DWARF expression E can only produce
4241     values up to the size of the generic type. This is due to not allowing any
4243     unusable for registers that are larger than the generic type. However,
4248   The rule is defined externally to this specification by the augmenter.
4251 of the entries at any point in the table are identical to the ones above them.
4252 The whole table can be represented quite compactly by recording just the
4253 differences starting at the beginning address of each subroutine in the
4256 The virtual unwind information is encoded in a self-contained section called
4258 multiple of the address size relative to the start of the section and come in
4261 *If the range of code addresses for a function is not contiguous, there may be
4262 multiple CIEs and FDEs corresponding to the parts of that function.*
4266 ``.debug_frame`` section. A CIE contains the following fields, in order:
4270     A constant that gives the number of bytes of the CIE structure, not
4271     including the length field itself (see Section 7.2.2 Initial Length Values).
4272     The size of the length field plus the value of length must be an integral
4273     multiple of the address size specified in the ``address_size`` field.
4280     In the 32-bit DWARF format, the value of the CIE id in the CIE header is
4281     0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.
4286     specific to the call frame information and is independent of the DWARF
4289     The value of the CIE version number is 4.
4293       Would this be increased to 5 to reflect the changes in these extensions?
4297     A null-terminated UTF-8 string that identifies the augmentation to this CIE
4298     or to the FDEs that use it. If a reader encounters an augmentation string
4299     that is unexpected, then only the following fields can be read:
4306     *The augmentation string allows users to indicate that there is additional
4307     vendor and target architecture specific information in the CIE or FDE which
4310     from the routine.*
4312     *Because the* ``.debug_frame`` *section is useful independently of any*
4313     ``.debug_info`` *section, the augmentation string always uses UTF-8
4316     The recommended format for the augmentation string is:
4320     Where *vendor* is the producer, ``vX.Y`` specifies the major X and minor Y
4321     version number of the extensions used, and *options* is an optional string
4322     providing additional information about the extensions. The version number
4324     The *options* string must not contain the "\ ``]``\ " character.
4334     The size of a target address in this CIE and any FDEs that use it, in bytes.
4335     If a compilation unit exists for this frame, its address size must match the
4340     The size of a segment selector in this CIE and any FDEs that use it, in
4346     :ref:`amdgpu-dwarf-row-creation-instructions`). The resulting value is
4353     :ref:`amdgpu-dwarf-register-rule-instructions`). The resulting value is
4358     An unsigned LEB128 constant that indicates which column in the rule table
4359     represents the return address of the subprogram. Note that this column might
4362     The value of the return address register is used to determine the program
4363     location of the caller frame. The program location of the top frame is the
4364     target architecture program counter value of the current thread.
4368     A sequence of rules that are interpreted to create the initial setting of
4369     each column in the table.
4371     The default rule for all columns before interpretation of the initial
4372     instructions is the undefined rule. However, an ABI authoring body or a
4378     Enough ``DW_CFA_nop`` instructions to make the size of this entry match the
4381 An FDE contains the following fields, in order:
4385     A constant that gives the number of bytes of the header and instruction
4386     stream for this subprogram, not including the length field itself (see
4387     Section 7.2.2 Initial Length Values). The size of the length field plus the
4388     value of length must be an integral multiple of the address size.
4393     A constant offset into the ``.debug_frame`` section that denotes the CIE
4398     The address of the first location associated with this table entry. If the
4399     segment_selector_size field of this FDE’s CIE is non-zero, the initial
4400     location is preceded by a segment selector of the given length.
4404     The number of bytes of program instructions described by this entry.
4413     Enough ``DW_CFA_nop`` instructions to make the size of this entry match the
4421 Each call frame instruction is defined to take 0 or more operands. Some of the
4422 operands may be encoded as part of the opcode (see
4423 :ref:`amdgpu-dwarf-call-frame-information-encoding`). The instructions are
4424 defined in the following sections.
4427 expressions E (see :ref:`amdgpu-dwarf-operation-expressions`). The DWARF
4428 operations that can be used in E have the following restrictions:
4434   operations are not allowed because the call frame information must not depend
4441   because the call frame instructions describe the actions for the whole target
4442   architecture thread, not the lanes or iterations independently.
4467   These instructions are the same as in DWARF Version 5 section 6.4.2.1.
4476     The ``DW_CFA_def_cfa`` instruction takes two unsigned LEB128 operands
4478     AS is set to the target architecture default address space identifier. The
4479     required action is to define the current CFA rule to be equivalent to the
4480     result of evaluating the DWARF operation expression ``DW_OP_constu AS;
4485     The ``DW_CFA_def_cfa_sf`` instruction takes two operands: an unsigned LEB128
4487     displacement B. AS is set to the target architecture default address space
4488     identifier. The required action is to define the current CFA rule to be
4489     equivalent to the result of evaluating the DWARF operation expression
4493     *The action is the same as* ``DW_CFA_def_cfa``\ *, except that the second
4498     The ``DW_CFA_LLVM_def_aspace_cfa`` instruction takes three unsigned LEB128
4501     AS. The required action is to define the current CFA rule to be equivalent
4502     to the result of evaluating the DWARF operation expression ``DW_OP_constu
4505     If AS is not one of the values defined by the target architecture specific
4506     ``DW_ASPACE_LLVM_*`` values then the DWARF expression is ill-formed.
4510     The ``DW_CFA_LLVM_def_aspace_cfa_sf`` instruction takes three operands: an
4513     target architecture specific address space identifier AS. The required
4514     action is to define the current CFA rule to be equivalent to the result of
4515     evaluating the DWARF operation expression ``DW_OP_constu AS;
4519     If AS is not one of the values defined by the target architecture specific
4520     ``DW_ASPACE_LLVM_*`` values, then the DWARF expression is ill-formed.
4522     *The action is the same as* ``DW_CFA_aspace_def_cfa``\ *, except that the
4527     The ``DW_CFA_def_cfa_register`` instruction takes a single unsigned LEB128
4528     operand representing a register number R. The required action is to define
4529     the current CFA rule to be equivalent to the result of evaluating the DWARF
4531     location description. B and AS are the old CFA byte displacement and address
4534     If the subprogram has no current CFA rule, or the rule was defined by a
4535     ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.
4539     The ``DW_CFA_def_cfa_offset`` instruction takes a single unsigned LEB128
4540     operand representing a (non-factored) byte displacement B. The required
4541     action is to define the current CFA rule to be equivalent to the result of
4542     evaluating the DWARF operation expression ``DW_OP_constu AS;
4543     DW_OP_LLVM_aspace_bregx R, B`` as a location description. R and AS are the
4546     If the subprogram has no current CFA rule, or the rule was defined by a
4547     ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.
4551     The ``DW_CFA_def_cfa_offset_sf`` instruction takes a signed LEB128 operand
4552     representing a factored byte displacement B. The required action is to
4553     define the current CFA rule to be equivalent to the result of evaluating the
4555     data_alignment_factor`` as a location description. R and AS are the old CFA
4558     If the subprogram has no current CFA rule, or the rule was defined by a
4559     ``DW_CFA_def_cfa_expression`` instruction, then the DWARF is ill-formed.
4561     *The action is the same as* ``DW_CFA_def_cfa_offset``\ *, except that the
4566     The ``DW_CFA_def_cfa_expression`` instruction takes a single operand encoded
4568     The required action is to define the current CFA rule to be equivalent to
4569     the result of evaluating E with the current context, except the result kind
4570     is a location description, the compilation unit is unspecified, the object
4574     the DWARF expression operations that can be used in E.*
4576     The DWARF is ill-formed if the result of evaluating E is not a memory byte
4586     The ``DW_CFA_undefined`` instruction takes a single unsigned LEB128 operand
4587     that represents a register number R. The required action is to set the rule
4588     for the register specified by R to ``undefined``.
4592     The ``DW_CFA_same_value`` instruction takes a single unsigned LEB128 operand
4593     that represents a register number R. The required action is to set the rule
4594     for the register specified by R to ``same value``.
4598     The ``DW_CFA_offset`` instruction takes two operands: a register number R
4599     (encoded with the opcode) and an unsigned LEB128 constant representing a
4600     factored displacement B. The required action is to change the rule for the
4605       Seems this should be named ``DW_CFA_offset_uf`` since the offset is
4610     The ``DW_CFA_offset_extended`` instruction takes two unsigned LEB128
4612     This instruction is identical to ``DW_CFA_offset``, except for the encoding
4613     and size of the register operand.
4617       Seems this should be named ``DW_CFA_offset_extended_uf`` since the
4622     The ``DW_CFA_offset_extended_sf`` instruction takes two operands: an
4629     The ``DW_CFA_val_offset`` instruction takes two unsigned LEB128 operands
4630     representing a register number R and a factored displacement B. The required
4631     action is to change the rule for the register indicated by R to be a
4636       Seems this should be named ``DW_CFA_val_offset_uf`` since the displacement
4641       An alternative is to define ``DW_CFA_val_offset`` to implicitly use the
4643       specifies the address space.
4647     The ``DW_CFA_val_offset_sf`` instruction takes two operands: an unsigned
4654     The ``DW_CFA_register`` instruction takes two unsigned LEB128 operands
4655     representing register numbers R1 and R2 respectively. The required action is
4656     to set the rule for the register specified by R1 to be a *register(R2)* rule.
4660     The ``DW_CFA_expression`` instruction takes two operands: an unsigned LEB128
4662     representing a DWARF operation expression E. The required action is to
4663     change the rule for the register specified by R to be an *expression(E)*
4666     *That is, E computes the location description where the register value can
4670     the DWARF expression operations that can be used in E.*
4674     The ``DW_CFA_val_expression`` instruction takes two operands: an unsigned
4676     representing a DWARF operation expression E. The required action is to
4677     change the rule for the register specified by R to be a *val_expression(E)*
4680     *That is, E computes the value of register R.*
4683     the DWARF expression operations that can be used in E.*
4685     If the result of evaluating E is not a value with a base type size that
4686     matches the register size, then the DWARF is ill-formed.
4690     The ``DW_CFA_restore`` instruction takes a single operand (encoded with the
4691     opcode) that represents a register number R. The required action is to
4692     change the rule for the register specified by R to the rule assigned it by
4693     the ``initial_instructions`` in the CIE.
4697     The ``DW_CFA_restore_extended`` instruction takes a single unsigned LEB128
4699     to ``DW_CFA_restore``, except for the encoding and size of the register
4707   These instructions are the same as in DWARF Version 5 section 6.4.2.4.
4714   These instructions are the same as in DWARF Version 5 section 6.4.2.5.
4721   The same as in DWARF Version 5 section 6.4.3.
4730   The same as in DWARF Version 5 section 6.4.4.
4738   attributes. These would be incorporated into the corresponding DWARF Version 5
4769 The following table gives the encoding of the additional debugging information
4795   The following modifies the matching text in DWARF Version 5 section 7.5.5.
4800       - The first type of reference...
4802       - The second type of reference can identify any debugging information
4804         entry in a different compilation unit from the unit containing the
4806         This type of reference (DW_FORM_ref_addr) is an offset from the
4807         beginning of the .debug_info section of the target executable or shared
4809         offset from the beginning of the local .debug_info section; it is
4811         executable or shared object file. In the 32-bit DWARF format, this
4812         offset is a 4-byte unsigned value; in the 64-bit DWARF format, it is an
4821         the reference is resolved by the debugger to identify the executable or
4822         shared object file and the offset into that file's* ``.debug_info``
4823         *section in the same fashion as the run time loader, either when the
4824         debug information is first read, or when the reference is used.*
4831   Rename DWARF Version 5 section 7.7 to reflect the unification of location
4839   Rename DWARF Version 5 section 7.7.1 and delete section 7.7.2 to reflect the
4845 A DWARF operation expression is stored in a block of contiguous bytes. The bytes
4847 that operation, followed by zero or more bytes of additional data. The encoding
4848 for the operation ``DW_OP_LLVM_user`` is described in
4849 :ref:`amdgpu-dwarf-operation-encodings-table`, and the encoding of all
4910 The following table gives the encoding of the additional DWARF languages.
4929 The value of the common address space encoding ``DW_ASPACE_LLVM_none`` is 0.
4939 The encodings of the constants used for the currently defined memory spaces
4964 The following table gives the encoding of the additional line number header
4986 The following table gives the encoding of the additional call frame information
5024 The following table provides the additional attributes that are applicable to
5063   This modifies the corresponding DWARF Version 5 Appendix D examples.
5072   A structure member is four bytes from the start of the structure instance. The
5073   location description of the base of the structure instance is assumed to be
5074   already on the stack.
5077   The address of the memory location is calculated by adding 16 to the value
5078   contained in register 5 upon entering the current subprogram.
5126   !  Note: for the m'th dimension, the second operator becomes
5131   !  That is, the expression does not get longer for each successive
5132   !  dimension (other than to express the larger offsets involved).
5182 Figure D.13: Sample DWARF for the array descriptor in Figure D.12
5205               !   Looks up the lower bound of dimension i.
5219               !   Looks up the upper bound of dimension i.
5231               !   Looks up the byte stride of dimension i.
5240   evaluate an exprloc with an initial stack containing the rank value. The
5304 The AMD GPU specific usage of the features in these extensions, including
5334 4.  [AMDGPU-DWARF-LOC] `Allow Location Descriptions on the DWARF Expression Stack <https://llvm.org/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.html>`__
5354 9.  [GCC] `GCC: The GNU Compiler Collection <https://www.gnu.org/software/gcc/>`__
5358 10. [GDB] `GDB: The GNU Project Debugger <https://www.gnu.org/software/gdb/>`__
5370 13. [LLVM] `The LLVM Compiler Infrastructure <https://llvm.org/>`__
5374 14. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__